[Skiboot] [PATCH v7 18/22] fadump: Add documentation
Vasant Hegde
hegdevasant at linux.vnet.ibm.com
Sat Apr 13 19:15:44 AEST 2019
Document fadump 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 | 33 +++++++++++++++
doc/fadump.rst | 51 +++++++++++++++++++++++
doc/index.rst | 1 +
doc/opal-api/opal-cec-reboot-6-116.rst | 2 +
doc/opal-api/opal-fadump-manage-173.rst | 73 +++++++++++++++++++++++++++++++++
5 files changed, 160 insertions(+)
create mode 100644 doc/device-tree/ibm,opal/dump.rst
create mode 100644 doc/fadump.rst
create mode 100644 doc/opal-api/opal-fadump-manage-173.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..a5145cf73
--- /dev/null
+++ b/doc/device-tree/ibm,opal/dump.rst
@@ -0,0 +1,33 @@
+.. _device-tree/ibm,opal/dump:
+
+Fadump Device Tree Binding
+==========================
+
+See :ref:`fadump` for general fadump information.
+
+dump node
+---------
+.. code-block:: dts
+
+ dump {
+ /* Architected register data format version */
+ cpu-data-version = <0x1>;
+ /*
+ * 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";
+ phandle = <0x98>;
+ /*
+ * This property contains captured dump details. This property
+ * exists only when we have dump.
+ */
+ result-table = <0x280002 0x0 0x3000000 0x0 0x0 0x30000000 0x0 0x5f10000 0x0 0x71e10000 0x0 0x5f10000 0x0 0x0 0x0 0x3165a558 0x0 0x34800 0x0 0x3165a558 0x0 0x34800>;
+ /* Each thread architected register data size */
+ cpu-data-size = <0x600>;
+ };
diff --git a/doc/fadump.rst b/doc/fadump.rst
new file mode 100644
index 000000000..a704c72cd
--- /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 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/index.rst b/doc/index.rst
index b7a868c96..9f154a275 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -46,6 +46,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 9ac7f9f69..8b332c880 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-173.rst b/doc/opal-api/opal-fadump-manage-173.rst
new file mode 100644
index 000000000..916167503
--- /dev/null
+++ b/doc/opal-api/opal-fadump-manage-173.rst
@@ -0,0 +1,73 @@
+.. _opal-api-fadump-manage:
+
+OPAL fadump manage call
+=======================
+::
+
+ #define OPAL_FADUMP_MANAGE 173
+
+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 crashing_cpu;
+ u64 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
--
2.14.3
More information about the Skiboot
mailing list