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

[Mukesh Ojha]

Hi Vasant,

Thanks for your comment.

Changes will be sent in V5.

Regards,
Mukesh


On Thursday 04 August 2016 04:44 PM, Vasant Hegde wrote:
> 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
>