<!DOCTYPE html>
<html lang="en" data-content_root="../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Perf — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../_static/alabaster.css?v=3918102e" />
<script src="../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../_static/doctools.js?v=9bcbadda"></script>
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Pointer authentication in AArch64 Linux" href="pointer-authentication.html" />
<link rel="prev" title="Memory copy/set instructions (MOPS)" href="mops.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../index.html">
<img class="logo" src="../../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/index.html">All development-process docs</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../subsystem-apis.html">Subsystems</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">CPU architectures</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../arc/index.html">ARC architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../arm/index.html">ARM Architecture</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">ARM64 Architecture</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="acpi_object_usage.html">ACPI Tables</a></li>
<li class="toctree-l3"><a class="reference internal" href="amu.html">Activity Monitors Unit (AMU) extension in AArch64 Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="arm-acpi.html">ACPI on Arm systems</a></li>
<li class="toctree-l3"><a class="reference internal" href="arm-cca.html">Arm Confidential Compute Architecture</a></li>
<li class="toctree-l3"><a class="reference internal" href="asymmetric-32bit.html">Asymmetric 32-bit SoCs</a></li>
<li class="toctree-l3"><a class="reference internal" href="booting.html">Booting AArch64 Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="cpu-feature-registers.html">ARM64 CPU Feature Registers</a></li>
<li class="toctree-l3"><a class="reference internal" href="cpu-hotplug.html">CPU Hotplug and ACPI</a></li>
<li class="toctree-l3"><a class="reference internal" href="elf_hwcaps.html">ARM64 ELF hwcaps</a></li>
<li class="toctree-l3"><a class="reference internal" href="gcs.html">Guarded Control Stack support for AArch64 Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="hugetlbpage.html">HugeTLBpage on ARM64</a></li>
<li class="toctree-l3"><a class="reference internal" href="kdump.html">crashkernel memory reservation on arm64</a></li>
<li class="toctree-l3"><a class="reference internal" href="legacy_instructions.html">Legacy instructions</a></li>
<li class="toctree-l3"><a class="reference internal" href="memory.html">Memory Layout on AArch64 Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="memory-tagging-extension.html">Memory Tagging Extension (MTE) in AArch64 Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="mops.html">Memory copy/set instructions (MOPS)</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Perf</a></li>
<li class="toctree-l3"><a class="reference internal" href="pointer-authentication.html">Pointer authentication in AArch64 Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="ptdump.html">Kernel page table dump</a></li>
<li class="toctree-l3"><a class="reference internal" href="silicon-errata.html">Silicon Errata and Software Workarounds</a></li>
<li class="toctree-l3"><a class="reference internal" href="sme.html">Scalable Matrix Extension support for AArch64 Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="sve.html">Scalable Vector Extension support for AArch64 Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="tagged-address-abi.html">AArch64 TAGGED ADDRESS ABI</a></li>
<li class="toctree-l3"><a class="reference internal" href="tagged-pointers.html">Tagged virtual addresses in AArch64 Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="features.html">Feature status on arm64 architecture</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../loongarch/index.html">LoongArch Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../m68k/index.html">m68k Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mips/index.html">MIPS-specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../nios2/index.html">Nios II Specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../openrisc/index.html">OpenRISC Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../parisc/index.html">PA-RISC Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../powerpc/index.html">powerpc</a></li>
<li class="toctree-l2"><a class="reference internal" href="../riscv/index.html">RISC-V architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../s390/index.html">s390 Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sh/index.html">SuperH Interfaces Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sparc/index.html">Sparc Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../x86/index.html">x86-specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../xtensa/index.html">Xtensa Architecture</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/arch/arm64/perf.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="language-selection">
English
<ul>
<li><a href="../../translations/zh_CN/arch/arm64/perf.html">Chinese (Simplified)</a></li>
<li><a href="../../translations/zh_TW/arch/arm64/perf.html">Chinese (Traditional)</a></li>
</ul>
</div>
<section id="perf">
<span id="perf-index"></span><h1>Perf<a class="headerlink" href="#perf" title="Link to this heading">¶</a></h1>
<section id="perf-event-attributes">
<h2>Perf Event Attributes<a class="headerlink" href="#perf-event-attributes" title="Link to this heading">¶</a></h2>
<dl class="field-list simple">
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd"><p>Andrew Murray <<a class="reference external" href="mailto:andrew.murray%40arm.com">andrew<span>.</span>murray<span>@</span>arm<span>.</span>com</a>></p>
</dd>
<dt class="field-even">Date<span class="colon">:</span></dt>
<dd class="field-even"><p>2019-03-06</p>
</dd>
</dl>
<section id="exclude-user">
<h3>exclude_user<a class="headerlink" href="#exclude-user" title="Link to this heading">¶</a></h3>
<p>This attribute excludes userspace.</p>
<p>Userspace always runs at EL0 and thus this attribute will exclude EL0.</p>
</section>
<section id="exclude-kernel">
<h3>exclude_kernel<a class="headerlink" href="#exclude-kernel" title="Link to this heading">¶</a></h3>
<p>This attribute excludes the kernel.</p>
<p>The kernel runs at EL2 with VHE and EL1 without. Guest kernels always run
at EL1.</p>
<p>For the host this attribute will exclude EL1 and additionally EL2 on a VHE
system.</p>
<p>For the guest this attribute will exclude EL1. Please note that EL2 is
never counted within a guest.</p>
</section>
<section id="exclude-hv">
<h3>exclude_hv<a class="headerlink" href="#exclude-hv" title="Link to this heading">¶</a></h3>
<p>This attribute excludes the hypervisor.</p>
<p>For a VHE host this attribute is ignored as we consider the host kernel to
be the hypervisor.</p>
<p>For a non-VHE host this attribute will exclude EL2 as we consider the
hypervisor to be any code that runs at EL2 which is predominantly used for
guest/host transitions.</p>
<p>For the guest this attribute has no effect. Please note that EL2 is
never counted within a guest.</p>
</section>
<section id="exclude-host-exclude-guest">
<h3>exclude_host / exclude_guest<a class="headerlink" href="#exclude-host-exclude-guest" title="Link to this heading">¶</a></h3>
<p>These attributes exclude the KVM host and guest, respectively.</p>
<p>The KVM host may run at EL0 (userspace), EL1 (non-VHE kernel) and EL2 (VHE
kernel or non-VHE hypervisor).</p>
<p>The KVM guest may run at EL0 (userspace) and EL1 (kernel).</p>
<p>Due to the overlapping exception levels between host and guests we cannot
exclusively rely on the PMU’s hardware exception filtering - therefore we
must enable/disable counting on the entry and exit to the guest. This is
performed differently on VHE and non-VHE systems.</p>
<p>For non-VHE systems we exclude EL2 for exclude_host - upon entering and
exiting the guest we disable/enable the event as appropriate based on the
exclude_host and exclude_guest attributes.</p>
<p>For VHE systems we exclude EL1 for exclude_guest and exclude both EL0,EL2
for exclude_host. Upon entering and exiting the guest we modify the event
to include/exclude EL0 as appropriate based on the exclude_host and
exclude_guest attributes.</p>
<p>The statements above also apply when these attributes are used within a
non-VHE guest however please note that EL2 is never counted within a guest.</p>
</section>
<section id="accuracy">
<h3>Accuracy<a class="headerlink" href="#accuracy" title="Link to this heading">¶</a></h3>
<p>On non-VHE hosts we enable/disable counters on the entry/exit of host/guest
transition at EL2 - however there is a period of time between
enabling/disabling the counters and entering/exiting the guest. We are
able to eliminate counters counting host events on the boundaries of guest
entry/exit when counting guest events by filtering out EL2 for
exclude_host. However when using !exclude_hv there is a small blackout
window at the guest entry/exit where host events are not captured.</p>
<p>On VHE systems there are no blackout windows.</p>
</section>
</section>
<section id="perf-userspace-pmu-hardware-counter-access">
<h2>Perf Userspace PMU Hardware Counter Access<a class="headerlink" href="#perf-userspace-pmu-hardware-counter-access" title="Link to this heading">¶</a></h2>
<section id="overview">
<h3>Overview<a class="headerlink" href="#overview" title="Link to this heading">¶</a></h3>
<p>The perf userspace tool relies on the PMU to monitor events. It offers an
abstraction layer over the hardware counters since the underlying
implementation is cpu-dependent.
Arm64 allows userspace tools to have access to the registers storing the
hardware counters’ values directly.</p>
<p>This targets specifically self-monitoring tasks in order to reduce the overhead
by directly accessing the registers without having to go through the kernel.</p>
</section>
<section id="how-to">
<h3>How-to<a class="headerlink" href="#how-to" title="Link to this heading">¶</a></h3>
<p>The focus is set on the armv8 PMUv3 which makes sure that the access to the pmu
registers is enabled and that the userspace has access to the relevant
information in order to use them.</p>
<p>In order to have access to the hardware counters, the global sysctl
kernel/perf_user_access must first be enabled:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nb">echo</span><span class="w"> </span><span class="m">1</span><span class="w"> </span>><span class="w"> </span>/proc/sys/kernel/perf_user_access
</pre></div>
</div>
<p>It is necessary to open the event using the perf tool interface with config1:1
attr bit set: the sys_perf_event_open syscall returns a fd which can
subsequently be used with the mmap syscall in order to retrieve a page of memory
containing information about the event. The PMU driver uses this page to expose
to the user the hardware counter’s index and other necessary data. Using this
index enables the user to access the PMU registers using the <cite>mrs</cite> instruction.
Access to the PMU registers is only valid while the sequence lock is unchanged.
In particular, the PMSELR_EL0 register is zeroed each time the sequence lock is
changed.</p>
<p>The userspace access is supported in libperf using the <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">perf_evsel__mmap()</span></code>
and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">perf_evsel__read()</span></code> functions. See <a class="reference external" href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/lib/perf/tests/test-evsel.c">tools/lib/perf/tests/test-evsel.c</a> for
an example.</p>
</section>
<section id="about-heterogeneous-systems">
<h3>About heterogeneous systems<a class="headerlink" href="#about-heterogeneous-systems" title="Link to this heading">¶</a></h3>
<p>On heterogeneous systems such as big.LITTLE, userspace PMU counter access can
only be enabled when the tasks are pinned to a homogeneous subset of cores and
the corresponding PMU instance is opened by specifying the ‘type’ attribute.
The use of generic event types is not supported in this case.</p>
<p>Have a look at <a class="reference external" href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/arch/arm64/tests/user-events.c">tools/perf/arch/arm64/tests/user-events.c</a> for an example. It
can be run using the perf tool to check that the access to the registers works
correctly from userspace:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>perf<span class="w"> </span><span class="nb">test</span><span class="w"> </span>-v<span class="w"> </span>user
</pre></div>
</div>
</section>
<section id="about-chained-events-and-counter-sizes">
<h3>About chained events and counter sizes<a class="headerlink" href="#about-chained-events-and-counter-sizes" title="Link to this heading">¶</a></h3>
<p>The user can request either a 32-bit (config1:0 == 0) or 64-bit (config1:0 == 1)
counter along with userspace access. The sys_perf_event_open syscall will fail
if a 64-bit counter is requested and the hardware doesn’t support 64-bit
counters. Chained events are not supported in conjunction with userspace counter
access. If a 32-bit counter is requested on hardware with 64-bit counters, then
userspace must treat the upper 32-bits read from the counter as UNKNOWN. The
‘pmc_width’ field in the user page will indicate the valid width of the counter
and should be used to mask the upper bits as needed.</p>
</section>
</section>
<section id="event-counting-threshold">
<h2>Event Counting Threshold<a class="headerlink" href="#event-counting-threshold" title="Link to this heading">¶</a></h2>
<section id="id1">
<h3>Overview<a class="headerlink" href="#id1" title="Link to this heading">¶</a></h3>
<p>FEAT_PMUv3_TH (Armv8.8) permits a PMU counter to increment only on
events whose count meets a specified threshold condition. For example if
threshold_compare is set to 2 (‘Greater than or equal’), and the
threshold is set to 2, then the PMU counter will now only increment by
when an event would have previously incremented the PMU counter by 2 or
more on a single processor cycle.</p>
<p>To increment by 1 after passing the threshold condition instead of the
number of events on that cycle, add the ‘threshold_count’ option to the
commandline.</p>
</section>
<section id="id2">
<h3>How-to<a class="headerlink" href="#id2" title="Link to this heading">¶</a></h3>
<p>These are the parameters for controlling the feature:</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Parameter</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>threshold</p></td>
<td><p>Value to threshold the event by. A value of 0 means that
thresholding is disabled and the other parameters have no effect.</p></td>
</tr>
<tr class="row-odd"><td><p>threshold_compare</p></td>
<td><div class="line-block">
<div class="line">Comparison function to use, with the following values supported:</div>
<div class="line"><br /></div>
<div class="line">0: Not-equal</div>
<div class="line">1: Equals</div>
<div class="line">2: Greater-than-or-equal</div>
<div class="line">3: Less-than</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>threshold_count</p></td>
<td><p>If this is set, count by 1 after passing the threshold condition
instead of the value of the event on this cycle.</p></td>
</tr>
</tbody>
</table>
<p>The threshold, threshold_compare and threshold_count values can be
provided per event, for example:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>perf<span class="w"> </span>stat<span class="w"> </span>-e<span class="w"> </span>stall_slot/threshold<span class="o">=</span><span class="m">2</span>,threshold_compare<span class="o">=</span><span class="m">2</span>/<span class="w"> </span><span class="se">\</span>
<span class="w"> </span>-e<span class="w"> </span>dtlb_walk/threshold<span class="o">=</span><span class="m">10</span>,threshold_compare<span class="o">=</span><span class="m">3</span>,threshold_count/
</pre></div>
</div>
<p>In this example the stall_slot event will count by 2 or more on every
cycle where 2 or more stalls happen. And dtlb_walk will count by 1 on
every cycle where the number of dtlb walks were less than 10.</p>
<p>The maximum supported threshold value can be read from the caps of each
PMU, for example:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>cat<span class="w"> </span>/sys/bus/event_source/devices/armv8_pmuv3/caps/threshold_max
0x000000ff
</pre></div>
</div>
<p>If a value higher than this is given, then opening the event will result
in an error. The highest possible maximum is 4095, as the config field
for threshold is limited to 12 bits, and the Perf tool will refuse to
parse higher values.</p>
<p>If the PMU doesn’t support FEAT_PMUv3_TH, then threshold_max will read
0, and attempting to set a threshold value will also result in an error.
threshold_max will also read as 0 on aarch32 guests, even if the host
is running on hardware with the feature.</p>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../../_sources/arch/arm64/perf.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>