diff options
author | Vasant Hegde <hegdevasant@linux.vnet.ibm.com> | 2019-07-12 16:48:02 +0530 |
---|---|---|
committer | Oliver O'Halloran <oohall@gmail.com> | 2019-08-15 17:54:32 +1000 |
commit | 11cb51abfc46e3dde9f0e6ac001b36566a58521c (patch) | |
tree | 0d41ce88936c3bc7d85c489904521593ff5fc5dc /doc/opal-api | |
parent | 4ddf1144de419f26173a68b2a25989089e1c17ef (diff) | |
download | skiboot-11cb51abfc46e3dde9f0e6ac001b36566a58521c.zip skiboot-11cb51abfc46e3dde9f0e6ac001b36566a58521c.tar.gz skiboot-11cb51abfc46e3dde9f0e6ac001b36566a58521c.tar.bz2 |
MPIPL: Add documentation
Document MPIPL 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>
[oliver: rebased]
Signed-off-by: Oliver O'Halloran <oohall@gmail.com>
Diffstat (limited to 'doc/opal-api')
-rw-r--r-- | doc/opal-api/index.rst | 6 | ||||
-rw-r--r-- | doc/opal-api/opal-cec-reboot-6-116.rst | 2 | ||||
-rw-r--r-- | doc/opal-api/opal-mpipl-173-174.rst | 156 |
3 files changed, 164 insertions, 0 deletions
diff --git a/doc/opal-api/index.rst b/doc/opal-api/index.rst index b2fe942..96ce62a 100644 --- a/doc/opal-api/index.rst +++ b/doc/opal-api/index.rst @@ -384,6 +384,12 @@ 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_UPDATE` | 173 | Future, likely 6.4 | POWER9 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_MPIPL_REGISTER_TAG` | 174 | Future, likely 6.4 | POWER9 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_MPIPL_QUERY_TAG` | 175 | 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 9a5c794..431098f 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 0000000..fa27569 --- /dev/null +++ b/doc/opal-api/opal-mpipl-173-174.rst @@ -0,0 +1,156 @@ +.. _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 |