Commit 6baec315 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

docs: perf: convert to ReST 



Rename the perf documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent 39443104

Documentation/perf/arm-ccn.txt→Documentation/perf/arm-ccn.rst

+10 −8
Original line number Diff line number Diff line 
==========================

ARM Cache Coherent Network

==========================
@@ -29,6 +30,7 @@ Crosspoint watchpoint-based events (special "event" value 0xfe) 
require "xp" and "vc" as as above plus "port" (device port index),

"dir" (transmit/receive direction), comparator values ("cmp_l"

and "cmp_h") and "mask", being index of the comparator mask.



Masks are defined separately from the event description

(due to limited number of the config values) in the "cmp_mask"

directory, with first 8 configurable by user and additional
@@ -44,7 +46,7 @@ request the events on this processor (if not, the perf_event->cpu value 
will be overwritten anyway). In case of this processor being offlined,

the events are migrated to another one and the attribute is updated.



Example of perf tool use:

Example of perf tool use::



  / # perf list | grep ccn

    ccn/cycles/                                        [Kernel PMU event]

Documentation/perf/arm_dsu_pmu.txt→Documentation/perf/arm_dsu_pmu.rst

+3 −2
Original line number Diff line number Diff line 
==================================

ARM DynamIQ Shared Unit (DSU) PMU

==================================
@@ -13,7 +14,7 @@ PMU doesn't support process specific events and cannot be used in sampling mode. 
The DSU provides a bitmap for a subset of implemented events via hardware

registers. There is no way for the driver to determine if the other events

are available or not. Hence the driver exposes only those events advertised

by the DSU, in "events" directory under :

by the DSU, in "events" directory under::



  /sys/bus/event_sources/devices/arm_dsu_<N>/
@@ -23,6 +24,6 @@ and use the raw event code for the unlisted events. 
The driver also exposes the CPUs connected to the DSU instance in "associated_cpus".





e.g usage :

e.g usage::



	perf stat -a -e arm_dsu_0/cycles/

Documentation/perf/hisi-pmu.txt→Documentation/perf/hisi-pmu.rst

+22 −15
Original line number Diff line number Diff line 
======================================================

HiSilicon SoC uncore Performance Monitoring Unit (PMU)

======================================================



The HiSilicon SoC chip includes various independent system device PMUs

such as L3 cache (L3C), Hydra Home Agent (HHA) and DDRC. These PMUs are

independent and have hardware logic to gather statistics and performance
@@ -11,11 +13,13 @@ called Super CPU cluster (SCCL) and is made up of 6 CCLs. Each SCCL has 
two HHAs (0 - 1) and four DDRCs (0 - 3), respectively.



HiSilicon SoC uncore PMU driver

---------------------------------------

-------------------------------



Each device PMU has separate registers for event counting, control and

interrupt, and the PMU driver shall register perf PMU drivers like L3C,

HHA and DDRC etc. The available events and configuration options shall

be described in the sysfs, see:



/sys/devices/hisi_sccl{X}_<l3c{Y}/hha{Y}/ddrc{Y}>/, or

/sys/bus/event_source/devices/hisi_sccl{X}_<l3c{Y}/hha{Y}/ddrc{Y}>.

The "perf list" command shall list the available events from sysfs.
@@ -24,15 +28,18 @@ Each L3C, HHA and DDRC is registered as a separate PMU with perf. The PMU 
name will appear in event listing as hisi_sccl<sccl-id>_module<index-id>.

where "sccl-id" is the identifier of the SCCL and "index-id" is the index of

module.



e.g. hisi_sccl3_l3c0/rd_hit_cpipe is READ_HIT_CPIPE event of L3C index #0 in

SCCL ID #3.



e.g. hisi_sccl1_hha0/rx_operations is RX_OPERATIONS event of HHA index #0 in

SCCL ID #1.



The driver also provides a "cpumask" sysfs attribute, which shows the CPU core

ID used to count the uncore PMU event.



Example usage of perf:

Example usage of perf::



  $# perf list

  hisi_sccl3_l3c0/rd_hit_cpipe/ [kernel PMU event]

  ------------------------------------------

Documentation/perf/index.rst

0 → 100644
+16 −0
Original line number Diff line number Diff line 
:orphan:



===========================

Performance monitor support

===========================



.. toctree::

   :maxdepth: 1



   hisi-pmu

   qcom_l2_pmu

   qcom_l3_pmu

   arm-ccn

   xgene-pmu

   arm_dsu_pmu

   thunderx2-pmu

Documentation/perf/qcom_l2_pmu.txt→Documentation/perf/qcom_l2_pmu.rst

+2 −1
Original line number Diff line number Diff line 
=====================================================================

Qualcomm Technologies Level-2 Cache Performance Monitoring Unit (PMU)

=====================================================================
@@ -28,7 +29,7 @@ The driver provides a "cpumask" sysfs attribute which contains a mask 
consisting of one CPU per cluster which will be used to handle all the PMU

events on that cluster.



Examples for use with perf:

Examples for use with perf::



  perf stat -e l2cache_0/config=0x001/,l2cache_0/config=0x042/ -a sleep 1

CRA Git | Maintained and supported by SUSTech CRA and CCSE