Skip to contentSkip to conversation

perf Documentation: Describe the PMU naming convention

RFC PATCH Superseded Ian Rogers 2 participants 3 messages May 14, 2024

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Ian Rogers

author
#0 lore raw

RFC PATCH 1/1 perf Documentation: Describe the PMU naming convention

It is an existing convention to use suffixes with PMU names. Try to capture that convention so that future PMU devices may adhere to it.

The name of the file and date within the file try to follow existing conventions, particularly sysfs-bus-event_source-devices-events.

---
 .../testing/sysfs-bus-event_source-devices    | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-event_source-devices
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +24 -0
new file mode 100644
index 000000000000..3f7e53e82de7
@@ -0,0 +1,24 @@
+What: /sys/bus/event_source/devices/<pmu>
+Date: 2014/02/24
+Contact:	Linux kernel mailing list <[email protected]>
+Description:	Performance Monitoring Unit (<pmu>)
+
+		Each <pmu> directory, for a PMU device, is a name
+		optionally followed by an underscore and then either a
+		decimal or hexadecimal number. For example, cpu is a
+		PMU name without a suffix as is intel_bts,
+		uncore_imc_0 is a PMU name with a 0 numeric suffix,
+		ddr_pmu_87e1b0000000 is a PMU name with a hex
+		suffix. The hex suffix must be more than two
+		characters long to avoid ambiguity with PMUs like the
+		S390 cpum_cf.
+
+		Tools can treat PMUs with the same name that differ by
+		suffix as instances of the same PMU for the sake of,
+		for example, opening an event. For example, the PMUs
+		uncore_imc_free_running_0 and
+		uncore_imc_free_running_1 have an event data_read,
+		opening the data_read event on a PMU specified as
+		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.
Signature · 1 line
2.45.0.rc1.225.g2a3ae87e7f-goog
Reviewed-by on v1 1/1
#1 lore raw

Hi,

Quoted 16 lines · Ian Rogers

It is an existing convention to use suffixes with PMU names. Try to capture that convention so that future PMU devices may adhere to it.

The name of the file and date within the file try to follow existing conventions, particularly sysfs-bus-event_source-devices-events.

---
 .../testing/sysfs-bus-event_source-devices    | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-event_source-devices
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +0 -0
new file mode 100644
index 000000000000..3f7e53e82de7

Documentation/ABI/testing/sysfs-bus-event_source-devices line 5

Quoted 5 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +5 -0
@@ -0,0 +1,24 @@
+What: /sys/bus/event_source/devices/<pmu>
+Date: 2014/02/24
+Contact:	Linux kernel mailing list <[email protected]>
+Description:	Performance Monitoring Unit (<pmu>)
+

Mostly looks good to me. I prefer a small change (below).

Quoted 5 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +5 -0
+		Each <pmu> directory, for a PMU device, is a name
+		optionally followed by an underscore and then either a
+		decimal or hexadecimal number. For example, cpu is a
+		PMU name without a suffix as is intel_bts,
+		uncore_imc_0 is a PMU name with a 0 numeric suffix,

Documentation/ABI/testing/sysfs-bus-event_source-devices line 20

Quoted 10 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +10 -0
+		ddr_pmu_87e1b0000000 is a PMU name with a hex
+		suffix. The hex suffix must be more than two
+		characters long to avoid ambiguity with PMUs like the
+		S390 cpum_cf.
+
+		Tools can treat PMUs with the same name that differ by
+		suffix as instances of the same PMU for the sake of,
+		for example, opening an event. For example, the PMUs
+		uncore_imc_free_running_0 and
+		uncore_imc_free_running_1 have an event data_read,

s/,/;/
or: s/,/./ and begin the next sentence with a capital letter.

Documentation/ABI/testing/sysfs-bus-event_source-devices line 24

Quoted 4 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +4 -0
+		opening the data_read event on a PMU specified as
+		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.

With that change, you may add:

thanks.

Signature · 3 lines
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html
author
#2 lore raw
Quoted 52 lines · Randy Dunlap

Hi,

Quoted 16 lines · Ian Rogers

It is an existing convention to use suffixes with PMU names. Try to capture that convention so that future PMU devices may adhere to it.

The name of the file and date within the file try to follow existing conventions, particularly sysfs-bus-event_source-devices-events.

---
 .../testing/sysfs-bus-event_source-devices    | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-event_source-devices
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +0 -0
new file mode 100644
index 000000000000..3f7e53e82de7

Documentation/ABI/testing/sysfs-bus-event_source-devices line 5

Quoted 5 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +5 -0
@@ -0,0 +1,24 @@
+What: /sys/bus/event_source/devices/<pmu>
+Date: 2014/02/24
+Contact:     Linux kernel mailing list <[email protected]>
+Description: Performance Monitoring Unit (<pmu>)
+

Mostly looks good to me. I prefer a small change (below).

Quoted 5 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +5 -0
+             Each <pmu> directory, for a PMU device, is a name
+             optionally followed by an underscore and then either a
+             decimal or hexadecimal number. For example, cpu is a
+             PMU name without a suffix as is intel_bts,
+             uncore_imc_0 is a PMU name with a 0 numeric suffix,

Documentation/ABI/testing/sysfs-bus-event_source-devices line 20

Quoted 10 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +10 -0
+             ddr_pmu_87e1b0000000 is a PMU name with a hex
+             suffix. The hex suffix must be more than two
+             characters long to avoid ambiguity with PMUs like the
+             S390 cpum_cf.
+
+             Tools can treat PMUs with the same name that differ by
+             suffix as instances of the same PMU for the sake of,
+             for example, opening an event. For example, the PMUs
+             uncore_imc_free_running_0 and
+             uncore_imc_free_running_1 have an event data_read,

s/,/;/
or: s/,/./ and begin the next sentence with a capital letter.

Documentation/ABI/testing/sysfs-bus-event_source-devices line 24

Quoted 4 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +4 -0
+             opening the data_read event on a PMU specified as
+             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.
Quoted 5 lines

With that change, you may add:

thanks.

Thanks Randy, I'll leave this on the list to bake a little longer and then send a v2 with your fixes.

Ian

Quoted 4 lines

--
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html