diff mbox

[v12,10/10] skiboot: Add documentation for IMC opal call

Message ID 1495379407-6658-11-git-send-email-maddy@linux.vnet.ibm.com
State Superseded
Headers show

Commit Message

maddy May 21, 2017, 3:10 p.m. UTC 
From: Anju T Sudhakar <anju@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, u64 cpu_pir)
	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@linux.vnet.ibm.com>
Signed-off-by: Madhavan Srinivasan <maddy@linux.vnet.ibm.com>
---
 doc/opal-api/opal-imc-counters.rst | 67 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 doc/opal-api/opal-imc-counters.rst

Comments

Michael Neuling June 14, 2017, 5:06 a.m. UTC | #1 
> OPAL_IMC_COUNTERS_INIT
> +==============================
> +OPAL call interface to initialize In-memory collection
> +infrastructure. Call does multiple scom writes on each
> +incavation for Core IMC initialization. And for the
> +Nest IMC, at this point, call is a no-op and returns
> +OPAL_SUCCESS.

So why doesn't skiboot do this itself?  

What happens on kexec where init() has already been called by the first kernel? 
Wouldn't that be similar to skiboot doing it itself?

> +
> +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.
> +
> +``uint64_t cpu_pir``
> +  This parameter specifices target cpu pir
> +
> +Returns
> +-------
> +OPAL_PARAMETER - In case of  unsupported ``type``
> +OPAL_HARDWARE  - If any error in setting up the hardware.
> +OPAL_SUCCESS   - On succesfully initialized or even if init operation is a
> no-op.
> +
> +
> +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'

How do I know if this is going to work?  

What happens on the next generation where we have OPAL_IMC_COUNTERS_PONY?  How
do we know skiboot supports that call?

> +
> +Returns
> +-------
> +OPAL_PARAMETER - In case of  Unsupported ``type``
> +OPAL_HARDWARE  - If any error in setting up the hardware.
> +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).
> +STOP should always be called after a related START.
> +While STOP *may* run successfully without an associated
> +START call, this is not gaurenteed.
> +
> +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 any error in setting up the hardware.
> +OPAL_SUCCESS   - On successful execution of the operation for the given
> ``type``.
diff mbox

Patch

diff --git a/doc/opal-api/opal-imc-counters.rst b/doc/opal-api/opal-imc-counters.rst
new file mode 100644
index 000000000000..cda2a3bddf2c
--- /dev/null
+++ b/doc/opal-api/opal-imc-counters.rst
@@ -0,0 +1,67 @@ 
+OPAL_IMC_COUNTERS_INIT
+==============================
+OPAL call interface to initialize In-memory collection
+infrastructure. Call does multiple scom writes on each
+incavation for Core IMC initialization. And for the
+Nest IMC, at this point, call is a no-op and returns
+OPAL_SUCCESS.
+
+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.
+
+``uint64_t cpu_pir``
+  This parameter specifices target cpu pir
+
+Returns
+-------
+OPAL_PARAMETER - In case of  unsupported ``type``
+OPAL_HARDWARE  - If any error in setting up the hardware.
+OPAL_SUCCESS   - On succesfully initialized or even if init operation is a no-op.
+
+
+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 any error in setting up the hardware.
+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).
+STOP should always be called after a related START.
+While STOP *may* run successfully without an associated
+START call, this is not gaurenteed.
+
+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 any error in setting up the hardware.
+OPAL_SUCCESS   - On successful execution of the operation for the given ``type``.