[Skiboot] [PATCH 040/110] doc: Make OPAL_ELOG_* pretty, mark OPAL_ELOG_WRITE unimplemented
Stewart Smith
stewart at linux.ibm.com
Fri May 31 16:12:41 AEST 2019
Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
doc/opal-api/index.rst | 3 +-
doc/opal-api/opal-elog-71-72-73-74-75.rst | 52 ++++++++++++++---------
2 files changed, 34 insertions(+), 21 deletions(-)
diff --git a/doc/opal-api/index.rst b/doc/opal-api/index.rst
index 65dcf10a870f..003014fb9703 100644
--- a/doc/opal-api/index.rst
+++ b/doc/opal-api/index.rst
@@ -155,7 +155,8 @@ The OPAL API is the interface between an Operating System and OPAL.
+---------------------------------------------+--------------+------------------------+----------+-----------------+
| :ref:`OPAL_ELOG_READ` | 71 | v1.0 (Initial Release) | POWER8 | |
+---------------------------------------------+--------------+------------------------+----------+-----------------+
-| :ref:`OPAL_ELOG_WRITE` | 72 | v1.0 (Initial Release) | POWER8 | |
+| :ref:`OPAL_ELOG_WRITE` | 72 | N/A | | Currently |
+| | | | | unused. |
+---------------------------------------------+--------------+------------------------+----------+-----------------+
| :ref:`OPAL_ELOG_ACK` | 73 | v1.0 (Initial Release) | POWER8 | |
+---------------------------------------------+--------------+------------------------+----------+-----------------+
diff --git a/doc/opal-api/opal-elog-71-72-73-74-75.rst b/doc/opal-api/opal-elog-71-72-73-74-75.rst
index 1e5212b5a34f..0326e284bf07 100644
--- a/doc/opal-api/opal-elog-71-72-73-74-75.rst
+++ b/doc/opal-api/opal-elog-71-72-73-74-75.rst
@@ -1,3 +1,5 @@
+.. _OPAL_ELOG:
+
OPAL_ELOG: Error logging
========================
@@ -8,7 +10,9 @@ by the service processor or OPAL in reaction to certain events. For example,
an IPL failure could be recorded in an error log, as could the reason and
details of an unexpected shut-down/reboot (e.g. hard thermal limits, check-stop).
-There are five OPAL calls from host to OPAL on error log: ::
+There are five OPAL calls from host to OPAL on error log:
+
+.. code-block:: c
#define OPAL_ELOG_READ 71
#define OPAL_ELOG_WRITE 72
@@ -16,21 +20,26 @@ There are five OPAL calls from host to OPAL on error log: ::
#define OPAL_ELOG_RESEND 74
#define OPAL_ELOG_SIZE 75
-Note: ``OPAL_ELOG_WRITE`` (72) Unused for now, can be used in future.
+.. _OPAL_ELOG_WRITE:
+
+Note: :ref:`OPAL_ELOG_WRITE` (72) Unused for now, might be supported in the
+future.
Not all platforms support these calls, so it's important for a host Operating
-System to use the OPAL_CHECK_TOKEN call first. If ``OPAL_ELOG_READ``,
-``OPAL_ELOG_ACK``, ``OPAL_ELOG_RESEND``, or ``OPAL_ELOG_SIZE`` is present,
-then the rest of that group is also present. The presence of ``OPAL_ELOG_WRITE``
+System to use the :ref:`OPAL_CHECK_TOKEN` call first. If :ref:`OPAL_ELOG_READ`,
+:ref:`OPAL_ELOG_ACK`, :ref:`OPAL_ELOG_RESEND`, or :ref:`OPAL_ELOG_SIZE` is present,
+then the rest of that group is also present. The presence of :ref:`OPAL_ELOG_WRITE`
must be checked separately.
**TODO**: we need a good explanation of the notification mechanism and in
what order and *when* to call each of the OPAL APIs.
+.. _OPAL_ELOG_READ:
+
OPAL_ELOG_READ
--------------
-The ``OPAL_ELOG_READ`` call will copy the error log identified by ``id`` into
+The :ref:`OPAL_ELOG_READ` call will copy the error log identified by ``id`` into
the ``buffer`` of size ``size``.
``OPAL_ELOG_READ`` accepts 3 parameters: ::
@@ -41,18 +50,20 @@ the ``buffer`` of size ``size``.
Returns:
-``OPAL_WRONG_STATE``
+:ref:`OPAL_WRONG_STATE`
When there are no error logs to read, or ``OPAL_ELOG`` calls are done in the
wrong order.
-``OPAL_PARAMETER``
+:ref:`OPAL_PARAMETER`
The ``id`` does not match the log id that is available.
-``OPAL_SUCCESS``
+:ref:`OPAL_SUCCESS`
Error log is copied to ``buffer``.
Other generic OPAL error codes may also be returned and should be treated
-like ``OPAL_INTERNAL_ERROR``.
+like :ref:`OPAL_INTERNAL_ERROR`.
+
+.. _OPAL_ELOG_ACK:
OPAL_ELOG_ACK
-------------
@@ -62,43 +73,44 @@ the host operating system has dealt with the error log successfully. This allows
OPAL and the service processor to delete the error log from their
memory/storage.
-``OPAL_ELOG_ACK`` accepts 1 parameter: ::
+:ref:`OPAL_ELOG_ACK` accepts 1 parameter: ::
uint64_t ack_id
Returns:
-``OPAL_INTERNAL_ERROR``
+:ref:`OPAL_INTERNAL_ERROR`
OPAL failed to send acknowledgement to the error log creator.
-
-``OPAL_SUCCESS``
+:ref:`OPAL_SUCCESS`
Success!
Other generic OPAL error codes may also be returned, and should be treated
-like ``OPAL_INTERNAL_ERROR``.
+like :ref:`OPAL_INTERNAL_ERROR`.
+.. _OPAL_ELOG_RESEND:
OPAL_ELOG_RESEND
----------------
-The ``OPAL_ELOG_RESEND`` call will cause OPAL to resend notification to the
+The :ref:`OPAL_ELOG_RESEND` call will cause OPAL to resend notification to the
host operating system of all outstanding error logs. This is commonly used
(although doesn't have to be) in a kexec scenario.
The call registered with this token accepts no parameter and returns type is
void.
+.. _OPAL_ELOG_SIZE:
OPAL_ELOG_SIZE
--------------
-The ``OPAL_ELOG_SIZE`` call retrieves information about an error log.
+The :ref:`OPAL_ELOG_SIZE` call retrieves information about an error log.
Here, ``type`` specifies error log format. Supported types are : ::
0 -> Platform Error Log
-``OPAL_ELOG_SIZE`` accepts 3 parameters: ::
+:ref:`OPAL_ELOG_SIZE` accepts 3 parameters: ::
uint64_t *elog_id
uint64_t *elog_size
@@ -106,10 +118,10 @@ Here, ``type`` specifies error log format. Supported types are : ::
Returns:
-``OPAL_WRONG_STATE``
+:ref:`OPAL_WRONG_STATE`
There is no error log to fetch information about.
-``OPAL_SUCCESS``
+:ref:`OPAL_SUCCESS`
Success.
Other general OPAL errors may be returned.
--
2.21.0
More information about the Skiboot
mailing list