[Skiboot] [PATCH] doc/opal-api/opal-elog: heavily rework error log documentation
Stewart Smith
stewart at linux.vnet.ibm.com
Wed Aug 10 15:15:26 AEST 2016
Signed-off-by: Stewart Smith <stewart at linux.vnet.ibm.com>
---
doc/opal-api/opal-elog-71-72-73-74-75.rst | 135 ++++++++++++++----------------
1 file changed, 62 insertions(+), 73 deletions(-)
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 3543ba4..1e5212b 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,5 +1,12 @@
-Error logging API's description:
-================================
+OPAL_ELOG: Error logging
+========================
+
+OPAL provides an abstraction to platform specific methods of storing and
+retrieving error logs. Some service processors may be able to store information
+in the Platform Error Log (PEL) format. These may be generated at runtime
+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: ::
@@ -11,92 +18,72 @@ There are five OPAL calls from host to OPAL on error log: ::
Note: ``OPAL_ELOG_WRITE`` (72) Unused for now, can be used in future.
-Host kernel define macros for the call with the above tokens.
-e.g. ::
-
- OPAL_CALL(opal_read_elog, OPAL_ELOG_READ);
- OPAL_CALL(opal_send_ack_elog, OPAL_ELOG_ACK);
- OPAL_CALL(opal_get_elog_size, OPAL_ELOG_SIZE);
- OPAL_CALL(opal_resend_pending_logs, OPAL_ELOG_RESEND);
-
-And OPAL also register interfaces for the above tokens.
-e.g. ::
-
- opal_register(OPAL_ELOG_READ, fsp_opal_elog_read, 3);
- opal_register(OPAL_ELOG_ACK, fsp_opal_elog_ack, 1);
- opal_register(OPAL_ELOG_RESEND, fsp_opal_resend_pending_logs, 0);
- opal_register(OPAL_ELOG_SIZE, fsp_opal_elog_info, 3);
-
-Numbers in the above example are the number of parameter(e.g. 3) the callback
-(e.g. ``fsp_opal_elog_read``) accepts.
-
-So, a call to any of the above api's(``opal_read_elog``) in the host kernel will
-call the corresponding interface(``fsp_opal_elog_read``) in the OPAL.
-
-e.g. Below is the example of one of the call from the host kernel. ::
-
- elog->id = id;
- elog->size = size;
- elog->type = type;
- elog->buffer = kzalloc(elog->size, GFP_KERNEL);
-
- if (elog->buffer) {
- rc = opal_read_elog(__pa(elog->buffer),
- elog->size, elog->id);
- if (rc != OPAL_SUCCESS) {
- pr_err("ELOG: log read failed for log-id=%llx\n",
- elog->id);
- kfree(elog->buffer);
- elog->buffer = NULL;
- }
- }
+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``
+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
--------------
-This token is used to register a call which will copy the error log content to
-the passed buffer with the passed ``elog id`` and ``elog size`` from the host
-kernel.
+The ``OPAL_ELOG_READ`` call will copy the error log identified by ``id`` into
+the ``buffer`` of size ``size``.
``OPAL_ELOG_READ`` accepts 3 parameters: ::
- uint64_t elog buffer
- uint64_t elog size
- uint64_t elog id
+ uint64_t *elog_buffer
+ uint64_t elog_size
+ uint64_t elog_id
+
+Returns:
-The call registered with this token returns ``OPAL_WRONG_STATE``, when read
-state of state machine is not in ``ELOG_STATE_FETCHED_DATA`` or error log read
-pending list is empty.
+``OPAL_WRONG_STATE``
+ When there are no error logs to read, or ``OPAL_ELOG`` calls are done in the
+ wrong order.
-It returns ``OPAL_PARAMETER``, when passed log id is not the same as log id of the
-top node in the elog_read_pending list and ``OPAL_SUCCESS`` on successfully copying
-the error log data to the passed buffer.
+``OPAL_PARAMETER``
+ The ``id`` does not match the log id that is available.
+``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``.
OPAL_ELOG_ACK
-------------
-This token is used to register a call which acknowledges the passed ``ack_id``
-(elog_id) which in turn sends a acknowledgement to the error log source and
-move the acknowledge elog id from processed list to the read free list.
+Acknowledging (ACKing) an error log tells OPAL and the service processor that
+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: ::
- uint64_t ack id
+ uint64_t ack_id
+
+Returns:
-In case of OPAL error logs, for the passed ``ack_id`` the corresponding node is
-returned to the pool of free object.
+``OPAL_INTERNAL_ERROR``
+ OPAL failed to send acknowledgement to the error log creator.
-The call registered with this token returns ``OPAL_INTERNAL_ERROR`` on failure to
-send acknowledgement to the error log creator and ``OPAL_SUCCESS`` on success.
+``OPAL_SUCCESS``
+ Success!
+
+Other generic OPAL error codes may also be returned, and should be treated
+like ``OPAL_INTERNAL_ERROR``.
OPAL_ELOG_RESEND
----------------
-This token is used to register a call which will resend all the error logs
-again to newly loaded kernel.
+The ``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.
@@ -105,8 +92,7 @@ void.
OPAL_ELOG_SIZE
--------------
-This token is used to register a call which will fill information about the
-error log like id, size and type.
+The ``OPAL_ELOG_SIZE`` call retrieves information about an error log.
Here, ``type`` specifies error log format. Supported types are : ::
@@ -114,13 +100,16 @@ Here, ``type`` specifies error log format. Supported types are : ::
``OPAL_ELOG_SIZE`` accepts 3 parameters: ::
- uint64_t elog ID
- uint64_t elog size
- uint64_t type
+ uint64_t *elog_id
+ uint64_t *elog_size
+ uint64_t *elog_type
+
+Returns:
+
+``OPAL_WRONG_STATE``
+ There is no error log to fetch information about.
-The call registered with this token returns ``OPAL_WRONG_STATE``, when read
-state of state machine is not in ``ELOG_STATE_FETCHED_DATA`` or error log read
-pending list is empty.
+``OPAL_SUCCESS``
+ Success.
-It returns ``OPAL_SUCCESS`` on successfully filling up the error log information
-in passed parameters.
+Other general OPAL errors may be returned.
--
2.7.4
More information about the Skiboot
mailing list