tools/perf/Documentation/topdown.txt

Source file repositories/reference/linux-study-clean/tools/perf/Documentation/topdown.txt

File Facts

System
Linux kernel
Corpus path
tools/perf/Documentation/topdown.txt
Extension
.txt
Size
14210 bytes
Lines
363
Domain
Support Tooling And Documentation
Bucket
tools
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

Using TopDown metrics
---------------------

TopDown metrics break apart performance bottlenecks. Starting at level
1 it is typical to get metrics on retiring, bad speculation, frontend
bound, and backend bound. Higher levels provide more detail in to the
level 1 bottlenecks, such as at level 2: core bound, memory bound,
heavy operations, light operations, branch mispredicts, machine
clears, fetch latency and fetch bandwidth. For more details see [1][2][3].

perf stat --topdown implements this using available metrics that vary
per architecture.

% perf stat -a --topdown -I1000
#           time      %  tma_retiring %  tma_backend_bound %  tma_frontend_bound %  tma_bad_speculation
     1.001141351                 11.5                 34.9                  46.9                    6.7
     2.006141972                 13.4                 28.1                  50.4                    8.1
     3.010162040                 12.9                 28.1                  51.1                    8.0
     4.014009311                 12.5                 28.6                  51.8                    7.2
     5.017838554                 11.8                 33.0                  48.0                    7.2
     5.704818971                 14.0                 27.5                  51.3                    7.3
...

New Topdown features in Intel Ice Lake
======================================

With Ice Lake CPUs the TopDown metrics are directly available as
fixed counters and do not require generic counters. This allows
to collect TopDown always in addition to other events.

Using TopDown through RDPMC in applications on Intel Ice Lake
=============================================================

For more fine grained measurements it can be useful to
access the new  directly from user space. This is more complicated,
but drastically lowers overhead.

On Ice Lake, there is a new fixed counter 3: SLOTS, which reports
"pipeline SLOTS" (cycles multiplied by core issue width) and a
metric register that reports slots ratios for the different bottleneck
categories.

The metrics counter is CPU model specific and is not available on older
CPUs.

Example code
============

Library functions to do the functionality described below
is also available in libjevents [4]

The application opens a group with fixed counter 3 (SLOTS) and any
metric event, and allow user programs to read the performance counters.

Fixed counter 3 is mapped to a pseudo event event=0x00, umask=04,
so the perf_event_attr structure should be initialized with
{ .config = 0x0400, .type = PERF_TYPE_RAW }
The metric events are mapped to the pseudo event event=0x00, umask=0x8X.
For example, the perf_event_attr structure can be initialized with
{ .config = 0x8000, .type = PERF_TYPE_RAW } for Retiring metric event
The Fixed counter 3 must be the leader of the group.

#include <linux/perf_event.h>
#include <sys/mman.h>
#include <sys/syscall.h>
#include <unistd.h>

/* Provide own perf_event_open stub because glibc doesn't */
__attribute__((weak))
int perf_event_open(struct perf_event_attr *attr, pid_t pid,

Annotation

Implementation Notes