doc/opal-api/opal-elog: heavily rework error log documentation

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

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.