[Skiboot] [PATCH v12 01/10] skiboot/doc: Add doc/imc.rst documentation

[Michael Neuling]

On Sun, 2017-05-21 at 20:39 +0530, Madhavan Srinivasan wrote:
> 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>

Acked-by: Michael Neuling <mikey at neuling.org>

> ---
>  doc/imc.rst   | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  doc/index.rst |  1 +
>  2 files changed, 55 insertions(+)
>  create mode 100644 doc/imc.rst
> 
> diff --git a/doc/imc.rst b/doc/imc.rst
> new file mode 100644
> index 000000000000..6b8fed483aac
> --- /dev/null
> +++ b/doc/imc.rst
> @@ -0,0 +1,54 @@
> +.. _imc:
> +
> +OPAL/Skiboot In-Memory Collection (IMC) interface Documentation
> +===============================================================
> +
> +Overview:
> +---------
> +
> +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 units, they're implemented by having microcode in an on-chip
> +microcontroller and for core units, they are implemented as part of core
> logic
> +to 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:
> +----------
> +
> +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.
> +
> +See :ref:`opal-api/opal-imc-counters` and :ref:`device-tree/imc`
> diff --git a/doc/index.rst b/doc/index.rst
> index 5464ae252384..d350acc3a59f 100644
> --- a/doc/index.rst
> +++ b/doc/index.rst
> @@ -34,6 +34,7 @@ Developer Guide and Internals
>     pci-slot
>     xscom-node-bindings
>     xive
> +   imc
>  
>  
>  OPAL ABI