[RFC PATCH 1/2] {topost} drivers/perf: hisi: Add description for HNS3 PMU driver

[John Garry]

On 22/03/2021 01:49, Guangbin Huang wrote:

please remove {topost} next time

> HNS3 PMU End Point device is supported on HiSilicon HIP09 platform, so
> add document hns3-pmu.rst to provide guidance on how to use it.
> 

sorry, I didn't do much review of this before sending out...

> Signed-off-by: Guangbin Huang <huangguangbin2 at huawei.com>
> ---
>   Documentation/admin-guide/perf/hns3-pmu.rst | 125 ++++++++++++++++++++++++++++
>   1 file changed, 125 insertions(+)
>   create mode 100644 Documentation/admin-guide/perf/hns3-pmu.rst
> 
> diff --git a/Documentation/admin-guide/perf/hns3-pmu.rst b/Documentation/admin-guide/perf/hns3-pmu.rst
> new file mode 100644
> index 0000000..3597a8e
> --- /dev/null
> +++ b/Documentation/admin-guide/perf/hns3-pmu.rst
> @@ -0,0 +1,125 @@
> +======================================
> +HNS3 Performance Monitoring Unit (PMU)
> +======================================
> +
> +HNS3(HiSilicon network system 3) Performance Monitoring Unit (PMU) is an
> +End Point device to collect performance statistics of HiSilicon SoC NIC.
> +On Hip09, each SICL has one PMU device.

Even though the hisi-pmu doc now mentions what is SICL, it is also 
better mention here what it is.

> +
> +HNS3 PMU is supported to collect performance statistics of bandwidth,
> +latency, packet rate and interrupt rate.
> +
> +Each HNS3 PMU supports up to 8 hardware events.
> +
> +HNS3 PMU driver
> +===============
> +
> +The HNS3 PMU driver registers a perf PMU with the name of its device id.::
> +
> +  /sys/devices/hns3_pmu_<device_id>

any reason for which sicl is not used in the same?

How is a anyone supposed to know which device hns3_pmu_0 - for example - 
is ?

> +
> +PMU driver provides description of available events, filter modes, format,
> +identifier and cpumask in sysfs.
> +
> +The "events" directory describes the event code and subevent code of all
> +supported events shown in perf list.
> +
> +The "filtermode" directory describes the supported filter modes of each
> +event.
> +
> +The "format" directory describes all formats of the config (events) and
> +config1 (filter options) fields of the perf_event_attr structure.
> +
> +The "identifier" file shows version of PMU hardware device.
> +
> +The "cpumask" file shows which CPU is PMU driver running on.

isn't that really the CPUs associated with that PMU?

> +
> +Example usage of checking event code and subevent code::
> +
> +  $# cat /sys/devices/hns3_pmu_0/events/bw_igu_ssu
> +  event=0x0, subevent=0x0

as below

> +
> +Example usage of checking supported filter mode::
> +
> +  $# cat /sys/devices/hns3_pmu_0/filtermode/bw_igu_ssu
> +  filter mode supported: global/port/port-tc/

A sysfs file should just hold a single value is a basic rule

> +
> +Example usage of perf::
> +
> +  $# perf list
> +  hns3_pmu_0/bw_igu_ssu/ [kernel PMU event]
> +  ------------------------------------------
> +
> +  $# perf stat -a -e hns3_pmu_0/bw_igu_ssu,global=1/ -I 1000
> +  or
> +  $# perf stat -a -e hns3_pmu_0/event=0,subevent=0,global=1/ -I 1000
> +
> +The current driver does not support sampling. So "perf record" is unsupported.
> +Also attach to a task is unsupported for HNS3 PMU.
> +
> +Filter modes
> +--------------
> +
> +1. global mode
> +PMU collect performance statistic of all functions of IO DIE. Set the
> +"global" filter option to 1 will enable this mode.
> +Example usage of perf::
> +
> +  $# perf stat -a -e hns3_pmu_0/event=0,subevent=0,global=1/ -I 1000
> +
> +2. port mode
> +PMU collect performance statistic of one whole physical port. The port id
> +is same as mac id. The "tc" filter option must be set to 0xF in this mode.
> +Example usage of perf::
> +
> +  $# perf stat -a -e hns3_pmu_0/event=0,subevent=0,port=0,tc=0xF/ -I 1000
> +
> +3. port-tc mode
> +PMU collect performance statistic of one tc of physical port. The port id
> +is same as mac id. The "tc" filter option must be set to 0 ~ 7 in this
> +mode.
> +Example usage of perf::
> +
> +  $# perf stat -a -e hns3_pmu_0/event=0,subevent=0,port=0,tc=0/ -I 1000
> +
> +4. func mode
> +PMU collect performance statistic of one PF/VF. The function id is BDF of
> +PF/VF, its conversion formula::
> +
> +  func = (bus << 8) + (device << 3) + (function)
> +
> +for example:
> +  BDF         func
> +  35:00.0    0x3500
> +  35:00.1    0x3501
> +  35:01.0    0x3508

any reason why we can't have each nibble holding a digit of BDF?  0x3508 
look strange

> +
> +In this mode, the "queue" filter option must be set to 0xFFFF.
> +Example usage of perf::
> +
> +  $# perf stat -a -e hns3_pmu_0/event=0,subevent=0,func=0x3500,queue=0xFFFF/ -I 1000
> +
> +5. func-queue mode
> +PMU collect performance statistic of one queue of PF/VF. The function id
> +is BDF of PF/VF, its conversion formula::
> +
> +  func = (bus << 8) + (device << 3) + (function)
> +
> +In this mode, the "queue" filter option must be set to the exact queue id
> +of function.
> +Example usage of perf::
> +
> +  $# perf stat -a -e hns3_pmu_0/event=0,subevent=0,func=0x3500,queue=0/ -I 1000
> +

To me it's odd that the difference between func mode and func-queue mode 
is just setting the queue=0xffff or queue=0 - seems to be just the same 
mode with a different queue option

> +
> +6. func-intr mode
> +PMU collect performance statistic of one interrupt of PF/VF. The function
> +id is BDF of PF/VF, its conversion formula::
> +
> +  func = (bus << 8) + (device << 3) + (function)
> +
> +In this mode, the "intr" filter option must be set to the exact interrupt
> +id of function.
> +Example usage of perf::
> +
> +  $# perf stat -a -e hns3_pmu_0/event=0,subevent=0,func=0x3500,intr=0/ -I 1000
>