Re: [PATCH V2 5/6] docs: ABI: sysfs-bus-event_source-devices-htm: Document sysfs event format entries for htm pmu

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 3 potential issue(s) to consider:
- [Medium] The format attributes documented in the ABI file do not match the V2 layout claimed in the commit message.
- [Medium] The commit message provides a fundamentally flawed example for using the 'events' attribute group, conflating it with the 'format' group.
- [Low] Minor grammatical error in the description text.
--

--- Patch [5]: [PATCH V2 5/6] docs: ABI: sysfs-bus-event_source-devices-htm: Document sysfs event format entries for htm pmu ---
commit 9ec8c4a8a34dc7a4a75859018f086bb71432aa4a
Author: Athira Rajeev <atrajeev@linux.ibm.com>

docs: ABI: sysfs-bus-event_source-devices-htm: Document sysfs event format entries for htm pmu

This commit adds ABI documentation for the sysfs entries exposed by the
HTM PMU under /sys/bus/event_source/devices/htm/. It documents the format
attribute group and the events attribute group.

> Document the events attribute group, which lists the named events
> available on the PMU.  Users can pass these names directly to perf:
> 
>   # perf record -e htm/nodalchipindex=2,nodeindex=0,htm_type=1/ ...

[Severity: Medium]
Does this example conflate the 'events' attribute group with the 'format'
group? The example provided uses format attribute fields (key-value pairs),
whereas the 'events' directory is supposed to provide named aliases.

> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-htm b/Documentation/ABI/testing/sysfs-bus-event_source-devices-htm
> new file mode 100644
> index 0000000000000..784ba7c31b89b
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-htm
> @@ -0,0 +1,21 @@
> +What:           /sys/bus/event_source/devices/htm/format
> +Date:           June 2026
> +Contact:        Linux on PowerPC Developer List <linuxppc-dev at lists.ozlabs.org>
> +Description:    Read-only. Attribute group to describe the magic bits
> +                that go into perf_event_attr.config for a particular pmu.
> +                (See ABI/testing/sysfs-bus-event_source-devices-format).
> +
> +                Each attribute under this group defines a bit range of the
> +                perf_event_attr.config. Supported attribute are listed
                                                             ^^^^^^^^^
[Severity: Low]
This isn't a bug, but there is a grammatical error here ("attribute are"
instead of "attributes are").

> +                below::
> +
> +				event  = "config:0-27"  - event ID

[Severity: Medium]
Is the documentation missing the format attributes claimed in the commit
message?

The commit message explicitly states that htm_type, nodeindex,
nodalchipindex, and coreindexonchip were added for the V2 layout, but only
the generic 'event' attribute is listed here.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260720104447.11843-1-atrajeev@linux.ibm.com?part=5