[RESEND,v4,4/4] powerpc/papr_scm: Document papr_scm sysfs event format entries

Details is added for the event, cpumask and format attributes
in the ABI documentation.

Acked-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Reviewed-by: Madhavan Srinivasan <maddy@linux.ibm.com>
Tested-by: Nageswara R Sastry <rnsastry@linux.ibm.com>
Signed-off-by: Kajol Jain <kjain@linux.ibm.com>
---
 Documentation/ABI/testing/sysfs-bus-papr-pmem | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)

On Thu, Sep 2, 2021 at 10:11 PM Kajol Jain <kjain@linux.ibm.com> wrote:
>
> Details is added for the event, cpumask and format attributes
> in the ABI documentation.
>
> Acked-by: Peter Zijlstra (Intel) <peterz@infradead.org>
> Reviewed-by: Madhavan Srinivasan <maddy@linux.ibm.com>
> Tested-by: Nageswara R Sastry <rnsastry@linux.ibm.com>
> Signed-off-by: Kajol Jain <kjain@linux.ibm.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-papr-pmem | 31 +++++++++++++++++++
>  1 file changed, 31 insertions(+)
>
> diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem
> index 95254cec92bf..4d86252448f8 100644
> --- a/Documentation/ABI/testing/sysfs-bus-papr-pmem
> +++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem
> @@ -61,3 +61,34 @@ Description:
>                 * "CchRHCnt" : Cache Read Hit Count
>                 * "CchWHCnt" : Cache Write Hit Count
>                 * "FastWCnt" : Fast Write Count
> +
> +What:          /sys/devices/nmemX/format
> +Date:          June 2021
> +Contact:       linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev,
> +Description:   (RO) 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 is listed
> +                below::
> +
> +                   event  = "config:0-4"  - event ID
> +
> +               For example::
> +                   noopstat = "event=0x1"
> +
> +What:          /sys/devices/nmemX/events

That's not a valid sysfs path. Did you mean /sys/bus/nd/devices/nmemX?

> +Date:          June 2021
> +Contact:       linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev,
> +Description:    (RO) Attribute group to describe performance monitoring
> +                events specific to papr-scm. Each attribute in this group describes
> +                a single performance monitoring event supported by this nvdimm pmu.
> +                The name of the file is the name of the event.
> +                (See ABI/testing/sysfs-bus-event_source-devices-events).

Given these events are in the generic namespace the ABI documentation
should be generic as well. So I think move these entries to
Documentation/ABI/testing/sysfs-bus-nvdimm directly.

You can still mention papr-scm, but I would expect something like:

What:           /sys/bus/nd/devices/nmemX/events
Date:           September 2021
KernelVersion:  5.16
Contact:        Kajol Jain <kjain@linux.ibm.com>
Description:
                (RO) Attribute group to describe performance monitoring events
                for the nvdimm memory device. Each attribute in this group
                describes a single performance monitoring event supported by
                this nvdimm pmu.  The name of the file is the name of the event.
                (See ABI/testing/sysfs-bus-event_source-devices-events). A
                listing of the events supported by a given nvdimm provider type
                can be found in Documentation/driver-api/nvdimm/$provider, for
                example: Documentation/driver-api/nvdimm/papr-scm.



> +
> +What:          /sys/devices/nmemX/cpumask
> +Date:          June 2021
> +Contact:       linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev,
> +Description:   (RO) This sysfs file exposes the cpumask which is designated to make
> +                HCALLs to retrieve nvdimm pmu event counter data.

Seems this one would be provider generic, so no need to refer to PPC
specific concepts like HCALLs.

On 9/8/21 6:33 AM, Dan Williams wrote:
> On Thu, Sep 2, 2021 at 10:11 PM Kajol Jain <kjain@linux.ibm.com> wrote:
>>
>> Details is added for the event, cpumask and format attributes
>> in the ABI documentation.
>>
>> Acked-by: Peter Zijlstra (Intel) <peterz@infradead.org>
>> Reviewed-by: Madhavan Srinivasan <maddy@linux.ibm.com>
>> Tested-by: Nageswara R Sastry <rnsastry@linux.ibm.com>
>> Signed-off-by: Kajol Jain <kjain@linux.ibm.com>
>> ---
>>  Documentation/ABI/testing/sysfs-bus-papr-pmem | 31 +++++++++++++++++++
>>  1 file changed, 31 insertions(+)
>>
>> diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem
>> index 95254cec92bf..4d86252448f8 100644
>> --- a/Documentation/ABI/testing/sysfs-bus-papr-pmem
>> +++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem
>> @@ -61,3 +61,34 @@ Description:
>>                 * "CchRHCnt" : Cache Read Hit Count
>>                 * "CchWHCnt" : Cache Write Hit Count
>>                 * "FastWCnt" : Fast Write Count
>> +
>> +What:          /sys/devices/nmemX/format
>> +Date:          June 2021
>> +Contact:       linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev,
>> +Description:   (RO) 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 is listed
>> +                below::
>> +
>> +                   event  = "config:0-4"  - event ID
>> +
>> +               For example::
>> +                   noopstat = "event=0x1"
>> +
>> +What:          /sys/devices/nmemX/events
> 
> That's not a valid sysfs path. Did you mean /sys/bus/nd/devices/nmemX?

Hi Dan,
  Thanks, I will correct it and update it to `/sys/bus/event_source/devices/`
where perf creates sysfs files for given pmu.

> 
>> +Date:          June 2021
>> +Contact:       linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev,
>> +Description:    (RO) Attribute group to describe performance monitoring
>> +                events specific to papr-scm. Each attribute in this group describes
>> +                a single performance monitoring event supported by this nvdimm pmu.
>> +                The name of the file is the name of the event.
>> +                (See ABI/testing/sysfs-bus-event_source-devices-events).
> 
> Given these events are in the generic namespace the ABI documentation
> should be generic as well. So I think move these entries to
> Documentation/ABI/testing/sysfs-bus-nvdimm directly.
> 
> You can still mention papr-scm, but I would expect something like:
> 
> What:           /sys/bus/nd/devices/nmemX/events
> Date:           September 2021
> KernelVersion:  5.16
> Contact:        Kajol Jain <kjain@linux.ibm.com>
> Description:
>                 (RO) Attribute group to describe performance monitoring events
>                 for the nvdimm memory device. Each attribute in this group
>                 describes a single performance monitoring event supported by
>                 this nvdimm pmu.  The name of the file is the name of the event.
>                 (See ABI/testing/sysfs-bus-event_source-devices-events). A
>                 listing of the events supported by a given nvdimm provider type
>                 can be found in Documentation/driver-api/nvdimm/$provider, for
>                 example: Documentation/driver-api/nvdimm/papr-scm.
> 
> 

I will update it accordingly.

> 
>> +
>> +What:          /sys/devices/nmemX/cpumask
>> +Date:          June 2021
>> +Contact:       linuxppc-dev <linuxppc-dev@lists.ozlabs.org>, nvdimm@lists.linux.dev,
>> +Description:   (RO) This sysfs file exposes the cpumask which is designated to make
>> +                HCALLs to retrieve nvdimm pmu event counter data.
> 
> Seems this one would be provider generic, so no need to refer to PPC
> specific concepts like HCALLs.
> 

Sure will update it.

Thanks,
Kajol Jain