[PATCH v2 9/9] perf Documentation: Describe PMU names numbered in more than one place

[Besar Wicaksono]

The PMU naming convention describes an optional numeric suffix that tools
ignore to treat PMUs as instances of one PMU. Some PMU names contain more
than one number to identify an instance, such as the NVIDIA PCIe PMU
nvidia_pcie_pmu_<socket>_rc_<rc>. Since commit 730670b1d108 ("perf pmu:
Support more complex PMU event aliasing"), the perf tool matches such
names with json event Units with comma-separated parts, like
"nvidia_pcie_pmu_,rc_".

Describe these names and how tools can tell that all their numbers
identify an instance of the same PMU.

Signed-off-by: Besar Wicaksono <bwicaksono at nvidia.com>
---
 .../ABI/testing/sysfs-bus-event_source-devices     | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices b/Documentation/ABI/testing/sysfs-bus-event_source-devices
index 79b268319df1..7610aa46cd50 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices
@@ -22,3 +22,17 @@ Description:	Performance Monitoring Unit (<pmu>)
 		uncore_imc_free_running should be treated as opening
 		the data_read event on PMU uncore_imc_free_running_0
 		and PMU uncore_imc_free_running_1.
+
+		Some PMU names contain more than one number to
+		identify an instance. For example, the NVIDIA PCIe PMU
+		of root complex <rc> on socket <socket> is named
+		nvidia_pcie_pmu_<socket>_rc_<rc>. The name alone does
+		not show that both numbers identify an instance of the
+		same PMU; in other names, an earlier number can select
+		a different PMU. Tools can treat such PMUs as
+		instances of the same PMU when they have a description
+		of the name parts, like the perf tool's json event
+		"Unit" with comma-separated parts,
+		"nvidia_pcie_pmu_,rc_", which matches PMU names with
+		an optional number after each part, like
+		nvidia_pcie_pmu_1_rc_3.
-- 
2.43.0