[v3,17/18] fadump: Add documentation

Message ID 20180606053535.8855-18-hegdevasant@linux.vnet.ibm.com
State New
Headers show
Series
  • MPIPL support
Related show

Commit Message

Vasant Hegde June 6, 2018, 5:35 a.m.
Document fadump device tree and OPAL APIs.

Signed-off-by: Vasant Hegde <hegdevasant@linux.vnet.ibm.com>
Signed-off-by: Ananth N Mavinakayanahalli <ananth@linux.vnet.ibm.com>
---
 doc/device-tree/ibm,dump.rst            | 26 ++++++++++++
 doc/fadump.rst                          | 51 +++++++++++++++++++++++
 doc/index.rst                           |  1 +
 doc/opal-api/opal-cec-reboot-6-116.rst  |  2 +
 doc/opal-api/opal-fadump-manage-167.rst | 72 +++++++++++++++++++++++++++++++++
 5 files changed, 152 insertions(+)
 create mode 100644 doc/device-tree/ibm,dump.rst
 create mode 100644 doc/fadump.rst
 create mode 100644 doc/opal-api/opal-fadump-manage-167.rst

Patch

diff --git a/doc/device-tree/ibm,dump.rst b/doc/device-tree/ibm,dump.rst
new file mode 100644
index 000000000..055a68a16
--- /dev/null
+++ b/doc/device-tree/ibm,dump.rst
@@ -0,0 +1,26 @@ 
+.. _device-tree/ibm,dump:
+
+Fadump Device Tree Binding
+==========================
+
+See :ref:`fadump` for general fadump information.
+
+dump node
+---------
+.. code-block:: dts
+
+	ibm,dump {
+                /* Architected register data format version */
+		cpu-data-version = <0x10>;
+                /*
+                 * This property tells memory reserved by OPAL for OPAL dump.
+                 * We use `fadump` structure to pass reservation details to
+                 * Linux kernel.
+                 */
+		fw-source-table = <0x280001 0x0 0x3000000 0x0 0x0 0x30000000 0x0 0x5f10000 0x0 0x71e10000 0x0 0x5f10000>;
+                /* 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-v1";
+		phandle = <0x98>;
+	};
diff --git a/doc/fadump.rst b/doc/fadump.rst
new file mode 100644
index 000000000..520e89e8b
--- /dev/null
+++ b/doc/fadump.rst
@@ -0,0 +1,51 @@ 
+.. _fadump:
+
+FADUMP (aka MPIPL) 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_FADUMP_MANAGE API (see
+:ref:`opal-api-fadump-manage`).
+
+Early OPAL crash
+----------------
+We hardcode OPAL memory ranges and destination memory in the HDAT. So that we
+can capture early OPAL crash dump.
+
+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/S1 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,dump``) to pass dump details to Linux
+kernel from OPAL (see :ref:`device-tree/ibm,dump`).
diff --git a/doc/index.rst b/doc/index.rst
index 660085e05..c54fd01c4 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -45,6 +45,7 @@  Developer Guide and Internals
    xscom-node-bindings
    xive
    imc
+   fadump
 
 
 OPAL ABI
diff --git a/doc/opal-api/opal-cec-reboot-6-116.rst b/doc/opal-api/opal-cec-reboot-6-116.rst
index 11cf54aa1..ae14053f5 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-fadump-manage-167.rst b/doc/opal-api/opal-fadump-manage-167.rst
new file mode 100644
index 000000000..6308abe29
--- /dev/null
+++ b/doc/opal-api/opal-fadump-manage-167.rst
@@ -0,0 +1,72 @@ 
+.. _opal-api-fadump-manage:
+
+OPAL fadump manage call
+=======================
+::
+
+   #define OPAL_FADUMP_MANAGE                      167
+
+This call is used to manage FADUMP (aka MPIPL) on OPAL platform.
+Linux kernel will use this call to register/unregister FADUMP.
+
+Parameters
+----------
+::
+
+   uint64_t command
+   void *data
+   uint64_t dsize
+
+``command``
+   ``command`` parameter supports below values:
+
+::
+
+      0x01 - Register for fadump
+      0x02 - Unregister fadump
+      0x03 - Invalidate existing fadump
+
+``data``
+   ``data`` is valid when ``command`` is 0x01 (registration).
+   We use fadump structure (see below) to pass Linux kernel
+   memory reservation details.
+
+::
+
+
+   struct fadump_section {
+	u8	source_type;
+	u8	reserved[7];
+	u64	source_addr;
+	u64	source_size;
+	u64	dest_addr;
+	u64	dest_size;
+   } __packed;
+
+   struct fadump {
+	u16	fadump_section_size;
+	u16	section_count;
+	u32	reserved;
+	struct	fadump_section section[];
+   };
+
+``dsize``
+   Size of the data
+
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+  Operation success
+
+``OPAL_PARAMETER``
+  Invalid ``command`` or ``data`` or ``dsize``
+
+``OPAL_RESOURCE``
+  Ran out of space in MDST/MDDT table to add new entry
+
+``OPAL_PERMISSION``
+  Already registered
+
+``OPAL_HARDWARE``
+  Platform does not support fadump