[Skiboot] [PATCH V4] doc/opal-api : Document opal-api's related to error log

[Vasant Hegde]

On 07/18/2016 11:49 AM, Mukesh Ojha wrote:
> It documents opal-api's related to error log.
> OPAL_ELOG_READ          71
> OPAL_ELOG_WRITE         72(UNUSED)
> OPAL_ELOG_ACK           73
> OPAL_ELOG_RESEND        74
> OPAL_ELOG_SIZE          75
>

Mukesh,

Recently Stewart converted plain text documentation to sphinx (.rst) format. 
Please convert this document as well and repost.

> Signed-off-by: Mukesh Ojha <mukesh02 at linux.vnet.ibm.com>
> ---
> Changes in V4:
>   - Adds little detail about error log type format.
>   - Changes related Vasant's review.
>
> Changes in V3:
>   - It takes care of the comment made by Vasant.
>
> Changes in V2:
>   - As per the discussion with Stewart offline, This patch adds examples
>     and the usage of the api's from the host kernel.
>
>   doc/opal-api/opal-elog-71-72-73-74-75.txt | 120 ++++++++++++++++++++++++++++++
>   1 file changed, 120 insertions(+)
>   create mode 100644 doc/opal-api/opal-elog-71-72-73-74-75.txt
>
> diff --git a/doc/opal-api/opal-elog-71-72-73-74-75.txt b/doc/opal-api/opal-elog-71-72-73-74-75.txt
> new file mode 100644
> index 0000000..f955be3
> --- /dev/null
> +++ b/doc/opal-api/opal-elog-71-72-73-74-75.txt
> @@ -0,0 +1,120 @@
> +Error logging API's description:
> +=======================================
> +
> +There are five OPAL calls from host to OPAL on error log:
> +
> +#define OPAL_ELOG_READ         71
> +#define OPAL_ELOG_WRITE        72
> +#define OPAL_ELOG_ACK          73
> +#define OPAL_ELOG_RESEND       74
> +#define OPAL_ELOG_SIZE         75
> +
> +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.
> +<Snippet>:
> +	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;
> +		}
> +	}
> +
> +
> +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.
> +
> +OPAL_ELOG_READ accepts 3 parameters:
> +- elog buffer
> +- elog size
> +- elog id
> +
> +The call registered with this token returns OPAL_WRONG_STATE, when read
> +state of state machine is not in 'ELOG_STATE_FETCHED_DATA' or errorlog read
> +pending list is empty.
> +
> +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.
> +
> +It returns OPAL_SUCCESS on successfully copying the errorlog data to the passed

better "error log"

> +buffer.
> +
> +
> +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.
> +
> +OPAL_ELOG_ACK accepts 1 parameter::
> +- ack id
> +
> +In case of opal error logs, for the passed ack_id the corresponding node is
> +returned to the pool of free object.
> +
> +The call registered with this token returns OPAL_INTERNAL_ERROR on failure to
> +send acknowledgement to the FSP and OPAL_SUCCESS on success.

Today its FSP. tomorrow it may be some other backend. So better s/FSP/error log 
creator/

> +
> +
> +OPAL_ELOG_RESEND
> +================
> +
> +This token is used to register a call which will resend all the error logs
> +again to newly loaded kernel.
> +
> +The call registered with this token accepts no parameter and returns type is
> +void.
> +
> +
> +OPAL_ELOG_SIZE
> +==============
> +
> +This token is used to register a call which will fill information about the
> +errorlog like id, size and type. Here, 'type' is the format in which logs
> +are documented e.g PEL(Platform Error Log) is one of the type of error log
> +format.

Add something like below,

Here 'type' specifies error log format. Supported types are :

   0 -> Platform Error Log.

-Vasant