[RFC PATCH 08/22] docs: perf: Add TI K3 DDR PMU documentation

[MANNURU VENKATESWARLU]

From: Aarya Chaumal <a-chaumal@xxxxxx>

Add documentation for the TI K3 DDR PMU driver describing the
counter layout, supported events and perf tool usage examples.

Signed-off-by: MANNURU VENKATESWARLU <v-mannuru@xxxxxx>
Signed-off-by: Aarya Chaumal <a-chaumal@xxxxxx>
---
 Documentation/admin-guide/perf/index.rst  |  1 +
 Documentation/admin-guide/perf/k3-ddr.rst | 57 +++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 Documentation/admin-guide/perf/k3-ddr.rst

diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst
index aa12708ddb965..752384d2d050f 100644
--- a/Documentation/admin-guide/perf/index.rst
+++ b/Documentation/admin-guide/perf/index.rst
@@ -31,3 +31,4 @@ Performance monitor support
    ampere_cspmu
    mrvl-pem-pmu
    fujitsu_uncore_pmu
+   k3-ddr
diff --git a/Documentation/admin-guide/perf/k3-ddr.rst b/Documentation/admin-guide/perf/k3-ddr.rst
new file mode 100644
index 0000000000000..3788bd41d15ff
--- /dev/null
+++ b/Documentation/admin-guide/perf/k3-ddr.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================================================
+Texas Instruments K3 DDR Performance Monitoring Unit (PMU)
+==========================================================
+
+TI K3 SoCs contain DDR performance counters inside the MSMC2DDR bridge within
+the DDR subsystem (SSCFG region). The PMU provides four programmable counters,
+each tracking one event type simultaneously.
+
+Counter Select Register (Base + 0x100):
+
+  - Bits [5:0]   - Event select for counter 0
+  - Bits [13:8]  - Event select for counter 1
+  - Bits [21:16] - Event select for counter 2
+  - Bits [29:24] - Event select for counter 3
+
+Writing the event ID for a given counter causes it to begin counting. Counter
+values are read as 32-bit unsigned integers; the driver accumulates overflow
+using an hrtimer set to 1-second period.
+
+The ``format`` directory describes format of the config (event ID) field of the
+``perf_event_attr`` structure:
+``/sys/bus/event_source/devices/k3_ddr0/format/``.
+
+The ``events`` directory lists the hardware events that can be used with the
+perf tool: ``/sys/bus/event_source/devices/k3_ddr0/events/``.
+
+Supported SoCs
+==============
+
+* J721E
+* J721S2 (dual DDR channels: k3_ddr0, k3_ddr1)
+* J784S4 (four DDR channels: k3_ddr0 - k3_ddr3)
+* J7200
+* AM62
+* AM62A
+* AM62P
+* AM64
+
+Examples
+========
+
+To track read and write commands during a test, run:
+
+.. code-block:: bash
+
+   perf stat -a -e k3_ddr0/read/,k3_ddr0/write/ bw_mem -N 30 8M rd
+
+To monitor memory bandwidth (metric name varies by SoC, e.g. for J7 family):
+
+.. code-block:: bash
+
+    perf stat -a \
+     -M k3_ddr_j7.read_bandwidth_mbytes_sec,k3_ddr_j7.write_bandwidth_mbytes_sec \
+     -I 1000
+
-- 
2.34.1