.. _opal-imc-counters:

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. Incase of kexec, OS driver should first
stop the engine via OPAL_IMC_COUNTER_STOP(and then
free the memory if allocated, for nest memory is
mmapped). Incase of kdump, OS driver should stop
the engine via OPAL_IMC_COUNTER_STOP.

OPAL does sanity checks to detect unknown or
unsupported IMC device type and nest units.
check_imc_device_type() function removes
unsupported IMC device type. disable_unavailable_units()
removes unsupported nest units by the microcode.
This way OPAL can lock down and advertise only
supported device type and nest units.

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'

``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 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'

``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 successful execution of the operation for the given ``type``.

Add documentation for IMC opal call
skiboot: Add documentation for IMC opal call

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, u64 cpu_pir)
	opal_imc_counters_stop(int Domain, u64 cpu_pir)

Document details the input parameters and return values.

Acked-by: Michael Neuling <7b0ab45a730e48a69239010b5b8fe5fa4e8eaac6@neuling.org>
Signed-off-by: Anju T Sudhakar <e8c8e1f4d2d74e058c71d5cc0f36846d7866f919@linux.vnet.ibm.com>
Signed-off-by: Madhavan Srinivasan <50c9fed97c2a760bbf32e7fdccf39ca6a997eabd@linux.vnet.ibm.com>
Signed-off-by: Stewart Smith <ec31ab75ddf977353c8f660f92ea8b23f64aef25@linux.vnet.ibm.com>
