[RFC PATCH v1] perf Documentation: Describe the PMU naming convention

[RFC PATCH v1] perf Documentation: Describe the PMU naming convention

[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

diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices b/Documentation/ABI/testing/sysfs-bus-event_source-devices
new file mode 100644
index 000000000000..3f7e53e82de7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices
@@ -0,0 +1,24 @@
+What: /sys/bus/event_source/devices/<pmu>
+Date: 2014/02/24
+Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
+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.
-- 
2.45.0.rc1.225.g2a3ae87e7f-goog

Re: [RFC PATCH v1] perf Documentation: Describe the PMU naming convention

[Randy Dunlap]

Hi,

On 5/13/24 5:58 PM, Ian Rogers wrote:
> 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
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices b/Documentation/ABI/testing/sysfs-bus-event_source-devices
> new file mode 100644
> index 000000000000..3f7e53e82de7
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices
> @@ -0,0 +1,24 @@
> +What: /sys/bus/event_source/devices/<pmu>
> +Date: 2014/02/24
> +Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
> +Description:	Performance Monitoring Unit (<pmu>)
> +

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

> +		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,

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

> +		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:

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

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

Re: [RFC PATCH v1] perf Documentation: Describe the PMU naming convention

[Ian Rogers]

On Mon, May 13, 2024 at 10:40 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
> Hi,
>
> On 5/13/24 5:58 PM, Ian Rogers wrote:
> > 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
> >
> > diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices b/Documentation/ABI/testing/sysfs-bus-event_source-devices
> > new file mode 100644
> > index 000000000000..3f7e53e82de7
> > --- /dev/null
> > +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices
> > @@ -0,0 +1,24 @@
> > +What: /sys/bus/event_source/devices/<pmu>
> > +Date: 2014/02/24
> > +Contact:     Linux kernel mailing list <linux-kernel@vger.kernel.org>
> > +Description: Performance Monitoring Unit (<pmu>)
> > +
>
> Mostly looks good to me. I prefer a small change (below).
>
> > +             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,
>
> s/,/;/
> or: s/,/./ and begin the next sentence with a capital letter.
>
> > +             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:
>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>
> thanks.

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

Ian

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