[Skiboot] [PATCH v11 01/11] skiboot/doc: Add doc/imc.rst documentation

[Stewart Smith]

Madhavan Srinivasan <maddy at linux.vnet.ibm.com> writes:
> Add imc.rst documentation to detail the In-Memory Collection
> Counters infrastructure and interface
>
> Signed-off-by: Madhavan Srinivasan <maddy at linux.vnet.ibm.com>
> ---
>  doc/imc.rst   | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  doc/index.rst |  1 +
>  2 files changed, 54 insertions(+)
>  create mode 100644 doc/imc.rst
>
> diff --git a/doc/imc.rst b/doc/imc.rst
> new file mode 100644
> index 000000000000..213b4d722843
> --- /dev/null
> +++ b/doc/imc.rst
> @@ -0,0 +1,53 @@
> +.. _imc:
> +
> +OPAL/Skiboot In-Memory Collection (IMC) interface Documentation
> +===============================================================
> +
> +Overview:
> +---------
> +

What about the following:

In-Memory-Collection (IMC) is performance monitoring infrastrcuture
for counters that (once started) can be read from memory at any time by
an operating system. Such counters include those for the Nest and Core
units, enabling continuous monitoring of resource utilisation on the chip.

The API is agnostic as to how these counters are implemented. For the
Nest and Core units, they're implemented by having microcode in an
on-chip microcontroller gather data and periodically write it to the
memory locations.


> +Nest (On-Chip, Off-Core) unit:
> +------------------------------
> +
> +Nest units have dedicated hardware counters which can be programmed
> +to monitor various chip resources such as memory bandwidth,
> +xlink bandwidth, alink bandwidth, PCI, NVlink and so on. These Nest
> +unit PMU counters can be programmed in-band via scom. But alternatively,
> +programming of these counters and periodically moving the counter data
> +to memory are offloaded to a hardware engine part of OCC (On-Chip Controller).
> +
> +Microcode, starts to run at system boot in OCC complex, initialize these
> +Nest unit PMUs and periodically accumulate the nest pmu counter values
> +to memory. List of supported events by the microcode is packages as a DTS
> +and stored in IMA_CATALOG partition.
> +
> +Core unit:
> +----------
> +
> +Core IMC PMU counters are handled in the core-imc unit. Each core has
> +4 Core Performance Monitoring Counters (CPMCs) which are used by Core-IMC logic.
> +Two of these are dedicated to count core cycles and instructions.
> +The 2 remaining CPMCs have to multiplex 128 events each.
> +
> +Core IMC hardware does not support interrupts and it peridocially (based on
> +sampling duration) fetches the counter data and accumulate to main memory.
> +Memory to accumulate counter data are refered from "PDBAR" (per-core scom)
> +and "LDBAR" per-thread spr.
> +
> +OPAL APIs:
> +----------
> +
> +To enable the infrastructure, three OPAL APIs are implemented. These are
> +primarily intended for initializing the IMC hardware and Start/Stop
> +specfic IMC units (nest or core).

Perhaps instead:

"The OPAL API is simple: a call to init a counter type, and calls to
start and stop collection. The memory locations are described in the
device tree."

> +OPAL APIs call are documented and saved in doc/opal-api as
> opal-imc-counters.rst

Instead, point to the refenece, i.e.:

See :ref:`opal-api/opal-imc-counters` and :ref:`device-tree/imc`

> +Device Tree Bindings
> +--------------------
> +
> +See :ref:`device-tree/imc`

I think it's okay to reference the DT bindings under OPAL API above and
remove this section which is just a link to the DT bindings.


-- 
Stewart Smith
OPAL Architect, IBM.