[Skiboot] [PATCH V2] doc/opal-api : Document opal-api's related to errorlog

[Vasant Hegde]

On 07/08/2016 02:30 PM, Mukesh Ojha wrote:
> It documents opal-api's related to errorlog.
> OPAL_ELOG_READ          71
> OPAL_ELOG_WRITE         72(UNUSED)
> OPAL_ELOG_ACK           73
> OPAL_ELOG_RESEND        74
> OPAL_ELOG_SIZE          75
>
> Signed-off-by: Mukesh Ojha <mukesh02 at linux.vnet.ibm.com>
>
> ---
> 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 | 119 ++++++++++++++++++++++++++++++
>   1 file changed, 119 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..f6f501b
> --- /dev/null
> +++ b/doc/opal-api/opal-elog-71-72-73-74-75.txt
> @@ -0,0 +1,119 @@
> +Error logging on FSP based machine:
> +----------------------------------
> +
> +There are five OPAL calls for errorlog on FSP based machine:

These are generic API's , not specific to FSP.  Presently only FSP based machine 
is using these API's.
Hence we don't need to mention FSP here.


> +
> +#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 register callbacks with the above tokens.

There is no registration in host.. All these API's are called by kernel. We can 
check given API is supported or not before calling.

> +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);
> +	OPAL_CALL(opal_write_elog,		OPAL_ELOG_WRITE);

I think we can remove above line as we are not using this API now .. I doubt we 
will use it anytime soon.

> +
> +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 corressponding interface(fsp_opal_elog_read) in the OPAL.

s/corressponding/corresponding/

> +
> +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 errorlog content to

Better "error log"

> +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
> +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 FSP and move the

s/acknowledgement/acknowledgment/

Also s/FSP/service processor/   -OR- just say ...to error log source.


> +acknowledge elog id from processed list to the read free list.
> +
> +OPAL_ELOG_ACK accepts 1 parameter::
> +- ack id
> +
> +In case of opal errorlogs, 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 acknowledement to the FSP and OPAL_SUCCESS on success.
> +
> +
> +OPAL_ELOG_RESEND
> +----------------
> +
> +This token is used to register a call which will resend all the elogs again to

error log

> +new kexec kernel.

We can resend all the error log anytime, not just new kexec kernel. Today we 
make this call from
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.
> +
> +OPAL_ELOG_SIZE accepts 3 parameters:
> +- elog ID
> +- elog size
> +- elog type
> +


We have type field so that these API"s can support multiple error log format. 
today its PEL format.

Hence document type field here.


-Vasant