[Skiboot] [PATCH v8 24/24] MPIPL: Add documentation
Vasant Hegde
hegdevasant at linux.vnet.ibm.com
Mon Jun 17 03:10:24 AEST 2019
Document MPIPL device tree and OPAL APIs.
Signed-off-by: Vasant Hegde <hegdevasant at linux.vnet.ibm.com>
Signed-off-by: Ananth N Mavinakayanahalli <ananth at linux.vnet.ibm.com>
---
doc/device-tree/ibm,opal/dump.rst | 23 +++++++
doc/index.rst | 1 +
doc/mpipl.rst | 46 +++++++++++++
doc/opal-api/index.rst | 4 ++
doc/opal-api/opal-cec-reboot-6-116.rst | 2 +
doc/opal-api/opal-mpipl-173-174.rst | 119 +++++++++++++++++++++++++++++++++
6 files changed, 195 insertions(+)
create mode 100644 doc/device-tree/ibm,opal/dump.rst
create mode 100644 doc/mpipl.rst
create mode 100644 doc/opal-api/opal-mpipl-173-174.rst
diff --git a/doc/device-tree/ibm,opal/dump.rst b/doc/device-tree/ibm,opal/dump.rst
new file mode 100644
index 000000000..b2484966a
--- /dev/null
+++ b/doc/device-tree/ibm,opal/dump.rst
@@ -0,0 +1,23 @@
+.. _device-tree/ibm,opal/dump:
+
+Dump (MPIPL) Device Tree Binding
+=================================
+
+See :ref:`mpipl` for general MPIPL information.
+
+dump node
+---------
+.. code-block:: dts
+
+ dump {
+ /* Memory used by OPAL to load skiroot images */
+ fw-load-area = <0x0 0x20000000 0x0 0x8000000 0x0 0x28000000 0x0 0x8000000>;
+ /* Compatible property */
+ compatible = "ibm,opal-dump";
+ phandle = <0x98>;
+ /*
+ * This property indicates that its MPIPL boot. Kernel will use OPAL API
+ * to retrieve metadata tags and use metadata to create dump.
+ */
+ mpipl-boot
+ };
diff --git a/doc/index.rst b/doc/index.rst
index 79a5accf2..f21a658f9 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -47,6 +47,7 @@ Developer Guide and Internals
xive
imc
power-management
+ mpipl
OPAL ABI
diff --git a/doc/mpipl.rst b/doc/mpipl.rst
new file mode 100644
index 000000000..b994ebf93
--- /dev/null
+++ b/doc/mpipl.rst
@@ -0,0 +1,46 @@
+.. _mpipl:
+
+MPIPL (aka FADUMP) Overview
+===========================
+
+Memory Preserving Initial Program Load (MPIPL) is a Power feature where the
+contents of memory are preserved while the system reboots after a failure.
+This is accomplished by the firmware/OS publishing ranges of memory to be
+preserved across boots.
+
+Registration
+------------
+In the OPAL context, OPAL and host Linux communicate the memory ranges to be
+preserved via source descriptor tables in the HDAT (MDST and MDDT table inside
+SPIRAH). Host Linux can register/unregister using OPAL_MPIPL_UPDATE API (see
+:ref:`opal-api-mpipl`).
+
+Initiating dump
+---------------
+Whenever Linux crashes, it makes reboot2 OPAL call with type as MPIPL. (see
+:ref:`opal-api-cec-reboot`). Depending on sevice processor type OPAL makes
+appropriate call to initiate MPIPL. On FSP system we call `attn` instruction
+(see ``__trigger_attn()``) and on BMC system we call SBE `S0 interrupt`
+(see ``p9_sbe_terminate()``).
+
+Dump collection
+---------------
+Hostboot then re-IPLs the machine taking care to copy over contents of the
+source memory to a alternate memory locations as specified in descriptor table.
+Hostboot publishes this information in the destination descriptor tables (MDRT
+table inside SPIRAH structure). The success/failure of the copy is indicated
+by a results table.
+
+SBE/Hostboot also does the requisite procedures to gather hardware register
+states for all active threads at the time of the crash.
+
+MPIPL boot
+----------
+On an MPIPL boot, OPAL exports the results information to the host Linux kernel,
+which then uses its existing logic (kdump/fadump) to write out a core dump of
+OPAL and Linux kernel in a format that GDB and crash can understand.
+
+Device tree
+-----------
+We create new device tree node (``/ibm,opal/dump``) to pass dump details to Linux
+kernel from OPAL (see :ref:`device-tree/ibm,opal/dump`).
diff --git a/doc/opal-api/index.rst b/doc/opal-api/index.rst
index b2fe942c7..7fbbac001 100644
--- a/doc/opal-api/index.rst
+++ b/doc/opal-api/index.rst
@@ -384,6 +384,10 @@ The OPAL API is the interface between an Operating System and OPAL.
+---------------------------------------------+--------------+------------------------+----------+-----------------+
| :ref:`OPAL_NPU_MEM_RELEASE` | 172 | Future, likely 6.4 | | |
+---------------------------------------------+--------------+------------------------+----------+-----------------+
+| :ref:`OPAL_MPIPL_UPDATTE` | 173 | Future, likely 6.4 | POWER9 | |
++---------------------------------------------+--------------+------------------------+----------+-----------------+
+| :ref:`OPAL_MPIPL_QUERY_TAG` | 174 | Future, likely 6.4 | POWER9 | |
++---------------------------------------------+--------------+------------------------+----------+-----------------+
.. toctree::
:maxdepth: 1
diff --git a/doc/opal-api/opal-cec-reboot-6-116.rst b/doc/opal-api/opal-cec-reboot-6-116.rst
index d56f515ee..10ac01ab5 100644
--- a/doc/opal-api/opal-cec-reboot-6-116.rst
+++ b/doc/opal-api/opal-cec-reboot-6-116.rst
@@ -1,3 +1,5 @@
+.. _opal-api-cec-reboot:
+
OPAL_CEC_REBOOT and OPAL_CEC_REBOOT2
====================================
diff --git a/doc/opal-api/opal-mpipl-173-174.rst b/doc/opal-api/opal-mpipl-173-174.rst
new file mode 100644
index 000000000..2dc309e2a
--- /dev/null
+++ b/doc/opal-api/opal-mpipl-173-174.rst
@@ -0,0 +1,119 @@
+.. _opal-api-mpipl:
+
+OPAL MPIPL APIs
+===============
+
+.. code-block:: c
+
+ #define OPAL_MPIPL_UPDATE 173
+ #define OPAL_MPIPL_QUERY_TAG 174
+
+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_REGISTER_TAG = 0,
+ OPAL_MPIPL_ADD_RANGE = 1,
+ OPAL_MPIPL_REMOVE_RANGE = 2,
+ OPAL_MPIPL_REMOVE_ALL = 3,
+ OPAL_MPIPL_FREE_PRESERVED_MEMORY= 4,
+ };
+
+ops :
+-----
+ OPAL_MPIPL_REGISTER_TAG
+ Kernel metadata pointer. Kernel will send this to OPAL during MPIPL
+ registration. Post MPIPL, kernel will request for this tag via
+ opal_mpipl_query_tag API.
+ src = kernel metadata address
+ dest = ignore
+ size = ignore
+
+ 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_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 174
+
+ uint64_t opal_mpipl_query_tag(uint32_t idx, uint64_t *tag)
+
+ idx : tag index (0..n)
+ tag : OPAL will pass saved tag
+
+ Kernel will make this call with increased `index` until OPAL returns OPAL_EMPTY.
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+ Operation success
+
+``OPAL_PARAMETER``
+ Invalid parameter
+
+``OPAL_EMPTY``
+ OPAL completed sending all tags to kernel
--
2.14.3
More information about the Skiboot
mailing list