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

[Madhavan Srinivasan]

On Friday 12 May 2017 07:58 AM, Stewart Smith wrote:
> 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.

Yes. Will document it here.

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

Yes that is true. Also we did test kexec path multiple times
for all this three cases
1 )IMC kernel -> distro kernel (without IMC patchset)
2) distro kernel (without IMC Patchset) -> IMC kernel
3) IMC kernel -> IMC kernel.


>
> 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.

Yes. In the kernel patchset, we do have a check for the kdump
kernel before create IMC devices (in device probe function).
So that we dont _INIT in the kdump scenerio

https://lkml.org/lkml/2017/5/4/401

>> +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.

Ok sure. Will do

>
>> +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?

Currently we dont check whether the counters are started,
so STOP will succeed event there has not been a
corresponding START

Maddy