tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: arm64: Document PMU counters access from userspace
Add documentation to describe the access to the pmu hardware counters from
userspace.
Signed-off-by: Raphael Gault <raphael.gault@arm.com>
Signed-off-by: Rob Herring <robh@kernel.org>
Link: https://lore.kernel.org/r/20211208201124.310740-6-robh@kernel.org
Signed-off-by: Will Deacon <will@kernel.org>
authored by
Raphael Gault
and committed by
Will Deacon
aa1005d1
83a7a4d6
+77
-1
+77
-1
Documentation/arm64/perf.rst
+77
-1
Documentation/arm64/perf.rst
···
2
2
3
3
.. _perf_index:
4
4
5
-
=====================
5
+
====
6
+
Perf
7
+
====
8
+
6
9
Perf Event Attributes
7
10
=====================
8
11
···
91
88
window at the guest entry/exit where host events are not captured.
92
89
93
90
On VHE systems there are no blackout windows.
91
+
92
+
Perf Userspace PMU Hardware Counter Access
93
+
==========================================
94
+
95
+
Overview
96
+
--------
97
+
The perf userspace tool relies on the PMU to monitor events. It offers an
98
+
abstraction layer over the hardware counters since the underlying
99
+
implementation is cpu-dependent.
100
+
Arm64 allows userspace tools to have access to the registers storing the
101
+
hardware counters' values directly.
102
+
103
+
This targets specifically self-monitoring tasks in order to reduce the overhead
104
+
by directly accessing the registers without having to go through the kernel.
105
+
106
+
How-to
107
+
------
108
+
The focus is set on the armv8 PMUv3 which makes sure that the access to the pmu
109
+
registers is enabled and that the userspace has access to the relevant
110
+
information in order to use them.
111
+
112
+
In order to have access to the hardware counters, the global sysctl
113
+
kernel/perf_user_access must first be enabled:
114
+
115
+
.. code-block:: sh
116
+
117
+
echo 1 > /proc/sys/kernel/perf_user_access
118
+
119
+
It is necessary to open the event using the perf tool interface with config1:1
120
+
attr bit set: the sys_perf_event_open syscall returns a fd which can
121
+
subsequently be used with the mmap syscall in order to retrieve a page of memory
122
+
containing information about the event. The PMU driver uses this page to expose
123
+
to the user the hardware counter's index and other necessary data. Using this
124
+
index enables the user to access the PMU registers using the `mrs` instruction.
125
+
Access to the PMU registers is only valid while the sequence lock is unchanged.
126
+
In particular, the PMSELR_EL0 register is zeroed each time the sequence lock is
127
+
changed.
128
+
129
+
The userspace access is supported in libperf using the perf_evsel__mmap()
130
+
and perf_evsel__read() functions. See `tools/lib/perf/tests/test-evsel.c`_ for
131
+
an example.
132
+
133
+
About heterogeneous systems
134
+
---------------------------
135
+
On heterogeneous systems such as big.LITTLE, userspace PMU counter access can
136
+
only be enabled when the tasks are pinned to a homogeneous subset of cores and
137
+
the corresponding PMU instance is opened by specifying the 'type' attribute.
138
+
The use of generic event types is not supported in this case.
139
+
140
+
Have a look at `tools/perf/arch/arm64/tests/user-events.c`_ for an example. It
141
+
can be run using the perf tool to check that the access to the registers works
142
+
correctly from userspace:
143
+
144
+
.. code-block:: sh
145
+
146
+
perf test -v user
147
+
148
+
About chained events and counter sizes
149
+
--------------------------------------
150
+
The user can request either a 32-bit (config1:0 == 0) or 64-bit (config1:0 == 1)
151
+
counter along with userspace access. The sys_perf_event_open syscall will fail
152
+
if a 64-bit counter is requested and the hardware doesn't support 64-bit
153
+
counters. Chained events are not supported in conjunction with userspace counter
154
+
access. If a 32-bit counter is requested on hardware with 64-bit counters, then
155
+
userspace must treat the upper 32-bits read from the counter as UNKNOWN. The
156
+
'pmc_width' field in the user page will indicate the valid width of the counter
157
+
and should be used to mask the upper bits as needed.
158
+
159
+
.. Links
160
+
.. _tools/perf/arch/arm64/tests/user-events.c:
161
+
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/arch/arm64/tests/user-events.c
162
+
.. _tools/lib/perf/tests/test-evsel.c:
163
+
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/lib/perf/tests/test-evsel.c