[Skiboot] [PATCH 4/4] doc/opal-api: opal_ipmi_recv

[Mukesh Ojha]

On Thursday 11 August 2016 10:31 AM, ppaidipe at linux.vnet.ibm.com wrote:
> From: Pridhiviraj Paidipeddi <ppaidipe at linux.vnet.ibm.com>
>
> This patch adds documentation for the opal call opal_ipmi_recv.
>
> Signed-off-by: Pridhiviraj Paidipeddi <ppaidipe at linux.vnet.ibm.com>
> ---
>   doc/opal-api/opal-ipmi-recv-108.rst | 52 +++++++++++++++++++++++++++++++++++++
>   1 file changed, 52 insertions(+)
>   create mode 100644 doc/opal-api/opal-ipmi-recv-108.rst
>
> diff --git a/doc/opal-api/opal-ipmi-recv-108.rst b/doc/opal-api/opal-ipmi-recv-108.rst
> new file mode 100644
> index 0000000..43946b0
> --- /dev/null
> +++ b/doc/opal-api/opal-ipmi-recv-108.rst
> @@ -0,0 +1,52 @@
> +OPAL_IPMI_RECV
> +==============
> +::
> +
> +   #define OPAL_IPMI_RECV                          108
> +
> +   int64_t opal_ipmi_recv(uint64_t interface,
> +                              struct opal_ipmi_msg *opal_ipmi_msg, uint64_t *msg_len)

We generally not mention the api name 'opal_ipmi_recv'.

> +
> +Arguments
> +---------
Let us be consistent by using 'Parameters' here.

> +::
> +
> +   uint64_t interface
> +   struct opal_ipmi_msg *opal_ipmi_msg
> +   uint64_t *msg_len
> +
> +``interface``
> +   ``interface`` parameter is the value from the ipmi interface node ``ibm,ipmi-interface-id``
> +
> +``opal_ipmi_msg``
> +   ``opal_ipmi_msg`` is the pointer to below structure ``opal_ipmi_msg``

After a above line , you could give a ::

> +   struct opal_ipmi_msg {
> +        uint8_t version;
> +        uint8_t netfn;
> +        uint8_t cmd;
> +        uint8_t data[];
> +   };
> +
> +``msg_len``
> +   ``msg_len`` is the pointer to ipmi message response size
> +
> +``OPAL_IPMI_RECV`` call reads an ipmi message of type ``ipmi_msg`` from ipmi message
> +queue ``msgq`` into host OS structure ``opal_ipmi_msg``.
> +
> +Return Values
> +-------------
> +
> +``OPAL_SUCCESS``
> +  ipmi message dequeued successfully from ``msgq`` queue and frees the ipmi_msg structure
s/ipmi_msg/``ipmi_msg``

Better to reframe it as : 'ipmi message dequeued from ``msgq`` queue and 
memory taken by it got released successfully'.

Cheers,
~Mukesh
> +
> +``OPAL_EMPTY``
> +  ``msgq`` list is empty
> +
> +``OPAL_PARAMETER``
> +  invalid ipmi ``interface`` value
> +
> +``OPAL_UNSUPPORTED``
> +  in-correct opal ipmi message format version ``opal_ipmi_msg->version``
> +
> +``OPAL_RESOURCE``
> +  invalid ipmi message length ``msg_len``