Skip to contentSkip to conversation

perf Documentation: Describe the PMU naming convention

RFC PATCH Applied Ian Rogers 7 participants 10 messages Jun 6, 2024 – Mar 4, 2025

lore
Share & tools
lore

Ian Rogers

author
#0 lore raw

RFC PATCH v2 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..79b268319df1
@@ -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.1.467.gbab1589fc0-goog
Reviewed-by on v2 1/1
#1 lore raw
Quoted 33 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 +14 -0
new file mode 100644
index 000000000000..79b268319df1
@@ -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.

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

Quoted 10 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +10 -0
+
+		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.
Reviewed-by on v2 1/1
#2 lore raw
In reply to Ian Rogers
Quoted 8 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.

Reviewed-by on v2 1/1
#3 lore raw
In reply to Ian Rogers
Quoted 6 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.

Quoted 7 lines
---
 .../testing/sysfs-bus-event_source-devices    | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-event_source-devices

Thanks,
Kan

Quoted 30 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +24 -0
new file mode 100644
index 000000000000..79b268319df1
@@ -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.
author
#4 lore raw
Quoted 18 lines · Kan
Quoted 6 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.

Quoted 7 lines
---
 .../testing/sysfs-bus-event_source-devices    | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-event_source-devices
Quoted 1 line

Thanks for all the reviews. Could we land this?

Thanks,
Ian

Quoted 30 lines
Quoted 30 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +24 -0
new file mode 100644
index 000000000000..79b268319df1
@@ -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.
#5 lore raw
Quoted 19 lines · Ian Rogers
Quoted 18 lines · Kan
Quoted 13 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

Quoted 3 lines
Quoted 1 line

Thanks for all the reviews. Could we land this?

Hmm, it's not always going to be strictly true as written though - we will also have cases where multiple PMU instances owned by the same driver don't all support the same events/filters/etc., and/or are entirely unrelated such that the same event encoding may mean completely different things. I've just landed a driver where not only are the instances going to be heterogeneous (since it's for arbitrary bits of interconnect), but for hierarchy reasons the most logical place to put the instance ID in the name wasn't even at the end :(

FWIW I think if we want to nail down a strict ABI, it would seem more robust to have an explicit attribute to describe underlying PMU properties like whether instances do represent identical "slices" or not. The hex suffix thing is already proving how fragile names alone are liable to be.

Thanks,
Robin.

Quoted 34 lines

Thanks,
Ian

Quoted 30 lines
Quoted 30 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +24 -0
new file mode 100644
index 000000000000..79b268319df1
@@ -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.
author
#6 lore raw
Quoted 25 lines · Robin Murphy
Quoted 19 lines · Ian Rogers
Quoted 18 lines · Kan
Quoted 13 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

Quoted 3 lines
Quoted 1 line

Thanks for all the reviews. Could we land this?

Quoted 8 lines

Hmm, it's not always going to be strictly true as written though - we will also have cases where multiple PMU instances owned by the same driver don't all support the same events/filters/etc., and/or are entirely unrelated such that the same event encoding may mean completely different things. I've just landed a driver where not only are the instances going to be heterogeneous (since it's for arbitrary bits of interconnect), but for hierarchy reasons the most logical place to put the instance ID in the name wasn't even at the end :(

Right, I was trying to capture what the tool is doing and trying to encompass the problems hex suffix create. Another example of that problem recently burning us is ARM's PMU naming of armv8_pmuv3_a53 means the a53 looks like a hex suffix. When ARM release a model with a 3 digit number will the naming break? Wrt filters, I wonder if there should be testing, bugs, etc. The wildcard matching will likely do its thing and I think the failures should be predictable and descriptive, like an event used a format that a PMU doesn't support, but I'm not sure if we should do improvements in perf list where we try to deduplicate PMUs. Perhaps the deduplication should be smarter.

Quoted 5 lines

FWIW I think if we want to nail down a strict ABI, it would seem more robust to have an explicit attribute to describe underlying PMU properties like whether instances do represent identical "slices" or not. The hex suffix thing is already proving how fragile names alone are liable to be.

Agreed. Does this mean we shouldn't land this? I worry that LKML is the home of bike shedding conversations and we're likely to bike shed trying to achieve 'perfect' while something 'good' would have value today.

Thanks,
Ian

Quoted 31 lines
Quoted 30 lines
Quoted 30 lines
Quoted 30 lines
Documentation/ABI/testing/sysfs-bus-event_source-devices new file +24 -0
new file mode 100644
index 000000000000..79b268319df1
@@ -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.
author
#7 lore raw
Quoted 54 lines · Ian Rogers
Quoted 25 lines · Robin Murphy
Quoted 19 lines · Ian Rogers
Quoted 18 lines · Kan
Quoted 13 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

Quoted 3 lines
Quoted 1 line

Thanks for all the reviews. Could we land this?

Quoted 8 lines

Hmm, it's not always going to be strictly true as written though - we will also have cases where multiple PMU instances owned by the same driver don't all support the same events/filters/etc., and/or are entirely unrelated such that the same event encoding may mean completely different things. I've just landed a driver where not only are the instances going to be heterogeneous (since it's for arbitrary bits of interconnect), but for hierarchy reasons the most logical place to put the instance ID in the name wasn't even at the end :(

Right, I was trying to capture what the tool is doing and trying to encompass the problems hex suffix create. Another example of that problem recently burning us is ARM's PMU naming of armv8_pmuv3_a53 means the a53 looks like a hex suffix. When ARM release a model with a 3 digit number will the naming break? Wrt filters, I wonder if there should be testing, bugs, etc. The wildcard matching will likely do its thing and I think the failures should be predictable and descriptive, like an event used a format that a PMU doesn't support, but I'm not sure if we should do improvements in perf list where we try to deduplicate PMUs. Perhaps the deduplication should be smarter.

Quoted 5 lines

FWIW I think if we want to nail down a strict ABI, it would seem more robust to have an explicit attribute to describe underlying PMU properties like whether instances do represent identical "slices" or not. The hex suffix thing is already proving how fragile names alone are liable to be.

Quoted 4 lines

Agreed. Does this mean we shouldn't land this? I worry that LKML is the home of bike shedding conversations and we're likely to bike shed trying to achieve 'perfect' while something 'good' would have value today.

Ping.

Thanks,
Ian

#8 lore raw
Quoted 55 lines · Ian Rogers
Quoted 54 lines · Ian Rogers
Quoted 25 lines · Robin Murphy
Quoted 19 lines · Ian Rogers
Quoted 18 lines · Kan
Quoted 13 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

Quoted 3 lines
Quoted 1 line

Thanks for all the reviews. Could we land this?

Quoted 8 lines

Hmm, it's not always going to be strictly true as written though - we will also have cases where multiple PMU instances owned by the same driver don't all support the same events/filters/etc., and/or are entirely unrelated such that the same event encoding may mean completely different things. I've just landed a driver where not only are the instances going to be heterogeneous (since it's for arbitrary bits of interconnect), but for hierarchy reasons the most logical place to put the instance ID in the name wasn't even at the end :(

Right, I was trying to capture what the tool is doing and trying to encompass the problems hex suffix create. Another example of that problem recently burning us is ARM's PMU naming of armv8_pmuv3_a53 means the a53 looks like a hex suffix. When ARM release a model with a 3 digit number will the naming break? Wrt filters, I wonder if there should be testing, bugs, etc. The wildcard matching will likely do its thing and I think the failures should be predictable and descriptive, like an event used a format that a PMU doesn't support, but I'm not sure if we should do improvements in perf list where we try to deduplicate PMUs. Perhaps the deduplication should be smarter.

Quoted 5 lines

FWIW I think if we want to nail down a strict ABI, it would seem more robust to have an explicit attribute to describe underlying PMU properties like whether instances do represent identical "slices" or not. The hex suffix thing is already proving how fragile names alone are liable to be.

Quoted 6 lines
Quoted 4 lines

Agreed. Does this mean we shouldn't land this? I worry that LKML is the home of bike shedding conversations and we're likely to bike shed trying to achieve 'perfect' while something 'good' would have value today.

Ping.

Thanks, applied to perf-tools-next,

- Arnaldo

#9 lore raw
Quoted 61 lines · Arnaldo Carvalho de Melo
Quoted 60 lines · Ian Rogers
Quoted 58 lines · Ian Rogers
Quoted 25 lines · Robin Murphy
Quoted 19 lines · Ian Rogers
Quoted 18 lines · Kan
Quoted 13 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

Quoted 3 lines
Quoted 1 line

Thanks for all the reviews. Could we land this?

Quoted 8 lines

Hmm, it's not always going to be strictly true as written though - we will also have cases where multiple PMU instances owned by the same driver don't all support the same events/filters/etc., and/or are entirely unrelated such that the same event encoding may mean completely different things. I've just landed a driver where not only are the instances going to be heterogeneous (since it's for arbitrary bits of interconnect), but for hierarchy reasons the most logical place to put the instance ID in the name wasn't even at the end :(

Right, I was trying to capture what the tool is doing and trying to encompass the problems hex suffix create. Another example of that problem recently burning us is ARM's PMU naming of armv8_pmuv3_a53 means the a53 looks like a hex suffix. When ARM release a model with a 3 digit number will the naming break? Wrt filters, I wonder if there should be testing, bugs, etc. The wildcard matching will likely do its thing and I think the failures should be predictable and descriptive, like an event used a format that a PMU doesn't support, but I'm not sure if we should do improvements in perf list where we try to deduplicate PMUs. Perhaps the deduplication should be smarter.

Quoted 5 lines

FWIW I think if we want to nail down a strict ABI, it would seem more robust to have an explicit attribute to describe underlying PMU properties like whether instances do represent identical "slices" or not. The hex suffix thing is already proving how fragile names alone are liable to be.

Agreed. Does this mean we shouldn't land this? I worry that LKML is the home of bike shedding conversations and we're likely to bike shed trying to achieve 'perfect' while something 'good' would have value today.

Quoted 6 lines
Quoted 1 line

Ping.

Thanks, applied to perf-tools-next,

- Arnaldo

Just commenting to tie this into some related ideas that I put in the cover letter here: https://lore.kernel.org/linux-perf-users/[email protected]/T/#m44b5da77819baa249d34bc5b2c7f10b65d3d7360