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

[Madhavan Srinivasan]

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

Yes. Will do.

>
>> +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."
Sure. Will make the changes accordingly.

>
>> +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.
OK. will do.

Maddy


>