[Skiboot] [PATCH v11 11/11] skiboot: Add documentation for IMC opal call

[Stewart Smith]

Madhavan Srinivasan <maddy at linux.vnet.ibm.com> writes:
> From: Anju T Sudhakar <anju at linux.vnet.ibm.com>
>
> Add documentation for new OPAL Call APIs added for
> In Memory Collection(IMC) infrastructure. Three new
> OPAL Call APIs are added and they are
> 	opal_imc_counters_init(int Domain, u64 address)
> 	opal_imc_counters_start(int Domain)
> 	opal_imc_counters_stop(int Domain)
>
> Document details the input parameters and return values.
>
> Signed-off-by: Anju T Sudhakar <anju at linux.vnet.ibm.com>
> Signed-off-by: Madhavan Srinivasan <maddy at linux.vnet.ibm.com>
> ---
>  doc/opal-api/opal-imc-counters.rst | 60 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 60 insertions(+)
>  create mode 100644 doc/opal-api/opal-imc-counters.rst
>
> diff --git a/doc/opal-api/opal-imc-counters.rst b/doc/opal-api/opal-imc-counters.rst
> new file mode 100644
> index 000000000000..63830a7b52cd
> --- /dev/null
> +++ b/doc/opal-api/opal-imc-counters.rst
> @@ -0,0 +1,60 @@
> +OPAL_IMC_COUNTERS_INIT
> +==============================
> +OPAL call interface to initialize In-memory collection
> +infrastructure. This call support initialization of only
> +Core IMC type for now.

As mentioned elsewhere, I think this call should return OPAL_SUCCESS for
any supported counter type, even if the init operation is a no-op.

What's the behaviour over kexec? Calling _INIT multiple times is
harmless as long as no counters of that class are started?

This would imply that in a kdump scenario, the kdump kernel should *not*
init IMC counters, but in a normal kexec/boot scenario, it's safe to.

> +Parameters
> +----------
> +``uint32_t type``
> + This parameter specifies the imc counter domain.
> + The value should be 'OPAL_IMC_COUNTERS_CORE'
> +
> +``uint64_t addr``
> +  This parameter must have a non-zero value.
> +  This value must be a physical address of the core.
> +
> +
> +Returns
> +-------
> +OPAL_PARAMETER - In case of  unsupported ``type``
> +OPAL_HARDWARE  - If xscom_write fails.

OPAL_HARDWARE could be for other errors, so just say it's for any error
in setting up the hardware.

> +OPAL_SUCCESS   - When core counters are succesfully initialized.
> +
> +
> +OPAL_IMC_COUNTERS_START
> +============================
> +OPAL call interface for starting the In-Memory Collection
> +counters for a specified domain (NEST/CORE).
> +
> +Parameters
> +----------
> +``uint32_t type``
> + This parameter specifies the imc counter domain.
> + The value can be either 'OPAL_IMC_COUNTERS_NEST'
> + or 'OPAL_IMC_COUNTERS_CORE'
> +
> +Returns
> +-------
> +OPAL_PARAMETER - In case of  Unsupported ``type``
> +OPAL_HARDWARE  - If xscom_write fails.
> +OPAL_SUCCESS   - On successful execution of the operation for the given ``type``.
> +
> +
> +OPAL_IMC_COUNTERS_STOP
> +===========================
> +OPAL call interface for stoping In-Memory
> +Collection counters for a specified domain (NEST/CORE).
> +
> +Parameters
> +----------
> +``uint32_t type``
> + This parameter specifies the imc counter domain.
> + The value can be either 'OPAL_IMC_COUNTERS_NEST'
> + or 'OPAL_IMC_COUNTERS_CORE'
> +
> +Returns
> +-------
> +OPAL_PARAMETER - In case of  Unsupported ``type``
> +OPAL_HARDWARE  - If xscom_write fails.
> +OPAL_SUCCESS   - On successful execution of the operation for the given ``type``.

Will stop succeed if there has not been a corresponding START?

-- 
Stewart Smith
OPAL Architect, IBM.