1 files changed, 157 insertions, 0 deletions
diff --git a/roms/skiboot/doc/opal-api/opal-mpipl-173-174.rst b/roms/skiboot/doc/opal-api/opal-mpipl-173-174.rst
new file mode 100644
index 000000000..32e64e375
--- /dev/null
+++ b/roms/skiboot/doc/opal-api/opal-mpipl-173-174.rst
@@ -0,0 +1,157 @@
+.. _opal-api-mpipl:
+
+OPAL MPIPL APIs
+===============
+
+.. code-block:: c
+
+   #define OPAL_MPIPL_UPDATE                      173
+   #define OPAL_MPIPL_REGISTER_TAG                174
+   #define OPAL_MPIPL_QUERY_TAG                   175
+
+These calls are used for MPIPL (Memory Preserving Initial Program Load).
+
+It is an OPTIONAL part of the OPAL spec.
+
+If a platform supports MPIPL, then we will have "/ibm,opal/dump" node in
+device tree (see :ref:`device-tree/ibm,opal/dump`).
+
+.. _OPAL_MPIPL_UPDATE:
+
+OPAL_MPIPL_UPDATE
+==================
+Linux kernel will use this call to register/unregister MPIPL.
+
+.. code-block:: c
+
+   #define OPAL_MPIPL_UPDATE                      173
+
+   int64_t opal_mpipl_update(enum mpipl_ops ops, u64 src, u64 dest, u64 size)
+
+   /* MPIPL update operations */
+   enum mpipl_ops {
+        OPAL_MPIPL_ADD_RANGE            = 0,
+        OPAL_MPIPL_REMOVE_RANGE         = 1,
+        OPAL_MPIPL_REMOVE_ALL           = 2,
+        OPAL_MPIPL_FREE_PRESERVED_MEMORY= 3,
+   };
+
+ops :
+-----
+  OPAL_MPIPL_ADD_RANGE
+    Add new entry to MPIPL table. Kernel will send src, dest and size.
+    During MPIPL content from source address is moved to destination address.
+    src  = Source start address
+    dest = Destination start address
+    size = size
+
+  OPAL_MPIPL_REMOVE_RANGE
+    Remove kernel requested entry from MPIPL table.
+    src  = Source start address
+    dest = Destination start address
+    size = ignore
+
+  OPAL_MPIPL_REMOVE_ALL
+    Remove all kernel passed entry from MPIPL table.
+    src  = ignore
+    dest = ignore
+    size = ignore
+
+  OPAL_MPIPL_FREE_PRESERVED_MEMORY
+    Post MPIPL, kernel will indicate OPAL that it has processed dump and
+    it can clear/release metadata area.
+    src  = ignore
+    dest = ignore
+    size = ignore
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+  Operation success
+
+``OPAL_PARAMETER``
+  Invalid parameter
+
+``OPAL_RESOURCE``
+  Ran out of space in MDST/MDDT table to add new entry
+
+``OPAL_HARDWARE``
+  Platform does not support fadump
+
+
+.. _OPAL_MPIPL_REGISTER_TAG:
+
+OPAL_MPIPL_REGISTER_TAG
+=======================
+Kernel will use this API to register tags during MPIPL registration.
+It expects OPAL to preserve these tags across MPIPL. Post MPIPL Linux
+kernel will use `opal_mpipl_query_tag` call to retrieve these tags.
+
+.. code-block:: c
+
+  opal_mpipl_register_tag(enum opal_mpipl_tags tag, uint64_t tag_val)
+
+  tag:
+   OPAL_MPIPL_TAG_KERNEL
+     During first boot, kernel will setup its metadata area and asks
+     OPAL to preserve metadata area pointer across MPIPL. Post MPIPL
+     kernel requests OPAL to provide metadata pointer and it will use
+     that pointer to retrieve metadata and create dump.
+
+   OPAL_MPIPL_TAG_BOOT_MEM
+     During MPIPL registration kernel will specify how much memory
+     firmware can use for Post MPIPL load. Post MPIPL petitboot kernel
+     will query for this tag to get boot memory size.
+
+Return Values
+-------------
+``OPAL_SUCCESS``
+  Operation success
+
+``OPAL_PARAMETER``
+  Invalid parameter
+
+.. _OPAL_MPIPL_QUERY_TAG:
+
+OPAL_MPIPL_QUERY_TAG
+====================
+Post MPIPL linux kernel will call this API to get metadata tag. And use this
+tag to retrieve metadata information and generate dump.
+
+.. code-block:: c
+
+   #define OPAL_MPIPL_QUERY_TAG                 175
+
+   uint64_t opal_mpipl_query_tag(enum opal_mpipl_tags tag, uint64_t *tag_val)
+
+   enum opal_mpipl_tags {
+        OPAL_MPIPL_TAG_CPU      = 0,
+        OPAL_MPIPL_TAG_OPAL     = 1,
+        OPAL_MPIPL_TAG_KERNEL   = 2,
+        OPAL_MPIPL_TAG_BOOT_MEM = 3,
+   };
+
+  tag :
+     OPAL_MPIPL_TAG_CPU
+       Pointer to CPU register data content metadata area
+     OPAL_MPIPL_TAG_OPAL
+       Pointer to OPAL metadata area
+     OPAL_MPIPL_TAG_KERNEL
+       During first boot, kernel will setup its metadata area and asks
+       OPAL to preserve metadata area pointer across MPIPL. Post MPIPL
+       kernel calls this API to get metadata pointer and it will use
+       that pointer to retrieve metadata and create dump.
+     OPAL_MPIPL_TAG_BOOT_MEM
+       During MPIPL registration kernel will specify how much memory
+       firmware can use for Post MPIPL load. Post MPIPL petitboot kernel
+       will query for this tag to get boot memory size.
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+  Operation success
+
+``OPAL_PARAMETER``
+  Invalid parameter