diff options
| -rw-r--r-- | doc/opal-api/opal-elog-71-72-73-74-75.rst | 135 |
1 files 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. |