[Skiboot] [PATCH v9 01/11] skiboot/doc: Add doc/imc.rst to detailthe infrastructure and interface

[Anju T Sudhakar]

>From : Madhavan Srinivasan <maddy at linux.vnet.ibm.com>

Signed-off-by: Madhavan Srinivasan <maddy at linux.vnet.ibm.com>
Signed-off-by: Anju T Sudhakar <anju at linux.vnet.ibm.com>
---
 doc/imc.rst   | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/index.rst |  1 +
 2 files changed, 58 insertions(+)
 create mode 100644 doc/imc.rst

diff --git a/doc/imc.rst b/doc/imc.rst
new file mode 100644
index 0000000..b53e14d
--- /dev/null
+++ b/doc/imc.rst
@@ -0,0 +1,57 @@
+.. _imc:
+
+OPAL/Skiboot In-Memory Collection (IMC) interface Documentation
+===============================================================
+
+Overview:
+---------
+
+In-Memory-Collection (IMC) is performance monitoring infrastrcuture (PMU)
+added to Nest and Core unit to enable continuous monitoring of the chip
+resource utilisation.
+
+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. Core-IMC hardware
+consist of 4 hypervisor only per-core performance monitoring counters (CPMCs).
+Out of 4 CPMCs, CPMC3 and CPMC4 are dedicated to count core cycles and
+instructions. Core IMC support a maximum of 256 events and they are
+multiplexed on this 2 programmable CPMCs. Core IMC unit also support Thread
+level monitoring and when enabled will multiple these 256 events per-thread
+to generate per-thread IMC counter data.
+
+Core IMC hardware does not support interrupts and they peridocially (based on
+sampling duration) fetch the counter data and accumulate to main memory.
+For per-core counter updates, Core-IMC logic refer memory address from per-core
+scom resource "PDBAR". For per-thread counter updates, Core-IMC logic refer's
+per-thread spr "LDBAR".
+
+OPAL APIs:
+----------
+
+To enable the infrastructure, couple of OPAL APIs are implemented. These are
+primarily intended for 1) initializing the IMC hardware and 2) Start/Stop
+specfic IMC units (nest or core).
+
+OPAL APIs call are documented and saved in doc/opal-api as opal-imc-counters.rst
+
+Device Tree Bindings
+--------------------
+
+See :ref:`device-tree/imc`
diff --git a/doc/index.rst b/doc/index.rst
index 1826d13..89a5b32 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -32,6 +32,7 @@ Developer Guide and Internals
    pci-slot
    xscom-node-bindings
    xive
+   imc
 
 
 OPAL ABI
-- 
2.7.4