Received-SPF: pass (google.com: domain of linux-kernel+bounces-178330-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) client-ip=2604:1380:45e3:2400::1;
Message-ID: <793876b1-fd4d-42ef-91e2-88b4a48794b7@infradead.org>
Date: Mon, 13 May 2024 22:40:44 -0700
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [RFC PATCH v1] perf Documentation: Describe the PMU naming
 convention
To: Ian Rogers <irogers@google.com>,
 Tuan Phan <tuanphan@os.amperecomputing.com>,
 Robin Murphy <robin.murphy@arm.com>, Thomas Richter <tmricht@linux.ibm.com>,
 Bhaskara Budiredla <bbudiredla@marvell.com>,
 Bharat Bhushan <bbhushan2@marvell.com>, Peter Zijlstra
 <peterz@infradead.org>, Ingo Molnar <mingo@redhat.com>,
 Arnaldo Carvalho de Melo <acme@kernel.org>,
 Namhyung Kim <namhyung@kernel.org>, Mark Rutland <mark.rutland@arm.com>,
 Alexander Shishkin <alexander.shishkin@linux.intel.com>,
 Jiri Olsa <jolsa@kernel.org>, Adrian Hunter <adrian.hunter@intel.com>,
 Kan Liang <kan.liang@linux.intel.com>, James Clark <james.clark@arm.com>,
 Ravi Bangoria <ravi.bangoria@amd.com>, linux-perf-users@vger.kernel.org,
 linux-kernel@vger.kernel.org, Will Deacon <will@kernel.org>,
 Stephane Eranian <eranian@google.com>
References: <20240514005817.2902473-1-irogers@google.com>
Content-Language: en-US
From: Randy Dunlap <rdunlap@infradead.org>
In-Reply-To: <20240514005817.2902473-1-irogers@google.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

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