.\" -*- coding: UTF-8 -*-
.\" Copyright (c) 2012, Vincent Weaver
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" .
.\" %%%LICENSE_END
.\"
.\" This document is based on the perf_event.h header file, the
.\" tools/perf/design.txt file, and a lot of bitter experience.
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH PERF_EVENT_OPEN 2 "1 ноября 2020 г." Linux "Руководство программиста Linux"
.SH ИМЯ
perf_event_open \- настройка слежения за производительностью
.SH СИНТАКСИС
.nf
\fB#include \fP
\fB#include \fP
.PP
\fBint perf_event_open(struct perf_event_attr *\fP\fIattr\fP\fB,\fP
\fB pid_t \fP\fIpid\fP\fB, int \fP\fIcpu\fP\fB, int \fP\fIgroup_fd\fP\fB,\fP
\fB unsigned long \fP\fIflags\fP\fB);\fP
.fi
.PP
\fIЗамечание\fP: В glibc нет обёрточной функции для данного системного вызова;
смотрите ЗАМЕЧАНИЯ.
.SH ОПИСАНИЕ
Получая список параметров, \fBperf_event_open\fP() возвращает файловый
дескриптор, который можно использовать в последующих вызовах (\fBread\fP(2),
\fBmmap\fP(2), \fBprctl\fP(2), \fBfcntl\fP(2) и т. п.).
.PP
Вызов \fBperf_event_open\fP() создаёт файловый дескриптор, через который можно
получать измерения производительности. Каждый файловый дескриптор
соответствует одному измеряемому событию; события можно группировать для
одновременного измерения.
.PP
События можно включать и выключать двумя способами: через \fBioctl\fP(2) и
через \fBprctl\fP(2). Когда событие отключено, оно не учитывается и не
генерирует переполнения, но продолжает существовать и содержать своё
значение счётчика.
.PP
События бывают двух видов: подсчитывающие (counting) и измеряющие
(sampled). \fIПодсчитывающее\fP событие используется для сложения числа
произошедших событий. Обычно, результат подсчёта событий выбирается с
помощью вызова \fBread\fP(2). \fIИзмеряющее\fP событие периодически пишет значения
измерения в буфер, который доступен через вызов \fBmmap\fP(2).
.SS Аргументы
Аргументы \fIpid\fP и \fIcpu\fP позволяют задать отслеживаемый процесс и ЦП:
.TP
\fBpid == 0\fP и \fBcpu == \-1\fP
Это позволяет измерять вызывающий процесс/нить на любом ЦП.
.TP
\fBpid == 0\fP и \fBcpu >= 0\fP
Это позволяет измерять вызывающий процесс/нить только, когда выполнение
происходит на указанном ЦП.
.TP
\fBpid > 0\fP и \fBcpu == \-1\fP
Это позволяет измерять указанный процесс/нить на любом ЦП.
.TP
\fBpid > 0\fP и \fBcpu >= 0\fP
Это позволяет измерять указанный процесс/нить только, когда выполнение
происходит на указанном ЦП.
.TP
\fBpid == \-1\fP и \fBcpu >= 0\fP
This measures all processes/threads on the specified CPU. This requires
\fBCAP_PERFMON\fP (since Linux 5.8) or \fBCAP_SYS_ADMIN\fP capability or a
\fI/proc/sys/kernel/perf_event_paranoid\fP value of less than 1.
.TP
\fBpid == \-1\fP и \fBcpu == \-1\fP
Это некорректные значения и будет возвращена ошибка.
.PP
When \fIpid\fP is greater than zero, permission to perform this system call is
governed by \fBCAP_PERFMON\fP (since Linux 5.9) and a ptrace access mode
\fBPTRACE_MODE_READ_REALCREDS\fP check on older Linux versions; see
\fBptrace\fP(2).
.PP
Аргумент \fIgroup_fd\fP позволяет создавать группы событий. У группы событий
есть одно событие, которое считается лидером. Лидер создаётся самым первым и
имеет \fIgroup_fd\fP = \-1. Оставшиеся члены группы создаются последующими
вызовами \fBperf_event_open\fP() с \fIgroup_fd\fP равным файловому дескриптору
лидера группы (единственное событие создаётся с \fIgroup_fd\fP = \-1 и
считается, что группу имеет только 1 члена). Группа событий планируется для
выполнения на одном ЦП как один элемент: он помещается на ЦП только, если
все события в группе могут размещаться на ЦП. Это означает, что значения
событий\-членов могут сравниваться между собой — добавляться, делиться
(соотноситься друг с другом) и так далее — следовательно они подсчитывают
события для одного набора исполняемых инструкций.
.PP
Аргумент \fIflags\fP формируется с помощью объединения логической операцией ИЛИ
нуля или более следующих значений:
.TP
\fBPERF_FLAG_FD_CLOEXEC\fP (начиная с Linux 3.14)
.\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e
Этот флаг включает флаг close\-on\-exec на созданном файловом дескрипторе
события, то есть файловый дескриптор автоматически закрывается при
\fBexecve\fP(2). Установка флага close\-on\-exec при создании, а не в процессе
работы с помощью \fBfcntl\fP(2), позволяет избежать потенциальной
состязательности, когда вызывающая нить вызывает \fBperf_event_open\fP() и
\fBfcntl\fP(2) одновременно с запуском другой нитью вызовов \fBfork\fP(2) и
\fBexecve\fP(2).
.TP
\fBPERF_FLAG_FD_NO_GROUP\fP
Этот флаг указывает событию игнорировать параметр \fIgroup_fd\fP, если не
выполняется настройка перенаправления вывода с помощью флага
\fBPERF_FLAG_FD_OUTPUT\fP.
.TP
\fBPERF_FLAG_FD_OUTPUT\fP (не работает, начиная с Linux 2.6.35)
.\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318
Этот флаг переключает вывод измерений с буфера mmap в событие, указанное
\fIgroup_fd\fP.
.TP
\fBPERF_FLAG_PID_CGROUP\fP (начиная с Linux 2.6.39)
.\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25
Этот флаг включает поконтейнерное системное слежение. Контейнер — это
абстракция, которая изолирует набор ресурсов для их точного расходования
(ЦП, память и т. п.). В этом режиме событие измеряется только, если нить
выполняется в отслеживаемом ЦП, принадлежащем назначенному контейнеру
(cgroup). Значение cgroup задаётся переданным файловым дескриптором,
открываемом в его каталоге в файловой системе cgroupfs. Например, если
отслеживаемая cgroup называется \fItest\fP, то файловый дескриптор для
\fI/dev/cgroup/test\fP (предполагается, что cgroupfs смонтирована в
\fI/dev/cgroup\fP) должен передаваться как параметр \fIpid\fP. Слежение за cgroup
доступно только для системных событий и поэтому требуется дополнительных
прав.
.PP
Структура \fIperf_event_attr\fP предоставляет подробную информацию о
создаваемом событии.
.PP
.in +4n
.EX
struct perf_event_attr {
__u32 type; /* тип события */
__u32 size; /* размер структуры атрибутов */
__u64 config; /* настройки для типа */
union {
__u64 sample_period; /* период выборки */
__u64 sample_freq; /* частота выборки */
};
__u64 sample_type; /* значения, включённые в измерение */
__u64 read_format; /* значения, возвращаемые при чтении */
__u64 disabled : 1, /* off by default */
inherit : 1, /* children inherit it */
pinned : 1, /* must always be on PMU */
exclusive : 1, /* only group on PMU */
exclude_user : 1, /* don\(aqt count user */
exclude_kernel : 1, /* don\(aqt count kernel */
exclude_hv : 1, /* don\(aqt count hypervisor */
exclude_idle : 1, /* don\(aqt count when idle */
mmap : 1, /* include mmap data */
comm : 1, /* include comm data */
freq : 1, /* use freq, not period */
inherit_stat : 1, /* per task counts */
enable_on_exec : 1, /* next exec enables */
task : 1, /* trace fork/exit */
watermark : 1, /* wakeup_watermark */
precise_ip : 2, /* skid constraint */
mmap_data : 1, /* non\-exec mmap data */
sample_id_all : 1, /* sample_type all events */
exclude_host : 1, /* don\(aqt count in host */
exclude_guest : 1, /* don\(aqt count in guest */
exclude_callchain_kernel : 1,
/* exclude kernel callchains */
exclude_callchain_user : 1,
/* exclude user callchains */
mmap2 : 1, /* include mmap with inode data */
comm_exec : 1, /* flag comm events that are
due to exec */
use_clockid : 1, /* use clockid for time fields */
context_switch : 1, /* context switch data */
write_backward : 1, /* Write ring buffer from end
to beginning */
namespaces : 1, /* include namespaces data */
ksymbol : 1, /* include ksymbol events */
bpf_event : 1, /* include bpf events */
aux_output : 1, /* generate AUX records
instead of events */
cgroup : 1, /* include cgroup events */
text_poke : 1, /* include text poke events */
__reserved_1 : 30;
union {
__u32 wakeup_events; /* пробуждаться каждые n событий */
__u32 wakeup_watermark; /* байт до пробуждения */
};
__u32 bp_type; /* тип точки останова */
union {
__u64 bp_addr; /* адрес точки останова */
__u64 kprobe_func; /* для perf_kprobe */
__u64 uprobe_path; /* для perf_uprobe */
__u64 config1; /* расширение of config */
};
union {
__u64 bp_len; /* длина точки останова */
__u64 kprobe_addr; /* с kprobe_func == NULL */
__u64 probe_offset; /* для perf_[k,u]probe */
__u64 config2; /* расширение config1 */
};
__u64 branch_sample_type; /* enum perf_branch_sample_type */
__u64 sample_regs_user; /* пользовательские регистры,
записываемые в замер */
__u32 sample_stack_user; /* размер стека, записываемые в
замер */
__s32 clockid; /* часы, используемые в полях
времени */
__u64 sample_regs_intr; /* регистры, записываемые в замер */
__u32 aux_watermark; /* вспомогательные байт перед
пробуждением */
__u16 sample_max_stack; /* максимальное количество фреймов
в цепочке вызовов */
__u16 __reserved_2; /* выравнивание до u64 */
};
.EE
.in
.PP
Описание полей структуры \fIperf_event_attr\fP:
.TP
\fItype\fP
В этом поле указывается общий тип события. Может быть одно из следующих
значений:
.RS
.TP
\fBPERF_TYPE_HARDWARE\fP
Одно из «общих» аппаратных событий, предоставляется ядром. Подробней
смотрите в описании поля \fIconfig\fP.
.TP
\fBPERF_TYPE_SOFTWARE\fP
Одно из программных событий, предоставляется ядром (даже, если нет
аппаратной поддержки).
.TP
\fBPERF_TYPE_TRACEPOINT\fP
Точка трассировки, предоставляется ядерной инфраструктурой точек
трассировки.
.TP
\fBPERF_TYPE_HW_CACHE\fP
Событие аппаратного кэша. Создаётся специальным кодированием, смотрите
описание к полю \fIconfig\fP.
.TP
\fBPERF_TYPE_RAW\fP
«Неструктурированное», определяемое реализацией событие из поля \fIconfig\fP.
.TP
\fBPERF_TYPE_BREAKPOINT\fP (начиная с Linux 2.6.33)
.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
Аппаратная точка останова, предоставляемая ЦП. Точки останова можно
настроить на событие чтения/записи по адресу, а также на выполнение
инструкции по определённому адресу.
.TP
динамический PMU
.\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19
Начиная с Linux 2.6.38, \fBperf_event_open\fP() поддерживает несколько
PMU. Чтобы задать используемый PMU, его указывают в значении \fItype\fP,
экспортируемое ядром. Нужное значение можно найти в файловой системе sysfs:
для каждого экземпляра PMU создаётся подкаталог в каталоге
\fI/sys/bus/event_source/devices\fP. В каждом подкаталоге есть файл \fItype\fP,
содержащий целое число, которое можно использовать в поле \fItype\fP. Например,
в \fI/sys/bus/event_source/devices/cpu/type\fP содержится значение для PMU ядра
ЦП, которое, обычно равно 4.
.TP
\fBkprobe\fP и \fBuprobe\fP (начиная с Linux 4.17)
.\" commit 65074d43fc77bcae32776724b7fa2696923c78e4
.\" commit e12f03d7031a977356e3d7b75a68c2185ff8d155
.\" commit 33ea4b24277b06dbc55d7f5772a46f029600255e
Эти два динамических PMU создают kprobe/uprobe и присоединяют к файловому
дескриптору, сгенерованному perf_event_open. kprobe/uprobe будет уничтожен
при уничтожении файлового дескриптора. Подробности смотрите в описании полей
\fIkprobe_func\fP, \fIuprobe_path\fP, \fIkprobe_addr\fP и \fIprobe_offset\fP.
.RE
.TP
\fIsize\fP
Размер структуры \fIperf_event_attr\fP совместимости. Присвоение значения
\fIsizeof(struct perf_event_attr)\fP позволяет ядру видеть размер структуры во
время компиляции.
.IP
.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
.\" this was added much later when PERF_ATTR_SIZE_VER2 happened
.\" but the actual attr_size had increased in 2.6.33
.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2
.\" commit 1659d129ed014b715b0b2120e6fd929bdd33ed03
.\" commit 60e2364e60e86e81bc6377f49779779e6120977f
.\" commit 1a5941312414c71dece6717da9a0fa1303127afa
Соответствующее определение \fBPERF_ATTR_SIZE_VER0\fP равно 64; это размер
первой опубликованной структуры. Значение \fBPERF_ATTR_SIZE_VER1\fP равно 72,
соответствует добавленным в Linux 2.6.33 точкам останова. Значение
\fBPERF_ATTR_SIZE_VER2\fP равно 80, соответствует добавленным в Linux 3.4
ветвям замеров. Значение \fBPERF_ATTR_SIZE_VER3\fP равно 96, соответствует
добавленным в Linux 3.7 полям \fIsample_regs_user\fP и
\fIsample_stack_user\fP. Значение \fBPERF_ATTR_SIZE_VER4\fP равно 104,
соответствует добавленному в Linux 3.19 полю \fIsample_regs_intr\fP. Значение
\fBPERF_ATTR_SIZE_VER5\fP равно 112, соответствует добавленному в in Linux 4.1
полю \fIaux_watermark\fP.
.TP
\fIconfig\fP
Здесь указывается требуемое событие в сочетании с полем \fItype\fP. Поля
\fIconfig1\fP и \fIconfig2\fP также учитываются, если 64 бит недостаточно для
полного описания события. Кодирование значения этих полей зависит от
события.
.IP
Есть несколько способов присвоения значения полю \fIconfig\fP, которые зависят
от значения описанного ранее поля \fItype\fP. Содержимое различных возможных
настроек \fIconfig\fP выделяется по \fItype\fP.
.IP
Если \fItype\fP равно \fBPERF_TYPE_HARDWARE\fP, то измеряется одно из общих
аппаратных событий ЦП. Не все из них доступны на всех платформах. В
\fIconfig\fP может быть одно из следующих значений:
.RS 12
.TP
\fBPERF_COUNT_HW_CPU_CYCLES\fP
Общее количество циклов. Опасайтесь того, что происходит во время частотного
масштабирования ЦП.
.TP
\fBPERF_COUNT_HW_INSTRUCTIONS\fP
Запоздалые инструкции (retired instructions). Осторожно, могут влиять
различные ситуации, в основном, подсчёт аппаратных прерываний.
.TP
\fBPERF_COUNT_HW_CACHE_REFERENCES\fP
Доступ к кэшу. Обычно, учитывается доступ к кэшу последнего уровня, но для
различных ЦП может быть по\-разному. Может включать сообщения о
предварительной выборке и связности; опять же, зависит от ЦП.
.TP
\fBPERF_COUNT_HW_CACHE_MISSES\fP
Промахи кэша. Обычно, отражает промахи кэша последнего уровня; предназначена
для использования вместе с событием \fBPERF_COUNT_HW_CACHE_REFERENCES\fP для
подсчёта коэффициента промахов кэша.
.TP
\fBPERF_COUNT_HW_BRANCH_INSTRUCTIONS\fP
.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
Запоздалые инструкции ветвления. До Linux 2.6.35 использовалось неправильное
сообщение на процессорах AMD.
.TP
\fBPERF_COUNT_HW_BRANCH_MISSES\fP
Непредсказанные инструкции ветвления.
.TP
\fBPERF_COUNT_HW_BUS_CYCLES\fP
Количество циклов шины, которое может отличаться от общего количества
циклов.
.TP
\fBPERF_COUNT_HW_STALLED_CYCLES_FRONTEND\fP (начиная с Linux 3.0)
.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
Блокировано циклов во время проблемы.
.TP
\fBPERF_COUNT_HW_STALLED_CYCLES_BACKEND\fP (начиная с Linux 3.0)
.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
Блокировано циклов во время запаздывания.
.TP
\fBPERF_COUNT_HW_REF_CPU_CYCLES\fP (начиная с Linux 3.3)
.\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890
Общее количество циклов; не подвержено влиянию частотного масштабирования
ЦП.
.RE
.IP
Если значение \fItype\fP равно \fBPERF_TYPE_SOFTWARE\fP, то измеряются программные
события, предоставляемые ядром. Значением \fIconfig\fP может быть одно из
следующих:
.RS 12
.TP
\fBPERF_COUNT_SW_CPU_CLOCK\fP
Сообщить о часах ЦП, таймере высокого разрешения, работающем на каждом ЦП.
.TP
\fBPERF_COUNT_SW_TASK_CLOCK\fP
Сообщить о часах выполняющейся задачи.
.TP
\fBPERF_COUNT_SW_PAGE_FAULTS\fP
Сообщить о количестве сбойных страниц.
.TP
\fBPERF_COUNT_SW_CONTEXT_SWITCHES\fP
.\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21
Подсчёт числа переключений контекста. До Linux 2.6.34, это считалось
событиями пользовательского пространства, теперь об этом сообщается как о
происходящем в ядре.
.TP
\fBPERF_COUNT_SW_CPU_MIGRATIONS\fP
Сообщить сколько раз процесс перемещался в другой ЦП.
.TP
\fBPERF_COUNT_SW_PAGE_FAULTS_MIN\fP
Сообщить о количестве незначительных промахов страниц. Они не связаны с
обработкой дисковых операций ввода\-вывода.
.TP
\fBPERF_COUNT_SW_PAGE_FAULTS_MAJ\fP
Сообщить о количестве значительных промахов страниц. Они связаны с
обработкой дисковых операций ввода\-вывода.
.TP
\fBPERF_COUNT_SW_ALIGNMENT_FAULTS\fP (начиная с Linux 2.6.33)
.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
Сообщить о количестве ошибок выравнивания. Они возникают, когда происходит
доступ к памяти по невыровненному адресу; ядро может обработать такую
ситуацию, но это снижает производительность. Бывает только на некоторых
архитектурах (на x86 — никогда).
.TP
\fBPERF_COUNT_SW_EMULATION_FAULTS\fP (начиная с Linux 2.6.33)
.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
Сообщить о количестве ошибок эмуляции. Ядро иногда попадает в ловушки
нереализованных инструкций и эмулирует их в пользовательском
пространстве. Это может негативно отражаться на производительности.
.TP
\fBPERF_COUNT_SW_DUMMY\fP (начиная с Linux 3.12)
.\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77
Заместитель события, которое ничего не подсчитывает. This is a placeholder
event that counts nothing. Информационные образцы типов записей, таких как
mmap или comm, должны быть связаны с активным событием. Данное пустое
событие позволяет собирать такие записи без необходимости в подсчитывающем
событии.
.RE
.PP
.RS
Если \fItype\fP равно \fBPERF_TYPE_TRACEPOINT\fP, то измеряется точки трассировки
ядра. Значение, используемое в \fIconfig\fP, можно получить из debugfs
\fItracing/events/*/*/id\fP, если ftrace включён в ядре.
.RE
.PP
.RS
Если \fItype\fP равно \fBPERF_TYPE_HW_CACHE\fP, то измеряется событие кэша
аппаратного ЦП. Для вычисления соответствующего значения \fIconfig\fP
используйте следующую формулу:
.RS 4
.PP
.in +4n
.EX
config = (perf_hw_cache_id) |
(perf_hw_cache_op_id << 8) |
(perf_hw_cache_op_result_id << 16);
.EE
.in
.PP
где \fIperf_hw_cache_id\fP одно из:
.RS 4
.TP
\fBPERF_COUNT_HW_CACHE_L1D\fP
для измерения кэша данных 1\-го уровня
.TP
\fBPERF_COUNT_HW_CACHE_L1I\fP
для измерения кэша инструкций 1\-го уровня
.TP
\fBPERF_COUNT_HW_CACHE_LL\fP
для измерения кэша последнего уровня
.TP
\fBPERF_COUNT_HW_CACHE_DTLB\fP
для измерения TLB данных
.TP
\fBPERF_COUNT_HW_CACHE_ITLB\fP
для измерения TLB инструкций
.TP
\fBPERF_COUNT_HW_CACHE_BPU\fP
для измерения модуля предсказания ветвлений
.TP
\fBPERF_COUNT_HW_CACHE_NODE\fP (начиная с Linux 3.1)
.\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477
для измерения доступа к локальной памяти
.RE
.PP
и \fIperf_hw_cache_op_id\fP одно из:
.RS 4
.TP
\fBPERF_COUNT_HW_CACHE_OP_READ\fP
для доступа на чтение
.TP
\fBPERF_COUNT_HW_CACHE_OP_WRITE\fP
для доступа на запись
.TP
\fBPERF_COUNT_HW_CACHE_OP_PREFETCH\fP
для доступа предварительной выборки
.RE
.PP
и \fIperf_hw_cache_op_result_id\fP одно из:
.RS 4
.TP
\fBPERF_COUNT_HW_CACHE_RESULT_ACCESS\fP
для измерения доступа
.TP
\fBPERF_COUNT_HW_CACHE_RESULT_MISS\fP
для измерения промахов
.RE
.RE
.PP
Если \fItype\fP равно \fBPERF_TYPE_RAW\fP, то требуется пользовательское
«неструктурированное» значение \fIconfig\fP. Большинство ЦП поддерживают
события, которые не подпадают под «общие» события. Они определяются
реализацией; смотрите руководство на ЦП (например, документацию Intel
Volume 3B или AMD BIOS и руководство разработчика ядра). Для трансляции
ожидаемых значений в этом поле шестнадцатеричных значений в
\fBperf_event_open\fP() из имён справочников по архитектуре можно использовать
библиотеку libpfm4.
.PP
Если \fItype\fP равно \fBPERF_TYPE_BREAKPOINT\fP, то присвойте \fIconfig\fP значение
0. Его параметры задаются в других местах.
.PP
Если \fItype\fP равно \fBkprobe\fP или \fBuprobe\fP, установите \fIretprobe\fP (бит 0 в
\fIconfig\fP, смотрите
\fI/sys/bus/event_source/devices/[k,u]probe/format/retprobe\fP) равным
kretprobe/uretprobe. Дополнительную информацию смотрите в описании полей
\fIkprobe_func\fP, \fIuprobe_path\fP, \fIkprobe_addr\fP и \fIprobe_offset\fP.
.RE
.TP
\fIkprobe_func\fP, \fIuprobe_path\fP, \fIkprobe_addr\fP и \fIprobe_offset\fP
Эти поля описывают kprobe/uprobe в динамических PMU \fBkprobe\fP и
\fBuprobe\fP. Для \fBkprobe\fP: используйте \fIkprobe_func\fP и \fIprobe_offset\fP, или
используйте \fIkprobe_addr\fP и оставьте \fIkprobe_func\fP равным NULL. Для
\fBuprobe\fP: используйте \fIuprobe_path\fP и \fIprobe_offset\fP.
.TP
\fIsample_period\fP, \fIsample_freq\fP
«Измеряющее» событие генерирует уведомление о переполнении каждые N событий,
где N указывается в \fIsample_period\fP. У измеряющего события \fIsample_period\fP
> 0. Если происходит переполнение, то запрашиваемые данные записываются
в буфер mmap. В поле \fIsample_type\fP указывается какие данные записываются
при каждом переполнении.
.IP
Если вы хотите использовать частоту, а не период, то можно использовать
\fIsample_freq\fP. В этом случае установите флаг \fIfreq\fP. Ядро откорректирует
период измерений, чтобы попытаться достигнуть желаемой частоты. Частота
измеряется в тактах таймера.
.TP
\fIsample_type\fP
Различными битами этого поля определяется какие значения включать в
измерение. Они будут записаны в кольцевой буфер, который доступен в
пользовательском пространстве через \fBmmap\fP(2). Порядок сохраняемых значений
описан в разделе «Разбивка MMAP» ниже; он не совпадает с порядком \fIenum
perf_event_sample_format\fP.
.RS
.TP
\fBPERF_SAMPLE_IP\fP
Сохранять указатель инструкций.
.TP
\fBPERF_SAMPLE_TID\fP
Сохранять идентификатор процесса и нити.
.TP
\fBPERF_SAMPLE_TIME\fP
Сохранять метку времени.
.TP
\fBPERF_SAMPLE_ADDR\fP
Сохранять адрес (если используется).
.TP
\fBPERF_SAMPLE_READ\fP
Сохранять значения счётчика для всех событий в группе, а не только для
лидера группы.
.TP
\fBPERF_SAMPLE_CALLCHAIN\fP
Сохранять цепочку вызовов (обратная трассировка стека).
.TP
\fBPERF_SAMPLE_ID\fP
Сохранять уникальный идентификатор для открытых лидером группы событий.
.TP
\fBPERF_SAMPLE_CPU\fP
Сохранять номер ЦП.
.TP
\fBPERF_SAMPLE_PERIOD\fP
Сохранять текущий период измерения.
.TP
\fBPERF_SAMPLE_STREAM_ID\fP
Сохранять уникальный идентификатор открытого события. В отличии от
\fBPERF_SAMPLE_ID\fP возвращается реальный идентификатор, а не лидера
группы. Этот же идентификатор возвращается \fBPERF_FORMAT_ID\fP.
.TP
\fBPERF_SAMPLE_RAW\fP
Сохранять дополнительные данные, если есть. Обычно возвращаются для событий
трассировки.
.TP
\fBPERF_SAMPLE_BRANCH_STACK\fP (начиная с Linux 3.4)
.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
Сохранять запись о новых ветвях, предоставляемых аппаратурой ветвления ЦП
(например, Intel Last Branch Record). Не каждая аппаратура поддерживает
данную возможность.
.IP
В описании поля \fIbranch_sample_type\fP показано как выбирать ветви, о которых
нужно сообщать.
.TP
\fBPERF_SAMPLE_REGS_USER\fP (начиная с Linux 3.7)
.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
Записывать текущее состояние регистров ЦП на уровне пользователя (значения в
процессе до вызова ядра).
.TP
\fBPERF_SAMPLE_STACK_USER\fP (начиная с Linux 3.7)
.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
Сохранять стек пользовательского уровня для размотки стека.
.TP
\fBPERF_SAMPLE_WEIGHT\fP (начиная с Linux 3.10)
.\" commit c3feedf2aaf9ac8bad6f19f5d21e4ee0b4b87e9c
Сохранять данные аппаратуры, предоставляющие весовое значение, которое
отражает насколько затратным было измеряемое событие. Это позволяет
аппаратуре выявлять затратные события в профиле.
.TP
\fBPERF_SAMPLE_DATA_SRC\fP (начиная с Linux 3.10)
.\" commit d6be9ad6c960f43800a6f118932bc8a5a4eadcd1
Сохранять источник данных: где в иерархии памяти находятся данные, связанные
с измеряемое инструкцией. Доступно только, если поддерживается аппаратурой.
.TP
\fBPERF_SAMPLE_IDENTIFIER\fP (начиная с Linux 3.12)
.\" commit ff3d527cebc1fa3707c617bfe9e74f53fcfb0955
Помещать значение \fBSAMPLE_ID\fP в фиксированном месте записи, или в начале
(для измеряемых событий) или в конце (для не измеряемого события).
.IP
Это было необходимо потому, что поток измерений может содержать записи из
различных источников событий с различными параметрами
\fIsample_type\fP. Корректный разбор потока событий невозможен, так как для
формата записи необходимо найти \fBSAMPLE_ID\fP, но формат невозможно
определить без значения какому измерению принадлежит событие (что вызывает
циклическую зависимость).
.IP
Значение \fBPERF_SAMPLE_IDENTIFIER\fP делает поток всегда анализируемым,
помещая \fBSAMPLE_ID\fP в фиксированное расположение, несмотря на уже имеющиеся
значения \fBSAMPLE_ID\fP в записях.
.TP
\fBPERF_SAMPLE_TRANSACTION\fP (начиная с Linux 3.13)
.\" commit fdfbbd07e91f8fe387140776f3fd94605f0c89e5
Сохранять причины событий аварий транзакционной памяти (например, из
поддержки транзакционной памяти Intel TSX).
.IP
Значение \fIprecise_ip\fP должно быть больше 0 и должно измеряться событие
аварии транзакционной памяти или значения не будут записаны. Также отметим,
что некоторые измерения perf_event, такие как подсчёт числа циклов, могут
приводить к дополнительным авариям (вызванным прерыванием во время
транзакции).
.TP
\fBPERF_SAMPLE_REGS_INTR\fP (начиная с Linux 3.19)
.\" commit 60e2364e60e86e81bc6377f49779779e6120977f
Сохранять поднабор текущего состояния регистров ЦП, который определяется
\fIsample_regs_intr\fP. В отличии от \fBPERF_SAMPLE_REGS_USER\fP будут возвращены
значения регистров из состояния ядра, если произойдёт переполнение при
выполнении кода ядра. Если ЦП аппаратно поддерживает измерение состояния
регистра (PEBS в Intel x86) и \fIprecise_ip\fP больше нуля, то возвращаются
значения регистров, захваченных аппаратурой во время измерения запоздалой
инструкции.
.TP
\fBPERF_SAMPLE_PHYS_ADDR\fP (начиная с Linux 4.13)
.\" commit fc7ce9c74c3ad232b084d80148654f926d01ece7
Records physical address of data like in \fBPERF_SAMPLE_ADDR\fP.
.TP
\fBPERF_SAMPLE_CGROUP\fP (начиная с Linux 5.7)
.\" commit 96aaab686505c449e24d76e76507290dcc30e008
Records (perf_event) cgroup ID of the process. This corresponds to the
\fIid\fP field in the \fBPERF_RECORD_CGROUP\fP event.
.RE
.TP
\fIread_format\fP
В этом поле задаётся формат данных, возвращаемых \fBread\fP(2) из файлового
дескриптора \fBperf_event_open\fP().
.RS
.TP
\fBPERF_FORMAT_TOTAL_TIME_ENABLED\fP
Добавлять 64\-битное поле \fItime_enabled\fP. Его можно использовать для
вычисления общей оценки, если PMU слишком загружено и возникло
мультиплексирование.
.TP
\fBPERF_FORMAT_TOTAL_TIME_RUNNING\fP
Добавлять 64\-битное поле \fItime_running\fP. Его можно использовать для
вычисления общей оценки, если PMU слишком загружено и возникло
мультиплексирование.
.TP
\fBPERF_FORMAT_ID\fP
Добавлять 64\-битное уникальное значение, которое соответствует группе
событий.
.TP
\fBPERF_FORMAT_GROUP\fP
Позволить все значения счётчиков в группе событий читать за один проход.
.RE
.TP
\fIdisabled\fP
Битом \fIdisabled\fP определяется, будет ли счётчик изначально включен или
выключен. Если выключен, то событие может быть включено позже с помощью
\fBioctl\fP(2), \fBprctl\fP(2) или \fIenable_on_exec\fP.
.IP
Обычно, при создании группы событий значение \fIdisabled\fP лидера группы
устанавливается в 1, а у любого дочернего события \fIdisabled\fP
устанавливается в 0. Несмотря на \fIdisabled\fP равное 0, дочерние события не
запускаются до тех пор, пока не включится лидер группы.
.TP
\fIinherit\fP
Битом \fIinherit\fP задаётся, должен ли этот счётчик событий считать события
дочерних задач, кроме указанной задачи. Это применяется только к новым
потомкам, а не к существующим на момент создания счётчика (и не к новым
потомкам существующих потомков).
.IP
Наследование не работает с некоторыми комбинациями значений \fIread_format\fP,
например с \fBPERF_FORMAT_GROUP\fP.
.TP
\fIpinned\fP
Битом \fIpinned\fP определяется, что счётчик должен всегда быть на ЦП, если это
возможно. Применяется только к аппаратным счётчикам и только для лидеров
группы. Если прикреплённый счётчик невозможно поместить на ЦП (например,
потому что кончились аппаратные счётчики или возник конфликт с другим
событием), то счётчик переводится в состояние «ошибки», в котором чтение
возвращает конец файла (т. е., \fBread\fP(2) возвращает 0) до тех пор, пока
счётчик не будет включен или выключен.
.TP
\fIexclusive\fP
Битом \fIexclusive\fP определяется, что когда эта группа счётчиков на ЦП, то
должна быть только одна группа использующая счётчики ЦП. В будущем, это
может позволить следящим программам поддерживать возможности PMU,
необходимые для автономной работы без нарушения других аппаратных счётчиков.
.IP
Заметим, что многие неожиданные ситуации могут не позволить событиям с битом
\fIexclusive\fP даже выполниться. К ним относятся выполнение любых
пользовательских системных измерений, а также использование ядром счётчиков
производительности (включая обычно включённый интерфейс NMI Watchdog Timer).
.TP
\fIexclude_user\fP
Если этот бит установлен, то счётчик не учитывает события, происходящие в
пользовательском пространстве.
.TP
\fIexclude_kernel\fP
Если этот бит установлен, то счётчик не учитывает события, происходящие в
пространстве ядра.
.TP
\fIexclude_hv\fP
Если этот бит установлен, то счётчик не учитывает события, происходящие в
гипервизоре. В основном для PMU, имеющего для этого возможности (такие как
POWER). На большинстве машин необходима дополнительная поддержка для
измерений гипервизора.
.TP
\fIexclude_idle\fP
Если установлен, то счётчик не учитывает когда ЦП выполняет задачу
простоя. Хотя сейчас вы и можете включить его для любого типа события, он
игнорируется во всех кроме программных событий.
.TP
\fImmap\fP
Бит \fImmap\fP включает генерацию измерений \fBPERF_RECORD_MMAP\fP для каждого
вызова \fBmmap\fP(2) с установленными битом \fBPROT_EXEC\fP. Это позволяет
инструментам замечать новый исполняемый код, отображённый в программу
(например, общие динамические библиотеки) так, чтобы адреса можно было
отобразить обратно в первоначальный код.
.TP
\fIcomm\fP
.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
Битом \fIcomm\fP включается слежение за именем команды процесса, изменяемого
системными вызовами \fBexec\fP(2) и \fBprctl\fP(PR_SET_NAME), а также через запись
в \fI/proc/self/comm\fP. Если флаг \fIcomm_exec\fP также установлен (работает,
начиная с Linux 3.16), то можно использовать вспомогательный флаг
\fBPERF_RECORD_MISC_COMM_EXEC\fP, чтобы отличить использование \fBexec\fP(2) от
остальных.
.TP
\fIfreq\fP
Если этот бит установлен, то задания интервала измерения используется
\fIsample_frequency\fP, а не \fIsample_period\fP.
.TP
\fIinherit_stat\fP
Этот бит включает сохранение счётчика событий при переключении контекста для
наследуемых задач. Это полезно только, если установлен бит \fIinherit\fP.
.TP
\fIenable_on_exec\fP
Если этот бит установлен, то счётчик автоматически включается после вызова
\fBexec\fP(2).
.TP
\fItask\fP
Если этот бит установлен, то в кольцевой буфер включаются уведомления
fork/exit.
.TP
\fIwatermark\fP
Если установлен, то выдаётся уведомление о переполнении при пересечении
границы \fIwakeup_watermark\fP. В противном случае, уведомления о переполнении
выдаются после \fIwakeup_events\fP измерений.
.TP
\fIprecise_ip\fP (начиная с Linux 2.6.35)
.\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076
Управляет размером ската (skid). Скат — количество инструкций, выполняемое
между возникновением интересующего события и когда ядро способно
остановиться и записать событие. Чем меньше скат тем лучше: это приближает
события к инструкциям, от которых они возникли, но часто значение
ограничивается аппаратурой.
.IP
Возможными значениями этого поля могут быть:
.RS
.IP 0 3
\fBSAMPLE_IP\fP может иметь произвольный скат.
.IP 1
\fBSAMPLE_IP\fP должен иметь постоянный скат.
.IP 2
\fBSAMPLE_IP\fP запрашивает нулевой скат.
.IP 3
Значение \fBSAMPLE_IP\fP должно иметь 0 скат (skid). Смотрите также описание I
в \fBPERF_RECORD_MISC_EXACT_IP\fP().
.RE
.TP
\fImmap_data\fP (начиная с Linux 2.6.36)
.\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e
Противоположно полю \fImmap\fP. Включает генерацию измерений
\fBPERF_RECORD_MMAP\fP для вызовов \fBmmap\fP(2), у которых не установлен бит
\fBPROT_EXEC\fP (например, у данных и общей памяти SysV).
.TP
\fIsample_id_all\fP (начиная с Linux 2.6.38)
.\" commit c980d1091810df13f21aabbce545fd98f545bbf7
Если установлен, то TID, TIME, ID, STREAM_ID и ЦП могут дополнительно
включаться в не\-\fBPERF_RECORD_SAMPLE\fP, если выбран соответствующий
\fIsample_type\fP.
.IP
Если указан \fBPERF_SAMPLE_IDENTIFIER\fP, то дополнительно включается значение
ID в качестве последнего значения для облегчения разбора потока записей. Это
может привести к появлению значения \fIid\fP дважды.
.IP
Состав описывается следующей псевдо\-структурой:
.IP
.in +4n
.EX
struct sample_id {
{ u32 pid, tid; } /* если есть PERF_SAMPLE_TID */
{ u64 time; } /* если есть PERF_SAMPLE_TIME */
{ u64 id; } /* если есть PERF_SAMPLE_ID */
{ u64 stream_id;} /* если есть PERF_SAMPLE_STREAM_ID */
{ u32 cpu, res; } /* если есть PERF_SAMPLE_CPU */
{ u64 id; } /* если есть PERF_SAMPLE_IDENTIFIER */
};
.EE
.in
.TP
\fIexclude_host\fP (начиная с Linux 3.2)
.\" commit a240f76165e6255384d4bdb8139895fac7988799
При проведении измерений, которые включают процессы, запускающие экземпляры
VM (т. е. выполняют I \fBioctl\fP(2) \fBKVM_RUN\fP), измеряются только события,
возникающие внутри гостевого экземпляра. Имеет смысл только вне гостевых
машин; эта настройка не изменяет счётчики, собираемые внутри гостей. В
настоящее время работает только на x86.
.TP
\fIexclude_guest\fP (начиная с Linux 3.2)
.\" commit a240f76165e6255384d4bdb8139895fac7988799
При проведении измерений, которые включают процессы, запускающие экземпляры
VM (т. е. выполняют I \fBioctl\fP(2) \fBKVM_RUN\fP), не измеряются события,
возникающие внутри гостевого экземпляра. Имеет смысл только вне гостевых
машин; эта настройка не изменяет счётчики, собираемые внутри гостей. В
настоящее время работает только на x86.
.TP
\fIexclude_callchain_kernel\fP (начиная с Linux 3.7)
.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
Не включать цепочку вызовов ядра.
.TP
\fIexclude_callchain_user\fP (начиная с Linux 3.7)
.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
Не включать цепочку вызовов пользовательского пространства.
.TP
\fImmap2\fP (начиная с Linux 3.16)
.\" commit 13d7a2410fa637f450a29ecb515ac318ee40c741
.\" This is tricky; was committed during 3.12 development
.\" but right before release was disabled.
.\" So while you could select mmap2 starting with 3.12
.\" it did not work until 3.16
.\" commit a5a5ba72843dd05f991184d6cb9a4471acce1005
Генерировать расширенную запись выполняемого mmap, которая содержит
дополнительную информацию, достаточную для определения уникальности общих
отображений. Для работы также требуется установить флаг \fImmap\fP.
.TP
\fIcomm_exec\fP (начиная с Linux 3.16)
.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
Флаг определения свойств, не изменяет поведение ядра. Если флаг установлен,
то когда включён \fIcomm\fP, будет устанавливаться флаг
\fBPERF_RECORD_MISC_COMM_EXEC\fP в поле \fImisc\fP заголовка записи comm, если
сообщается о событии переименования, вызванного вызовом \fBexec\fP(2). Это
позволяет инструментам различать различные тип переименования процесса.
.TP
\fIuse_clockid\fP (начиная с Linux 4.1)
.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
Через \fIclockid\fP позволяет выбрать внутренние часы Linux, используемые для
генерации меток времени. Это может облегчить соответствие времён измерений с
метками времени, сгенерированными другими инструментами.
.TP
\fIcontext_switch\fP (начиная с Linux 4.3)
.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
Включает генерацию записей \fBPERF_RECORD_SWITCH\fP при переключении
контекста. Также включает генерацию записей \fBPERF_RECORD_SWITCH_CPU_WIDE\fP
при измерении в режиме CPU\-wide. Данная возможность дополняет существующие
точки трассировки и программные события для измерения переключений
контекста. Преимущество этого метода в том, что он даёт полную информацию
даже при ограничительных настройках \fIperf_event_paranoid\fP.
.TP
\fIwrite_backward\fP (начиная с Linux 4.6)
.\" commit 9ecda41acb971ebd07c8fb35faf24005c0baea12
This causes the ring buffer to be written from the end to the beginning.
This is to support reading from overwritable ring buffer.
.TP
\fInamespaces\fP (начиная с Linux 4.11)
.\" commit e422267322cd319e2695a535e47c5b1feeac45eb
This enables the generation of \fBPERF_RECORD_NAMESPACES\fP records when a task
enters a new namespace. Each namespace has a combination of device and
inode numbers.
.TP
\fIksymbol\fP (начиная с Linux 5.0)
.\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
This enables the generation of \fBPERF_RECORD_KSYMBOL\fP records when new
kernel symbols are registered or unregistered. This is analyzing dynamic
kernel functions like eBPF.
.TP
\fIbpf_event\fP (начиная с Linux 5.0)
.\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
This enables the generation of \fBPERF_RECORD_BPF_EVENT\fP records when an eBPF
program is loaded or unloaded.
.TP
\fIauxevent\fP (начиная с Linux 5.4)
.\" commit ab43762ef010967e4ccd53627f70a2eecbeafefb
This allows normal (non\-AUX) events to generate data for AUX events if the
hardware supports it.
.TP
\fIcgroup\fP (начиная с Linux 5.7)
.\" commit 96aaab686505c449e24d76e76507290dcc30e008
This enables the generation of \fBPERF_RECORD_CGROUP\fP records when a new
cgroup is created (and activated).
.TP
\fItext_poke\fP (начиная с Linux 5.8)
.\" commit e17d43b93e544f5016c0251d2074c15568d5d963
This enables the generation of \fBPERF_RECORD_TEXT_POKE\fP records when there's
a changes to the kernel text (i.e., self\-modifying code).
.TP
\fIwakeup_events\fP, \fIwakeup_watermark\fP
Это объединение задаёт как много измерений (\fIwakeup_events\fP) или байт
(\fIwakeup_watermark\fP) должно произойти до уведомления о
переполнении. Используемое поле выбирается битом флага \fIwatermark\fP.
.IP
В \fIwakeup_events\fP подсчитываются только записи с типом
\fBPERF_RECORD_SAMPLE\fP. Для приёма уведомления о переполнении всех типов
\fBPERF_RECORD\fP выберите watermark и присвойте \fIwakeup_watermark\fP значение
1.
.IP
.\" commit f506b3dc0ec454a16d40cab9ee5d75435b39dc50
До Linux 3.0 установка \fIwakeup_events\fP в 0 приводила к выключению
уведомления о переполнении; новые ядра считают 0 как 1.
.TP
\fIbp_type\fP (начиная с Linux 2.6.33)
.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
Задаёт тип точки останова. Может быть:
.RS
.TP
\fBHW_BREAKPOINT_EMPTY\fP
Нет точки останова.
.TP
\fBHW_BREAKPOINT_R\fP
Считать, когда выполняется чтение из определённого места памяти.
.TP
\fBHW_BREAKPOINT_W\fP
Считать, когда выполняется запись в определённое место памяти.
.TP
\fBHW_BREAKPOINT_RW\fP
Считать, когда выполняется чтение или запись в определённое место памяти.
.TP
\fBHW_BREAKPOINT_X\fP
Считать, когда выполняется код из определённого места памяти.
.PP
Значения можно побитово объединять, но комбинация \fBHW_BREAKPOINT_R\fP или
\fBHW_BREAKPOINT_W\fP с \fBHW_BREAKPOINT_X\fP недопустима.
.RE
.TP
\fIbp_addr\fP (начиная с Linux 2.6.33)
.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
Адрес точки останова. Для точек останова выполнения это адрес памяти
интересующей инструкции; для точек останова чтения и записи это адрес памяти
интересующего расположения в памяти.
.TP
\fIconfig1\fP (начиная с Linux 2.6.39)
.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
Значение \fIconfig1\fP используется для задания событий, которым нужен
дополнительный регистр или не хватает обычного поля config. Это поле
используется в Linux 3.3 и новее для неструктурированного OFFCORE_EVENTS на
архитектурах Nehalem/Westmere/SandyBridge.
.TP
\fIbp_len\fP (начиная с Linux 2.6.33)
.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
В \fIbp_len\fP содержится длина точки измеряемой останова, если значение
\fItype\fP равно \fBPERF_TYPE_BREAKPOINT\fP. Можно указывать
\fBHW_BREAKPOINT_LEN_1\fP, \fBHW_BREAKPOINT_LEN_2\fP, \fBHW_BREAKPOINT_LEN_4\fP и
\fBHW_BREAKPOINT_LEN_8\fP. Для точки останова выполнения присвойте
\fIsizeof(long)\fP.
.TP
\fIconfig2\fP (начиная с Linux 2.6.39)
.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
Поле \fIconfig2\fP — дальнейшее расширение поля \fIconfig1\fP.
.TP
\fIbranch_sample_type\fP (начиная с Linux 3.4)
.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
Если установлен \fBPERF_SAMPLE_BRANCH_STACK\fP, то ветви будут включаться в
запись ветви.
.IP
В первой части значения задаётся уровень привилегий, который может быть
комбинацией одного из показанных ниже значений. Если пользователь явно не
задал уровень привилегий, то ядро будет использовать уровень привилегий
события. Событие и уровни привилегий ветви не совпадают.
.RS
.TP
\fBPERF_SAMPLE_BRANCH_USER\fP
Цель ветвления в пользовательском пространстве
.TP
\fBPERF_SAMPLE_BRANCH_KERNEL\fP
Цель ветвления в пространстве ядра
.TP
\fBPERF_SAMPLE_BRANCH_HV\fP
Цель ветвления в гипервизоре.
.TP
\fBPERF_SAMPLE_BRANCH_PLM_ALL\fP
Подходящее значение состоит из трёх предшествующих значений объединённых OR.
.PP
В дополнении к значению привилегий, должно быть указано как минимум, одно из
следующих:
.TP
\fBPERF_SAMPLE_BRANCH_ANY\fP
Любой тип ветвления.
.TP
\fBPERF_SAMPLE_BRANCH_ANY_CALL\fP
Любое ветвление (прямые вызовы, косвенные вызовы и дальние переходы).
.TP
\fBPERF_SAMPLE_BRANCH_IND_CALL\fP
Косвенные вызовы.
.TP
\fBPERF_SAMPLE_BRANCH_CALL\fP (начиная с Linux 4.4)
.\" commit c229bf9dc179d2023e185c0f705bdf68484c1e73
Прямые вызовы.
.TP
\fBPERF_SAMPLE_BRANCH_ANY_RETURN\fP
Любой возврат из ветвления.
.TP
\fBPERF_SAMPLE_BRANCH_IND_JUMP\fP (начиная с Linux 4.2)
.\" commit c9fdfa14c3792c0160849c484e83aa57afd80ccc
Косвенные прыжки.
.TP
\fBPERF_SAMPLE_BRANCH_COND\fP (начиная с Linux 3.16)
.\" commit bac52139f0b7ab31330e98fd87fc5a2664951050
Ветвления по условию.
.TP
\fBPERF_SAMPLE_BRANCH_ABORT_TX\fP (начиная с Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
Аварии транзакционной памяти.
.TP
\fBPERF_SAMPLE_BRANCH_IN_TX\fP (начиная с Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
Ветвление в транзакции транзакционной памяти.
.TP
\fBPERF_SAMPLE_BRANCH_NO_TX\fP (начиная с Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
.\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70
Ветвление не транзакции транзакционной
памяти. \fBPERF_SAMPLE_BRANCH_CALL_STACK\fP (начиная с Linux 4.1) Ветвление это
часть аппаратно создаваемого стека вызовов. Требует аппаратной поддержки, в
настоящее время работает только на Intel x86 Haswell и новее.
.RE
.TP
\fIsample_regs_user\fP (начиная с Linux 3.7)
.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
Данной битовой маской задаётся набор битов пользовательских регистров ЦП,
которые сохраняются в измерениях. Значения битов в битовой маске зависят от
архитектуры и описаны в заголовочном файле ядра
\fIarch/ARCH/include/uapi/asm/perf_regs.h\fP.
.TP
\fIsample_stack_user\fP (начиная с Linux 3.7)
.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
Задаёт размер сохраняемого пользовательского стека, если указан
\fBPERF_SAMPLE_STACK_USER\fP.
.TP
\fIclockid\fP (начиная с Linux 4.1)
.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
Если установлен \fIuse_clockid\fP, то этим полем выбирается внутренний таймер
Linux, используемый для меток времени.Доступные таймеры определены в
\fIlinux/time.h\fP; в настоящее время поддерживаются \fBCLOCK_MONOTONIC\fP,
\fBCLOCK_MONOTONIC_RAW\fP, \fBCLOCK_REALTIME\fP, \fBCLOCK_BOOTTIME\fP и \fBCLOCK_TAI\fP.
.TP
\fIaux_watermark\fP (начиная с Linux 4.1)
.\" commit 1a5941312414c71dece6717da9a0fa1303127afa
Определяет какое количество данных требуется для запуска измерения
\fBPERF_RECORD_AUX\fP.
.TP
\fIsample_max_stack\fP (начиная с Linux 4.8)
.\" commit 97c79a38cd454602645f0470ffb444b3b75ce574
Если \fIsample_type\fP содержит \fBPERF_SAMPLE_CALLCHAIN\fP, то в этом поле
задаётся количество выводимых кадров стека при генерации цепочки вызовов.
.SS "Чтение результатов"
После открытия файлового дескриптора с помощью \fBperf_event_open\fP(),
значения событий доступны на чтение. События задаются вв поле \fIread_format\fP
структуры \fIattr\fP в момент открытия.
.PP
Если вы попытаетесь выполнить чтение в буфер недостаточного размера, то
результатом будет ошибка \fBENOSPC\fP.
.PP
Вот компоновка данных, возвращаемых чтением:
.IP * 2
Если указан \fBPERF_FORMAT_GROUP\fP для разрешения чтения всех событий в группе
за раз:
.IP
.in +4n
.EX
struct read_format {
u64 nr; /* количество событий */
u64 time_enabled; /* если PERF_FORMAT_TOTAL_TIME_ENABLED */
u64 time_running; /* если PERF_FORMAT_TOTAL_TIME_RUNNING */
struct {
u64 value; /* значение события */
u64 id; /* если PERF_FORMAT_ID */
} values[nr];
};
.EE
.in
.IP *
Если \fBPERF_FORMAT_GROUP\fP \fIне\fP указан:
.IP
.in +4n
.EX
struct read_format {
u64 value; /* значение события */
u64 time_enabled; /* если PERF_FORMAT_TOTAL_TIME_ENABLED */
u64 time_running; /* если PERF_FORMAT_TOTAL_TIME_RUNNING */
u64 id; /* если PERF_FORMAT_ID */
};
.EE
.in
.PP
Значения полей:
.TP
\fInr\fP
Количество событий в этом файловом дескрипторе. Доступно только, если указан
\fBPERF_FORMAT_GROUP\fP.
.TP
\fItime_enabled\fP, \fItime_running\fP
Полное время события с момента включения и выполнения. Обычно, эти значения
одинаковы. Если событий больше, чем доступно счётчиков слотов в PMU, то
возникает мультиплексирование. В этом случае события выполняются только
часть времени и значения \fItime_enabled\fP и \fItime running\fP можно
использовать для градации рассчитанного значения в счётчике.
.TP
\fIvalue\fP
Целое беззнаковое 64\-битное значение, содержащее счётчик\-результат.
.TP
\fIid\fP
Глобально уникальное значение данного события; присутствует только, если в
\fIread_format\fP указан \fBPERF_FORMAT_ID\fP.
.SS "Разбивка MMAP"
При использовании \fBperf_event_open\fP() в режиме измерений, асинхронные
события (такие как переполнение счётчика или слежение за \fBPROT_EXEC\fP mmap)
протоколируются в кольцевой буфер. Этот кольцевой буфер создаётся и доступен
через \fBmmap\fP(2).
.PP
Размер mmap должен быть 1+2^n страниц, где первая страница — страница
метаданных (\fIstruct perf_event_mmap_page\fP), в которой содержится различная
информация (например, начало кольцевого буфера).
.PP
До ядра версии 2.6.39, существовал дефект, который требовал от вас выделения
кольцевого буфера mmap при измерении, даже если доступ к нему не
планировался.
.PP
Структура первой страницы метаданных mmap:
.PP
.in +4n
.EX
struct perf_event_mmap_page {
__u32 version; /* номер версии структуры */
__u32 compat_version; /* наименьшая совместимая версия */
__u32 lock; /* seqlock для синхронизации */
__u32 index; /* идентификатор аппаратного счётчика */
__s64 offset; /* добавляется к значению аппаратного
счётчика */
__u64 time_enabled; /* время активности события */
__u64 time_running; /* время события на ЦП */
union {
__u64 capabilities;
struct {
__u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,
cap_bit0_is_deprecated : 1,
cap_user_rdpmc : 1,
cap_user_time : 1,
cap_user_time_zero : 1,
};
};
__u16 pmc_width;
__u16 time_shift;
__u32 time_mult;
__u64 time_offset;
__u64 __reserved[120]; /* дополнение до 1 k */
__u64 data_head; /* заголовок в секции данных */
__u64 data_tail; /* хвост, записываемый из
пользовательского пространства */
__u64 data_offset; /* начало буфера */
__u64 data_size; /* размер буфера данных */
__u64 aux_head;
__u64 aux_tail;
__u64 aux_offset;
__u64 aux_size;
}
.EE
.in
.PP
В следующем списке поля структуры \fIperf_event_mmap_page\fP описаны более
подробно:
.TP
\fIversion\fP
Номер версии этой структуры.
.TP
\fIcompat_version\fP
Наименьший номер версии, совместимой с данной структурой.
.TP
\fIlock\fP
Значение seqlock для синхронизации.
.TP
\fIindex\fP
Уникальный идентификатор аппаратного счётчика.
.TP
\fIoffset\fP
При использовании rdpmc для чтения это значение смещения должно добавляться
к возвращаемому rdpmc для получения текущего общего количества событий.
.TP
\fItime_enabled\fP
Время активности события.
.TP
\fItime_running\fP
Время выполнения события.
.TP
\fIcap_usr_time\fP / \fIcap_usr_rdpmc\fP / \fIcap_bit0\fP (начиная с Linux 3.4)
.\" commit c7206205d00ab375839bd6c7ddb247d600693c09
С Linux 3.4 по Linux 3.11 был дефект в определении \fIcap_usr_time\fP и
\fIcap_usr_rdpmc\fP. В обоих биты указывали на одно место, поэтому было
невозможно узнать что на самом деле установлено: \fIcap_usr_time\fP или
\fIcap_usr_rdpmc\fP.
.IP
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Начиная с Linux 3.12, они были переименованы в \fIcap_bit0\fP и вместо них вы
должны использовать поля \fIcap_user_time\fP и \fIcap_user_rdpmc\fP.
.TP
\fIcap_bit0_is_deprecated\fP (начиная с Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Если установлен, то этот бит показывает, что ядро поддерживает правильно
разделённые биты \fIcap_user_time\fP и \fIcap_user_rdpmc\fP.
.IP
Если не установлен, то это означает используется старое ядро, в котором
\fIcap_usr_time\fP и \fIcap_usr_rdpmc\fP отражают один и тот же бит, и оба
свойства нужно использовать с осторожностью.
.TP
\fIcap_user_rdpmc\fP (начиная с Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Если есть аппаратная поддержка чтения счётчиков производительности из
пользовательского пространства без системного вызова (инструкция «rdpmc» в
x86), то для чтения можно использовать следующий код:
.IP
.in +4n
.EX
u32 seq, time_mult, time_shift, idx, width;
u64 count, enabled, running;
u64 cyc, time_offset;
do {
seq = pc\->lock;
barrier();
enabled = pc\->time_enabled;
running = pc\->time_running;
if (pc\->cap_usr_time && enabled != running) {
cyc = rdtsc();
time_offset = pc\->time_offset;
time_mult = pc\->time_mult;
time_shift = pc\->time_shift;
}
idx = pc\->index;
count = pc\->offset;
if (pc\->cap_usr_rdpmc && idx) {
width = pc\->pmc_width;
count += rdpmc(idx \- 1);
}
barrier();
} while (pc\->lock != seq);
.EE
.in
.TP
\fIcap_user_time\fP (начиная с Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Этот бит указывает на наличие аппаратного, неизменяемого, неостанавливаемого
счётчика временных меток (TSC на x86).
.TP
\fIcap_user_time_zero\fP (начиная с Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Указывает на наличие \fItime_zero\fP, который позволяет отображать значения
временных меток в аппаратные часы.
.TP
\fIpmc_width\fP
Если установлен \fIcap_usr_rdpmc\fP, то это поле предоставляет ширину (в битах)
значения, считываемого с помощью rdpmc или эквивалентной инструкции. Может
использоваться для расширения знаком:
.IP
.in +4n
.EX
pmc <<= 64 \- pmc_width;
pmc >>= 64 \- pmc_width; // сдвиг знака вправо
count += pmc;
.EE
.in
.TP
\fItime_shift\fP, \fItime_mult\fP, \fItime_offset\fP
.IP
Если установлен \fIcap_usr_time\fP, то эти поля можно использоваться для
вычисления разницы времени, начиная с \fItime_enabled\fP (в наносекундах) с
помощью rdtsc или подобной инструкции.
.IP
.in +4n
.EX
u64 quot, rem;
u64 delta;
quot = cyc >> time_shift;
rem = cyc & (((u64)1 << time_shift) \- 1);
delta = time_offset + quot * time_mult +
((rem * time_mult) >> time_shift);
.EE
.in
.IP
Где \fItime_offset\fP, \fItime_mult\fP, \fItime_shift\fP и \fIcyc\fP читаются в цикле
seqcount, описанном выше. Затем эта разница может быть добавлена для
включения и, возможно, запуска (если idx) для улучшения масштабирования:
.IP
.in +4n
.EX
enabled += delta;
if (idx)
running += delta;
quot = count / running;
rem = count % running;
count = quot * enabled + (rem * enabled) / running;
.EE
.in
.TP
\fItime_zero\fP (начиная с Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
.IP
Если установлен \fIcap_usr_time_zero\fP, то аппаратные часы (счётчик временных
меток TSC на x86) могут быть вычислены из значений \fItime_zero\fP,
\fItime_mult\fP и \fItime_shift\fP:
.IP
.in +4n
.EX
time = timestamp \- time_zero;
quot = time / time_mult;
rem = time % time_mult;
cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
.EE
.in
.IP
И наоборот:
.IP
.in +4n
.EX
quot = cyc >> time_shift;
rem = cyc & (((u64)1 << time_shift) \- 1);
timestamp = time_zero + quot * time_mult +
((rem * time_mult) >> time_shift);
.EE
.in
.TP
\fIdata_head\fP
Указывает на начало секции данных. Значение непрерывно увеличивается, но не
возвращается в начало. Перед доступом к образцам его нужно возвращать в
начало вручную — на размер буфера mmap.
.IP
На платформах с SMP после чтения значения \fIdata_head\fP из пользовательского
пространства нужно вызвать функцию rmb().
.TP
\fIdata_tail\fP
Если отображение \fBPROT_WRITE\fP, то значение \fIdata_tail\fP будет записываться
из пользовательского пространства для отражения последних прочитанных
данных. В этом случае ядро не перезаписывает непрочитанные данные.
.TP
\fIdata_offset\fP (начиная с Linux 4.1)
.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
Содержит смещение расположения начала данных образца perf в буфере mmap.
.TP
\fIdata_size\fP (начиная с Linux 4.1)
.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
Содержит размер области образца perf в буфере mmap.
.TP
\fIaux_head\fP, \fIaux_tail\fP, \fIaux_offset\fP, \fIaux_size\fP (начиная с Linux 4.1)
.\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff
The AUX region allows \fBmmap\fP(2)\-ing a separate sample buffer for
high\-bandwidth data streams (separate from the main perf sample buffer). An
example of a high\-bandwidth stream is instruction tracing support, as is
found in newer Intel processors.
.IP
Для задания области AUX, сначала задайте \fIaux_offset\fP со смещением больше
чем \fIdata_offset\fP+\fIdata_size\fP, а в \fIaux_size\fP нужно указать желаемых
размер буфера. Желаемое смещение и размер должны быть выровнены по границе
страницы, и размер должен быть степенью двойки. Затем эти значения
передаются в mmap для отображения буфера AUX. Страницы буфера AUX
учитываются в ограничении ресурса \fBRLIMIT_MEMLOCK\fP (смотрите
\fBsetrlimit\fP(2)), а также проходят допустимость \fIperf_event_mlock_kb\fP.
.IP
По умолчанию буфер AUX будет обрезан, если он не вмещается в доступное
пространство кольцевого буфера. Если буфер AUX отображается только для
чтения, то он будет работать в режиме кольцевого буфера, где старые данные
перезаписываются новыми. В режиме перезаписи нельзя угадать место начала
новых данных, и задачей потребителя становится отключение измерения для
избежания возможной состязательности по данным.
.IP
Указатели кольцевого буфера \fIaux_head\fP и \fIaux_tail\fP работают и подчиняются
тем же правилам, которые описаны выше для \fIdata_head\fP и \fIdata_tail\fP.
.PP
Далее приводится раскладка страниц кольцевого буфера размером 2^n.
.PP
Если установлен \fIperf_event_attr.sample_id_all\fP, то все типы событий будут
иметь выбранные поля sample_type, относящиеся к где/когда (отличительность)
происходило событие (TID, TIME, ID, CPU, STREAM_ID), описанные в
\fBPERF_RECORD_SAMPLE\fP ниже; они будут спрятаны за \fIperf_event_header\fP и уже
имеющимися полями, то есть в записываться в конец полезных данных. Это
позволяет читать новый файл perf.data старыми инструментами perf, игнорируя
новые необязательные поля.
.PP
Значения mmap начинаются с заголовка:
.PP
.in +4n
.EX
struct perf_event_header {
__u32 type;
__u16 misc;
__u16 size;
};
.EE
.in
.PP
Далее мы опишем поля \fIperf_event_header\fP более подробно. Для простоты поля
с короткими описаниями показаны первыми.
.TP
\fIsize\fP
Показывает размер записи.
.TP
\fImisc\fP
В поле \fImisc\fP содержится дополнительная информация об образце.
.IP
По этому значению можно определить режим ЦП, наложив на него маску
\fBPERF_RECORD_MISC_CPUMODE_MASK\fP и одно из следующих значений (заметим, что
это не битовые маски, можно указывать только одно значение за раз):
.RS
.TP
\fBPERF_RECORD_MISC_CPUMODE_UNKNOWN\fP
Неизвестный режим ЦП.
.TP
\fBPERF_RECORD_MISC_KERNEL\fP
Образец возник в ядре.
.TP
\fBPERF_RECORD_MISC_USER\fP
Образец возник в пользовательском коде.
.TP
\fBPERF_RECORD_MISC_HYPERVISOR\fP
Образец возник в гипервизоре.
.TP
\fBPERF_RECORD_MISC_GUEST_KERNEL\fP (начиная с Linux 2.6.35)
.\" commit 39447b386c846bbf1c56f6403c5282837486200f
Образец возник в гостевом ядре.
.TP
\fBPERF_RECORD_MISC_GUEST_USER (начиная с Linux 2.6.35)\fP
.\" commit 39447b386c846bbf1c56f6403c5282837486200f
Образец возник в гостевом пользовательском коде.
.RE
.PP
.RS
Так как следующие три состояния сгенерированы различными типами записей, то
они указывают на один и тот же бит:
.TP
\fBPERF_RECORD_MISC_MMAP_DATA\fP (начиная с Linux 3.10)
.\" commit 2fe85427e3bf65d791700d065132772fc26e4d75
Устанавливается, когда отображение не выполняемое; в противном случае
отображение выполняемое.
.TP
\fBPERF_RECORD_MISC_COMM_EXEC\fP (начиная с Linux 3.16)
.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
Устанавливается для записи \fBPERF_RECORD_COMM\fP в ядрах новее версии Linux
3.16, если имя процесса изменено системным вызовом \fBexec\fP(2).
.TP
\fBPERF_RECORD_MISC_SWITCH_OUT\fP (начиная с Linux 4.3)
.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
При генерации записи \fBPERF_RECORD_SWITCH\fP или
\fBPERF_RECORD_SWITCH_CPU_WIDE\fP этот бит показывает, что переключение
контекста происходило из текущего процесса (а не в текущий процесс).
.RE
.PP
.RS
Также могут устанавливаться следующие биты:
.TP
\fBPERF_RECORD_MISC_EXACT_IP\fP
Показывает, что содержимое \fBPERF_SAMPLE_IP\fP указывает на актуальную
инструкцию, из\-за которой произошло событие. Смотрите также
\fIperf_event_attr.precise_ip\fP.
.TP
\fBPERF_RECORD_MISC_EXT_RESERVED\fP (начиная с Linux 2.6.35)
.\" commit 1676b8a077c352085d52578fb4f29350b58b6e74
Показывает, что доступны расширенные данные (пока не используется).
.TP
\fBPERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT\fP
.\" commit 930e6fcd2bcce9bcd9d4aa7e755678d33f3fe6f4
Данный бит не устанавливается ядром. Он зарезервирован для утилиты
пользовательского пространства perf и показывает, что разбор
\fI/proc/i[pid]/maps\fP выполнялся слишком долго и был остановлен, и поэтому
записи mmap могут быть обрезанными.
.RE
.TP
\fItype\fP
Значение \fItype\fP — одно из представленных ниже. Значения в соответствующей
записи (следующие за заголовком) зависят от выбранного \fItype\fP как описано.
.RS
.TP 4
\fBPERF_RECORD_MMAP\fP
События MMAP записывают отображения \fBPROT_EXEC\fP так, чтобы можно было
соотнести IP пользовательского пространства с кодом. Они имеют следующую
структуру:
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 pid, tid;
u64 addr;
u64 len;
u64 pgoff;
char filename[];
};
.EE
.in
.RS
.TP
\fIpid\fP
идентификатор процесса.
.TP
\fItid\fP
идентификатор нити.
.TP
\fIaddr\fP
адрес выделенной памяти. В \fIlen\fP указывается длина выделенной памяти. В
\fIpgoff\fP указывается смещение страницы выделенной памяти. В \fIfilename\fP
указывается строка, описывающая выделенную память.
.RE
.TP
\fBPERF_RECORD_LOST\fP
Эта запись указывает на потерю событий.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 id;
u64 lost;
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIid\fP
уникальный ID события утерянных образцов.
.TP
\fIlost\fP
количество потерянных событий.
.RE
.TP
\fBPERF_RECORD_COMM\fP
Эта запись указывает на изменение имени процесса.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 pid;
u32 tid;
char comm[];
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIpid\fP
идентификатор процесса.
.TP
\fItid\fP
идентификатор нити.
.TP
\fIcomm\fP
строка, содержащая новое имя процесса.
.RE
.TP
\fBPERF_RECORD_EXIT\fP
Эта запись указывает на событие выхода процесса.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 pid, ppid;
u32 tid, ptid;
u64 time;
struct sample_id sample_id;
};
.EE
.in
.TP
\fBPERF_RECORD_THROTTLE\fP, \fBPERF_RECORD_UNTHROTTLE\fP
Эта запись указывает на событие включения/выключения регулировки (throttle).
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 time;
u64 id;
u64 stream_id;
struct sample_id sample_id;
};
.EE
.in
.TP
\fBPERF_RECORD_FORK\fP
Эта запись указывает на событие порождения (fork) процесса.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 pid, ppid;
u32 tid, ptid;
u64 time;
struct sample_id sample_id;
};
.EE
.in
.TP
\fBPERF_RECORD_READ\fP
Эта запись указывает на событие чтения.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 pid, tid;
struct read_format values;
struct sample_id sample_id;
};
.EE
.in
.TP
\fBPERF_RECORD_SAMPLE\fP
Эта запись указывает на образец.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */
u64 ip; /* if PERF_SAMPLE_IP */
u32 pid, tid; /* if PERF_SAMPLE_TID */
u64 time; /* if PERF_SAMPLE_TIME */
u64 addr; /* if PERF_SAMPLE_ADDR */
u64 id; /* if PERF_SAMPLE_ID */
u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */
u32 cpu, res; /* if PERF_SAMPLE_CPU */
u64 period; /* if PERF_SAMPLE_PERIOD */
struct read_format v;
/* if PERF_SAMPLE_READ */
u64 nr; /* if PERF_SAMPLE_CALLCHAIN */
u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */
u32 size; /* if PERF_SAMPLE_RAW */
char data[size]; /* if PERF_SAMPLE_RAW */
u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */
struct perf_branch_entry lbr[bnr];
/* if PERF_SAMPLE_BRANCH_STACK */
u64 abi; /* if PERF_SAMPLE_REGS_USER */
u64 regs[weight(mask)];
/* if PERF_SAMPLE_REGS_USER */
u64 size; /* if PERF_SAMPLE_STACK_USER */
char data[size]; /* if PERF_SAMPLE_STACK_USER */
u64 dyn_size; /* if PERF_SAMPLE_STACK_USER &&
size != 0 */
u64 weight; /* if PERF_SAMPLE_WEIGHT */
u64 data_src; /* if PERF_SAMPLE_DATA_SRC */
u64 transaction; /* if PERF_SAMPLE_TRANSACTION */
u64 abi; /* if PERF_SAMPLE_REGS_INTR */
u64 regs[weight(mask)];
/* if PERF_SAMPLE_REGS_INTR */
u64 phys_addr; /* if PERF_SAMPLE_PHYS_ADDR */
u64 cgroup; /* if PERF_SAMPLE_CGROUP */
};
.EE
.in
.RS 4
.TP 4
\fIsample_id\fP
Если включён \fBPERF_SAMPLE_IDENTIFIER\fP, то добавляется уникальный 64\-битный
идентификатор. Это дубль значения \fIid\fP при \fBPERF_SAMPLE_ID\fP, но
добавляется в начало образца, для простоты получения значения анализаторами.
.TP
\fIip\fP
Если включён \fBPERF_SAMPLE_IP\fP, то добавляется значение 64\-битного указателя
инструкции.
.TP
\fIpid\fP, \fItid\fP
Если включён \fBPERF_SAMPLE_TID\fP, то добавляется 32\-битный идентификатор
процесс и 32\-битный идентификатор нити.
.TP
\fItime\fP
Если включён \fBPERF_SAMPLE_TIME\fP, то добавляется 64\-битная метка
времени. Она получается из local_clock(), которая возвращает, если возможно,
аппаратную метку времени или количество мигов, если нет.
.TP
\fIaddr\fP
Если включён \fBPERF_SAMPLE_ADDR\fP, то добавляется 64\-битный адрес. Обычно,
это адрес точки трассировки, останова или программного события; в противном
случае 0.
.TP
\fIid\fP
Если включён \fBPERF_SAMPLE_ID\fP, то добавляется 64\-битный уникальный
идентификатор. Если события является членом группы событий, то возвращается
идентификатор лидера группы. Этот идентификатор одинаков со значением,
возвращаемым при \fBPERF_FORMAT_ID\fP.
.TP
\fIstream_id\fP
Если включён \fBPERF_SAMPLE_STREAM_ID\fP, то добавляется 64\-битный уникальный
идентификатор. В отличии от \fBPERF_SAMPLE_ID\fP возвращается реальный
идентификатор, а не лидера группы. Этот же идентификатор возвращается при
\fBPERF_FORMAT_ID\fP.
.TP
\fIcpu\fP, \fIres\fP
Если включён \fBPERF_SAMPLE_CPU\fP, здесь хранится 32\-битное значение,
показывающее, какой использовался ЦП, а также зарезервированное
(неиспользуемое) 32\-битное значение.
.TP
\fIperiod\fP
Если включён \fBPERF_SAMPLE_PERIOD\fP, то записывается 64\-битное значение,
отражающее период выборки.
.TP
\fIv\fP
Если включён \fBPERF_SAMPLE_READ\fP, то добавляется структура read_format,
которая содержит значения для всех событий группы событий. Добавляемые
значения зависят от значения \fIread_format\fP, использованного во время
\fBperf_event_open\fP().
.TP
\fInr\fP, \fIips[nr]\fP
Если включён \fBPERF_SAMPLE_CALLCHAIN\fP, то добавляется 64\-битный номер,
показывающий сколько далее следует 64\-битных указателей инструкций. Это
относится к текущей цепочке вызовов.
.TP
\fIsize\fP, \fIdata[size]\fP
Если включён \fBPERF_SAMPLE_RAW\fP, то добавляется 32\-битное значение,
показывающее размер размещённого далее массива 8\-битных значений. Значения
дополняются нулями до 64\-битного.
.IP
Это неструктурированные записи с данными, скрытыми программным
интерфейсом. Не гарантируется неизменность их структуры в будущем, она может
зависеть от события, аппаратного обеспечения и версии ядра.
.TP
\fIbnr\fP, \fIlbr[bnr]\fP
Если включён \fBPERF_SAMPLE_BRANCH_STACK\fP, то добавляется 64\-битное значение,
показывающее количество записей, следующих за структурами \fIbnr\fP
\fIperf_branch_entry\fP, каждая из которых содержит следующие поля:
.RS
.TP
\fIfrom\fP
Источник инструкции (может быть не ветвление).
.TP
\fIto\fP
Цель ветвления.
.TP
\fImispred\fP
Цель ветвления предсказана ошибочно.
.TP
\fIpredicted\fP
Цель ветвления предсказана.
.TP
\fIin_tx\fP (начиная с Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
Ветвление возникло в транзакции транзакционной памяти.
.TP
\fIabort\fP (начиная с Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
Ветвление возникло в аварийной транзакции транзакционной памяти.
.TP
\fIcycles\fP (начиная с Linux 4.3)
.\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f
Количество циклов, прошедших с предыдущего обновления стека ветви.
.PP
Элементы располагаются от новых к старым, таким образом, первый указывает на
самое новое ветвление.
.PP
Поддержка \fImispred\fP, \fIpredicted\fP и \fIcycles\fP необязательна; если
отсутствует, то значения будут равны 0.
.PP
Тип сохранённых ветвлений указывается в поле \fIbranch_sample_type\fP.
.RE
.TP
\fIabi\fP, \fIregs[weight(mask)]\fP
Если включён \fBPERF_SAMPLE_REGS_USER\fP, то сохраняются пользовательские
регистры ЦП.
.IP
Значением поля \fIabi\fP может быть \fBPERF_SAMPLE_REGS_ABI_NONE\fP,
\fBPERF_SAMPLE_REGS_ABI_32\fP или \fBPERF_SAMPLE_REGS_ABI_64\fP.
.IP
В \fIregs\fP хранится массив регистров ЦП, которые были перечислены в поле
\fIsample_regs_user\fP. Количество значений определяется количеством бит,
установленных в битовой маске \fIsample_regs_user\fP.
.TP
\fIsize\fP, \fIdata[size]\fP, \fIdyn_size\fP
Если включён \fBPERF_SAMPLE_STACK_USER\fP, то сохраняется пользовательский
стек. Он может использоваться для генерации стека обратных вызовов. Значение
\fIsize\fP — размер, запрашиваемый пользователем для \fIsample_stack_user\fP или
максимальное значение записи. Значение \fIdata\fP — данные стека
(неструктурированная копия памяти, на которую указывает указатель стека во
время взятия образца). Значение \fIdyn_size\fP — количество данных, которые
были записаны (может быть меньше \fIsize\fP). Заметим, что \fIdyn_size\fP
пропускается, если \fIsize\fP равно 0.
.TP
\fIweight\fP
Если включён \fBPERF_SAMPLE_WEIGHT\fP, то добавляется 64\-битное аппаратное
значение, показывающее стоимость события. Это позволяет выделить в профилях
затратные события.
.TP
\fIdata_src\fP
Если включён \fBPERF_SAMPLE_DATA_SRC\fP, то сохраняется 64\-битное значение,
состоящее из следующих полей:
.RS
.TP 4
\fImem_op\fP
Тип кода операции, битовая комбинация из следующих значений:
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_OP_NA\fP
Недоступен
.TP
\fBPERF_MEM_OP_LOAD\fP
Инструкция загрузки
.TP
\fBPERF_MEM_OP_STORE\fP
Инструкция сохранения
.TP
\fBPERF_MEM_OP_PFETCH\fP
Предварительная выборка
.TP
\fBPERF_MEM_OP_EXEC\fP
Исполняемый код
.RE
.PD
.TP
\fImem_lvl\fP
Попадание или промах по уровням иерархии памяти, побитовая комбинация
следующего, сдвинутого влево на \fBPERF_MEM_LVL_SHIFT\fP:
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_LVL_NA\fP
Недоступен
.TP
\fBPERF_MEM_LVL_HIT\fP
Попадание
.TP
\fBPERF_MEM_LVL_MISS\fP
Промах
.TP
\fBPERF_MEM_LVL_L1\fP
Кэш 1 уровня
.TP
\fBPERF_MEM_LVL_LFB\fP
Построчно заполняемый буфер
.TP
\fBPERF_MEM_LVL_L2\fP
Кэш 2 уровня
.TP
\fBPERF_MEM_LVL_L3\fP
Кэш 3 уровня
.TP
\fBPERF_MEM_LVL_LOC_RAM\fP
Локальная оперативная память
.TP
\fBPERF_MEM_LVL_REM_RAM1\fP
Удалённая на 1 скачок оперативная память
.TP
\fBPERF_MEM_LVL_REM_RAM2\fP
Удалённая на 2 скачка оперативная память
.TP
\fBPERF_MEM_LVL_REM_CCE1\fP
Удалённый на 1 скачок кэш
.TP
\fBPERF_MEM_LVL_REM_CCE2\fP
Удалённый на 2 скачка кэш
.TP
\fBPERF_MEM_LVL_IO\fP
Память ввода\-вывода
.TP
\fBPERF_MEM_LVL_UNC\fP
Некэшируемая память
.RE
.PD
.TP
\fImem_snoop\fP
Режим подглядывания (snoop mode), побитовая комбинация следующего,
сдвинутого влево на \fBPERF_MEM_SNOOP_SHIFT\fP:
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_SNOOP_NA\fP
Недоступен
.TP
\fBPERF_MEM_SNOOP_NONE\fP
Нет подглядывания
.TP
\fBPERF_MEM_SNOOP_HIT\fP
Срабатывание подглядывания
.TP
\fBPERF_MEM_SNOOP_MISS\fP
Промах подглядывания
.TP
\fBPERF_MEM_SNOOP_HITM\fP
Срабатывание подглядывания изменено
.RE
.PD
.TP
\fImem_lock\fP
Инструкция блокировки, побитовая комбинация следующего, сдвинутого влево на
\fBPERF_MEM_LOCK_SHIFT\fP:
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_LOCK_NA\fP
Недоступен
.TP
\fBPERF_MEM_LOCK_LOCKED\fP
Заблокированная транзакция
.RE
.PD
.TP
\fImem_dtlb\fP
Попадание или промах доступа к TLB, побитовая комбинация следующего,
сдвинутого влево на \fBPERF_MEM_TLB_SHIFT\fP:
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_TLB_NA\fP
Недоступен
.TP
\fBPERF_MEM_TLB_HIT\fP
Попадание
.TP
\fBPERF_MEM_TLB_MISS\fP
Промах
.TP
\fBPERF_MEM_TLB_L1\fP
1 уровень TLB
.TP
\fBPERF_MEM_TLB_L2\fP
2 уровень TLB
.TP
\fBPERF_MEM_TLB_WK\fP
Обходчик оборудования
.TP
\fBPERF_MEM_TLB_OS\fP
Обработчик ошибок ОС
.RE
.PD
.RE
.TP
\fItransaction\fP
Если установлен флаг \fBPERF_SAMPLE_TRANSACTION\fP, то записывается 64\-битное
поле, описывающее источники аварий транзакционной памяти.
.IP
Данное поле является побитовым объединением следующих значений:
.RS
.TP
\fBPERF_TXN_ELISION\fP
Авария из\-за транзакции пропущенного типа (только для ЦП Intel).
.TP
\fBPERF_TXN_TRANSACTION\fP
Авария из\-за общей транзакции.
.TP
\fBPERF_TXN_SYNC\fP
Синхронная авария (относится к сообщению об инструкции).
.TP
\fBPERF_TXN_ASYNC\fP
Асинхронная авария (не относится к сообщению об инструкции).
.TP
\fBPERF_TXN_RETRY\fP
Повторяемая авария (повтор транзакции может привести к успешному
выполнению).
.TP
\fBPERF_TXN_CONFLICT\fP
Авария из\-за конфликта памяти между нитями.
.TP
\fBPERF_TXN_CAPACITY_WRITE\fP
Авария из\-за переполнения объёма при записи.
.TP
\fBPERF_TXN_CAPACITY_READ\fP
Авария из\-за переполнения объёма при чтении.
.RE
.IP
Также, можно получить указанный пользователем код аварии, если сдвинуть 32
бита поля вправо на \fBPERF_TXN_ABORT_SHIFT\fP и наложить маску
\fBPERF_TXN_ABORT_MASK\fP.
.TP
\fIabi\fP, \fIregs[weight(mask)]\fP
Если включён \fBPERF_SAMPLE_REGS_INTR\fP, то сохраняются пользовательские
регистры ЦП.
.IP
Значением поля \fIabi\fP может быть \fBPERF_SAMPLE_REGS_ABI_NONE\fP,
\fBPERF_SAMPLE_REGS_ABI_32\fP или \fBPERF_SAMPLE_REGS_ABI_64\fP.
.IP
В \fIregs\fP хранится массив регистров ЦП, которые были перечислены в поле
\fIsample_regs_intr\fP. Количество значений определяется количеством бит,
установленных в битовой маске \fIsample_regs_intr\fP.
.TP
\fIphys_addr\fP
If the \fBPERF_SAMPLE_PHYS_ADDR\fP flag is set, then the 64\-bit physical
address is recorded.
.TP
\fIcgroup\fP
If the \fBPERF_SAMPLE_CGROUP\fP flag is set, then the 64\-bit cgroup ID (for the
perf_event subsystem) is recorded. To get the pathname of the cgroup, the
ID should match to one in a \fBPERF_RECORD_CGROUP .\fP
.RE
.TP
\fBPERF_RECORD_MMAP2\fP
В этой записи добавлена расширенная информация вызовов \fBmmap\fP(2),
возвращающих выполняемые отображения. Формат подобен записи
\fBPERF_RECORD_MMAP\fP, до добавлены дополнительные значения, позволяющие
однозначно определить общие отображения.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 pid;
u32 tid;
u64 addr;
u64 len;
u64 pgoff;
u32 maj;
u32 min;
u64 ino;
u64 ino_generation;
u32 prot;
u32 flags;
char filename[];
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIpid\fP
идентификатор процесса.
.TP
\fItid\fP
идентификатор нити.
.TP
\fIaddr\fP
адрес выделенной памяти.
.TP
\fIlen\fP
длина выделенной памяти.
.TP
\fIpgoff\fP
смещение на странице выделенной памяти.
.TP
\fImaj\fP
основной идентификатор подлежащего устройства.
.TP
\fImin\fP
второстепенный идентификатор подлежащего устройства.
.TP
\fIino\fP
номер inode.
.TP
\fIino_generation\fP
поколение inode.
.TP
\fIprot\fP
защитная информация.
.TP
\fIflags\fP
информация о флагах.
.TP
\fIfilename\fP
строка, описывающая выделенную память.
.RE
.TP
\fBPERF_RECORD_AUX\fP (начиная с Linux 4.1)
.\" commit 68db7e98c3a6ebe7284b6cf14906ed7c55f3f7f0
Эта запись сообщает о доступности новых данных в отдельной буферной области
AUX.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 aux_offset;
u64 aux_size;
u64 flags;
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIaux_offset\fP
смещение области AUX mmap, где начинаются новые данные.
.TP
\fIaux_size\fP
размер доступных данных.
.TP
\fIflags\fP
описывает обновление AUX.
.RS
.TP
\fBPERF_AUX_FLAG_TRUNCATED\fP
Если установлен, то возвращённые данные были обрезаны до размера доступного
буфера.
.TP
\fBPERF_AUX_FLAG_OVERWRITE\fP
.\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142
Если установлен, то возвращённые данные перезаписали имеющиеся данные.
.RE
.RE
.TP
\fBPERF_RECORD_ITRACE_START\fP (начиная с Linux 4.1)
.\" ec0d7729bbaed4b9d2d3fada693278e13a3d1368
Эта запись показывает, что процесс начал событие трассировки инструкции,
который позволяет инструментам правильно соотносить адреса инструкций в
буфере AUX с подходящим исполняемым файлом.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 pid;
u32 tid;
};
.EE
.in
.RS
.TP
\fIpid\fP
идентификатор процесса нити, начавшей трассировку инструкций.
.TP
\fItid\fP
идентификатор нити для нити, начавшей трассировку инструкций.
.RE
.TP
\fBPERF_RECORD_LOST_SAMPLES\fP (начиная с Linux 4.2)
.\" f38b0dbb491a6987e198aa6b428db8692a6480f8
Если используются аппаратное измерение (такое как Intel PEBS), то данная
запись указывает, что несколько образцов могли потеряться.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 lost;
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIlost\fP
количество потенциально потерянных образцов.
.RE
.TP
\fBPERF_RECORD_SWITCH\fP (начиная с Linux 4.3)
.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
Данная запись указывает на выполнение переключения контекста. Бит
\fBPERF_RECORD_MISC_SWITCH_OUT\fP в поле \fImisc\fP показывает направление
переключение контекста — из или в текущий процесс.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
struct sample_id sample_id;
};
.EE
.in
.TP
\fBPERF_RECORD_SWITCH_CPU_WIDE\fP (начиная с Linux 4.3)
.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
Как и у \fBPERF_RECORD_SWITCH\fP данная запись показывает, что произошло
переключение контекста, но это случается только при измерении в режиме
CPU\-wide и предоставляет дополнительную информацию о направлении
переключения контекста в/из. Бит \fBPERF_RECORD_MISC_SWITCH_OUT\fP в поле
\fImisc\fP показывает направление переключения контекста: в или из текущего
процесса.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 next_prev_pid;
u32 next_prev_tid;
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fInext_prev_pid\fP
Идентификатор процесса предыдущего (если переключается в) или следующего
(если переключается из) процесса ЦП.
.TP
\fInext_prev_tid\fP
Идентификатор нити предыдущей (если переключается в) или следующей (если
переключается из) нити ЦП.
.RE
.TP
\fBPERF_RECORD_NAMESPACES\fP (начиная с Linux 4.11)
.\" commit e422267322cd319e2695a535e47c5b1feeac45eb
This record includes various namespace information of a process.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 pid;
u32 tid;
u64 nr_namespaces;
struct { u64 dev, inode } [nr_namespaces];
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIpid\fP
is the process ID
.TP
\fItid\fP
is the thread ID
.TP
\fInr_namespace\fP
is the number of namespaces in this record
.RE
.IP
Each namespace has \fIdev\fP and \fIinode\fP fields and is recorded in the fixed
position like below:
.RS
.TP
\fBNET_NS_INDEX\fP=\fB0\fP
Network namespace
.TP
\fBUTS_NS_INDEX\fP=\fB1\fP
Пространства имён UTS
.TP
\fBIPC_NS_INDEX\fP=\fB2\fP
IPC namespace
.TP
\fBPID_NS_INDEX\fP=\fB3\fP
PID namespace
.TP
\fBUSER_NS_INDEX\fP=\fB4\fP
User namespace
.TP
\fBMNT_NS_INDEX\fP=\fB5\fP
Mount namespace
.TP
\fBCGROUP_NS_INDEX\fP=\fB6\fP
Cgroup namespace
.RE
.TP
\fBPERF_RECORD_KSYMBOL\fP (начиная с Linux 5.0)
.\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
This record indicates kernel symbol register/unregister events.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 addr;
u32 len;
u16 ksym_type;
u16 flags;
char name[];
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIaddr\fP
is the address of the kernel symbol.
.TP
\fIlen\fP
is the length of the kernel symbol.
.TP
\fIksym_type\fP
is the type of the kernel symbol. Currently the following types are
available:
.RS
.TP
\fBPERF_RECORD_KSYMBOL_TYPE_BPF\fP
The kernel symbol is a BPF function.
.RE
.TP
\fIflags\fP
If the \fBPERF_RECORD_KSYMBOL_FLAGS_UNREGISTER\fP is set, then this event is
for unregistering the kernel symbol.
.RE
.TP
\fBPERF_RECORD_BPF_EVENT\fP (начиная с Linux 5.0)
.\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
This record indicates BPF program is loaded or unloaded.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u16 type;
u16 flags;
u32 id;
u8 tag[BPF_TAG_SIZE];
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fItype\fP
is one of the following values:
.RS
.TP
\fBPERF_BPF_EVENT_PROG_LOAD\fP
A BPF program is loaded
.TP
\fBPERF_BPF_EVENT_PROG_UNLOAD\fP
A BPF program is unloaded
.RE
.TP
\fIid\fP
is the ID of the BPF program.
.TP
\fItag\fP
is the tag of the BPF program. Currently, \fBBPF_TAG_SIZE\fP is defined as 8.
.RE
.TP
\fBPERF_RECORD_CGROUP\fP (начиная с Linux 5.7)
.\" commit 96aaab686505c449e24d76e76507290dcc30e008
This record indicates a new cgroup is created and activated.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 id;
char path[];
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIid\fP
is the cgroup identifier. This can be also retrieved by
\fBname_to_handle_at\fP(2) on the cgroup path (as a file handle).
.TP
\fIpath\fP
is the path of the cgroup from the root.
.RE
.TP
\fBPERF_RECORD_TEXT_POKE\fP (начиная с Linux 5.8)
.\" commit e17d43b93e544f5016c0251d2074c15568d5d963
This record indicates a change in the kernel text. This includes addition
and removal of the text and the corresponding length is zero in this case.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 addr;
u16 old_len;
u16 new_len;
u8 bytes[];
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIaddr\fP
is the address of the change
.TP
\fIold_len\fP
is the old length
.TP
\fInew_len\fP
is the new length
.TP
\fIbytes\fP
contains old bytes immediately followed by new bytes.
.RE
.RE
.SS "Обработка переполнения"
Можно задать события, которые будут уведомлять о прохождении порога,
указывающие на переполнение. Состояние переполнения можно перехватить,
проследив за файловым дескриптором событий с помощью \fBpoll\fP(2),
\fBselect\fP(2) или \fBepoll\fP(7). Или же события переполнения можно перехватить
через обработчик сигнала, включив ввод\-вывод сигналов о файловом
дескрипторе; смотрите описание операций \fBF_SETOWN\fP и \fBF_SETSIG\fP в
\fBfcntl\fP(2).
.PP
Переполнения генерируются только подсчитывающими событиями (значение
\fIsample_period\fP должно быть ненулевым).
.PP
Существует два способа генерации уведомлений о переполнении.
.PP
Первый: задать значение \fIwakeup_events\fP или \fIwakeup_watermark\fP, которые
будут срабатывать после записи определённого количества образцов или байт
кольцевой буфер mmap. В этом случае признаком служит \fBPOLL_IN\fP.
.PP
Второй: использовать ioctl \fBPERF_EVENT_IOC_REFRESH\fP. Данный ioctl
добавляется к счётчику, который уменьшается каждый раз при наступлении
события переполнения. Если значение не равно 0, то признаком служит
\fBPOLL_IN\fP, то после того, как счётчик достигнет 0, признаком становится
\fBPOLL_HUP\fP и определяющее событие отключается.
.PP
.\" See https://lkml.org/lkml/2011/5/24/337
Актуализация лидера группы событий, обновляет всех его потомков, а
актуализация с параметром 0 в настоящее время включает бесконечную
актуализацию; такое поведение не поддерживается и на него нельзя полагаться.
.PP
.\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883
Начиная с Linux 3.18, признак \fBPOLL_HUP\fP учитывается, если отслеживаемое
событие присоединено к другому процессу и этот процесс существует.
.SS "Инструкция rdpmc"
.\" commit c7206205d00ab375839bd6c7ddb247d600693c09
Начиная с Linux 3.4 на x86, вы можете использовать инструкцию \fIrdpmc\fP для
выполнения чтения с низкой задержкой без входа в ядро. Заметим, что
использование \fIrdpmc\fP необязательно быстрее других способов чтения значений
события.
.PP
Возможность использования этого можно определить по полю \fIcap_usr_rdpmc\fP
страницы mmap; документацию по вычислению событий значения можно найти в
этом разделе.
.PP
.\" 7911d3f7af14a614617e38245fedf98a724e46a9
Сначала, когда поддержка rdpmc была только включена, любой процесс (не
только с активным событием perf) мог использовать инструкцию rdpmc для
доступа к счётчикам. Начиная с Linux 4.0 поддержка rdpmc разрешена только,
если событие в данный момент включено в контексте процесса. Для возвращению
к старому поведению запишите значение 2 в \fI/sys/devices/cpu/rdpmc\fP.
.SS "Вызовы ioctl perf_event"
К файловым дескрипторам \fBperf_event_open\fP() допускаются различные вызовы
ioctl:
.TP
\fBPERF_EVENT_IOC_ENABLE\fP
Включает событие или группу событий, указанное в аргументе файлового
дескриптора.
.IP
Если в аргументе ioctl установлен бит \fBPERF_IOC_FLAG_GROUP\fP, то включаются
все события в группе, даже если указанное событие не лидер группы (но
смотрите ДЕФЕКТЫ).
.TP
\fBPERF_EVENT_IOC_DISABLE\fP
Отключает определённый счётчик или группу событий, указанный в аргументе
файлового дескриптора.
.IP
Включение или отключение лидера группы включает или выключает всю группу; то
есть пока отключён лидер группы, не считается ни один из
счётчиков. Включение или выключение члена группы (не лидера) влияет только
на этот счётчик; выключение не лидера останавливает его счётчик и не влияет
на другие счётчики.
.IP
Если в аргументе ioctl установлен бит \fBPERF_IOC_FLAG_GROUP\fP, то выключаются
все события в группе, даже если указанное событие не лидер группы (но
смотрите ДЕФЕКТЫ).
.TP
\fBPERF_EVENT_IOC_REFRESH\fP
Не унаследованные счётчики переполнения могут использовать это для установки
счётчика количества переполнений, после чего он выключается (значение
задаётся в аргументе). Последующие вызовы этого ioctl добавляют значение
аргумента в текущий счётчик. При каждом переполнении будет возникать
уведомление о переполнении с установленным \fBPOLL_IN\fP пока счётчик не
достигнет 0; когда это произойдёт, посылается уведомление с установленным
\fBPOLL_HUP\fP и событие выключается. Для значения 0 в аргументе поведение не
определено.
.TP
\fBPERF_EVENT_IOC_RESET\fP
Сбрасывает (в ноль) счётчик событий, указанный в аргументе файлового
дескриптора. Сбрасывается только счётчики; невозможно обнулить
мультиплексирующее значение \fItime_enabled\fP или \fItime_running\fP.
.IP
Если в аргументе ioctl установлен бит \fBPERF_IOC_FLAG_GROUP\fP, то
сбрасываются все события в группе, даже если указанное событие не лидер
группы (но смотрите ДЕФЕКТЫ).
.TP
\fBPERF_EVENT_IOC_PERIOD\fP
Обновляет период переполнения события.
.IP
.\" commit 3581fe0ef37ce12ac7a4f74831168352ae848edc
.\" commit bad7192b842c83e580747ca57104dd51fe08c223
Начиная с Linux 3.7 (на ARM) и Linux 3.14 (на всех остальных архитектурах),
новый период начинает действовать немедленно. В старых ядрах новый период не
работает пока не возникнет следующее переполнение.
.IP
Аргумент представляет собой указатель на 64\-битное значение, содержащее
желаемый новый период.
.IP
.\" commit ad0cf3478de8677f720ee06393b3147819568d6a
До Linux 2.6.36 данный ioctl всегда завершался с ошибкой из\-за дефекта в
ядре.
.TP
\fBPERF_EVENT_IOC_SET_OUTPUT\fP
Указывает ядру посылать уведомляющие события в указанный файловый
дескриптор, не в умолчательный. Все файловые дескрипторы должны быть на
одном ЦП.
.IP
В аргументе указывается желаемый файловый дескриптор или \-1, если вывод
нужно игнорировать.
.TP
\fBPERF_EVENT_IOC_SET_FILTER\fP (начиная с Linux 2.6.33)
.\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830
Добавить фильтр ftrace в это событие.
.IP
В аргументе указывается указатель на желаемый фильтр ftrace.
.TP
\fBPERF_EVENT_IOC_ID\fP (начиная с Linux 3.12)
.\" commit cf4957f17f2a89984915ea808876d9c82225b862
Возвращает значение идентификатора события для заданного файлового
дескриптора события.
.IP
Аргументом является указатель на 64\-битное беззнаковое целое число, в
которое будет сохранён результат.
.TP
\fBPERF_EVENT_IOC_SET_BPF\fP (начиная с Linux 4.1)
.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5
This allows attaching a Berkeley Packet Filter (BPF) program to an existing
kprobe tracepoint event. You need \fBCAP_PERFMON\fP (since Linux 5.8) or
\fBCAP_SYS_ADMIN\fP privileges to use this ioctl.
.IP
Аргументом является файловый дескриптор программы BPF, который был создан
ранее системным вызовом \fBbpf\fP(2).
.TP
\fBPERF_EVENT_IOC_PAUSE_OUTPUT\fP (начиная с Linux 4.7)
.\" commit 86e7972f690c1017fd086cdfe53d8524e68c661c
Позволяет приостанавливать и возобновлять работу кольцевого буфера
событий. Приостановленный кольцевой буфер не останавливает генерацию
измерений, а просто отбрасывает их. Отброшенные измерения считаются
пропавшими и генерируется, если возможно, измерение
\fBPERF_RECORD_LOST\fP. Сигнал переполнения по\-прежнему может возникнуть из\-за
отброшенного измерения, даже при пустом кольцевом буфере.
.IP
Аргументом является беззнаковое 32\-битное целое. Ненулевое значение
приостанавливает кольцевой буфер, а нулевое — возобновляет работу кольцевого
буфера.
.TP
\fBPERF_EVENT_MODIFY_ATTRIBUTES\fP (начиная с Linux 4.17)
.\" commit 32ff77e8cc9e66cc4fb38098f64fd54cc8f54573
Позволяет изменить существующее событие без накладных расходов на закрытие и
повторное открытие нового события. В настоящее время поддерживается только
для событий точек останова (breakpoint).
.IP
В аргументе содержится указатель на структуру \fIperf_event_attr\fP с
обновлёнными данными события.
.TP
\fBPERF_EVENT_IOC_QUERY_BPF\fP (начиная с Linux 4.16)
.\" commit f371b304f12e31fe30207c41ca7754564e0ea4dc
This allows querying which Berkeley Packet Filter (BPF) programs are
attached to an existing kprobe tracepoint. You can only attach one BPF
program per event, but you can have multiple events attached to a
tracepoint. Querying this value on one tracepoint event returns the ID of
all BPF programs in all events attached to the tracepoint. You need
\fBCAP_PERFMON\fP (since Linux 5.8) or \fBCAP_SYS_ADMIN\fP privileges to use this
ioctl.
.IP
В аргументе содержится указатель на структуру
.in +4n
.EX
struct perf_event_query_bpf {
__u32 ids_len;
__u32 prog_cnt;
__u32 ids[0];
};
.EE
.in
.IP
.\"
Значение поля \fIids_len\fP показывает сколько идентификаторов могут
поместиться в массив \fIids\fP. Значение \fIprog_cnt\fP заполняется ядром и
показывает количество присоединённых программ BPF. Массив \fIids\fP заполняется
идентификаторами каждой присоединённой программы BPF. Если имеет больше
программ, чем влезает в массив, то ядро вернёт \fBENOSPC\fP и \fIids_len\fP укажет
количество идентификаторов программ, которые были успешно скопированы.
.SS "Использование prctl(2)"
Процесс может включить или выключить все группы, в данный момент, открытых
событий (с помощью операций \fBprctl\fP(2) \fBPR_TASK_PERF_EVENTS_ENABLE\fP и
\fBPR_TASK_PERF_EVENTS_DISABLE\fP). Это применимо только к событиям созданным
локально вызывающим процессом. Это не применимо к событиям, созданным
другими процессами, присоединёнными к вызывающему процессу, или к
унаследованным от родительского процесса событиям. При этом включаются или
выключаются только лидеры групп, а не члены групп.
.SS "Файлы настройки perf_event"
Файлы в \fI/proc/sys/kernel/\fP
.RS 4
.TP
\fI/proc/sys/kernel/perf_event_paranoid\fP
Файл \fIperf_event_paranoid\fP можно использовать для ограничения доступа к
счётчикам производительности.
.IP
.PD 0
.RS
.IP 2 4
.\" default changed in commit 0161028b7c8aebef64194d3d73e43bc3b53b5c66
разрешить только измерения пользовательского пространства (по умолчанию
начиная с Linux 4.6).
.IP 1
разрешить измерения ядра и пользовательского пространства (по умолчанию
начиная с Linux 4.6).
.IP 0
разрешить доступ к данным ЦП, но не к структурированным образцам точек
трассировки.
.IP \-1
без ограничений.
.RE
.PD
.IP
Наличие файла \fIperf_event_paranoid\fP — официальный метод определения
поддержки ядром \fBperf_event_open\fP().
.TP
\fI/proc/sys/kernel/perf_event_max_sample_rate\fP
Максимальная скорость выборки. Установка слишком большого значения может
позволить пользователям задать выборку, которая скажется на
производительности машины и, возможно, заблокирует машину. Значение по
умолчанию 100000 (образов в секунду).
.TP
\fI/proc/sys/kernel/perf_event_max_stack\fP
.\" Introduced in c5dfd78eb79851e278b7973031b9ca363da87a7e
Данный файл задаёт максимальную глубину стека кадров, выдаваемых при
генерации трассировки вызова.
.TP
\fI/proc/sys/kernel/perf_event_mlock_kb\fP
Максимальное количество страниц, которое может получить непривилегированный
пользователь с помощью \fBmlock\fP(2). По умолчанию 516 (кБ).
.RE
.PP
Файлы в \fI/sys/bus/event_source/devices/\fP
.PP
.RS 4
Начиная с Linux 2.6.34, ядро поддерживает использование нескольких PMU для
слежения. Информацию о программировании этих PMU можно найти
в\fI/sys/bus/event_source/devices/\fP. Каждый подкаталог соответствует одному
PMU.
.TP
\fI/sys/bus/event_source/devices/*/type\fP (начиная с Linux 2.6.38)
.\" commit abe43400579d5de0078c2d3a760e6598e183f871
Содержит целое, которое можно использовать в поле \fItype\fP из
\fIperf_event_attr\fP, отражает, что вы хотите использовать этот PMU.
.TP
\fI/sys/bus/event_source/devices/cpu/rdpmc\fP (начиная с Linux 3.4)
.\" commit 0c9d42ed4cee2aa1dfc3a260b741baae8615744f
Если в файле значение 1, то с помощью инструкции rdpmc возможен прямой
доступ из пользовательского пространства к регистрам счётчика
производительности. Выключить доступ можно посредством записи 0 в этот файл.
.IP
.\" a66734297f78707ce39d756b656bfae861d53f62
.\" 7911d3f7af14a614617e38245fedf98a724e46a9
В Linux 4.0 это поведение изменено, теперь 1 означает лишь доступ к
процессам с активными событиями perf, а 2 возвращает старое поведение
разрешения доступа всем.
.TP
\fI/sys/bus/event_source/devices/*/format/\fP (начиная с Linux 3.4)
.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
В этом подкаталоге содержится информация по зависящим от архитектуры полям,
доступным для программирования различных полей \fIconfig\fP структуры
\fIperf_event_attr\fP.
.IP
В каждом файле содержится имя поля config, двоеточие, диапазоны бит через
запятую. Например, файл \fIevent\fP может содержать значение
\fIconfig1:1,6\-10,44\fP, что означает, что событие — атрибут, занимающий биты
1,6\(en10 и 44 в \fIperf_event_attr::config1\fP.
.TP
\fI/sys/bus/event_source/devices/*/events/\fP (начиная с Linux 3.4)
.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
В данном подкаталоге содержатся поля с предопределёнными
событиями. Содержимое — строки, описывающие настройки события в виде полей
упомянутых в каталоге \fI./format/\fP ранее. Это не обязательно полный список
всех событий, поддерживаемых PMU, но обычно это поднабор событий, считаемый
полезным.
.IP
Содержимое каждого файла — список имён атрибутов через запятую. Каждая
запись имеет необязательное значение (десятичное или шестнадцатеричное
число). Если значение не указано, то предполагается что это однобитовое поле
со значением 1. Пример: \fIevent=0x2,inv,ldlat=3\fP.
.TP
\fI/sys/bus/event_source/devices/*/uevent\fP
Данный файл — стандартное ядерное интерфейсное устройство для введения
событий на лету.
.TP
\fI/sys/bus/event_source/devices/*/cpumask\fP (начиная с Linux 3.7)
.\" commit 314d9f63f385096580e9e2a06eaa0745d92fe4ac
В файле \fIcpumask\fP содержится список целых чисел (через запятую), которые
представляют номер ЦП для каждого сокета (пакета) на материнской плате. Он
необходим для настройки внеядерных событий или событий северного моста,
поскольку эти PMU представляют события всего сокета.
.RE
.SH "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ"
Вызов \fBperf_event_open\fP() возвращает новый дескриптор файла или \-1 в случае
ошибки (в этом случае \fIerrno\fP устанавливается в соответствующее значение).
.SH ОШИБКИ
Ошибки, возвращаемые \fBperf_event_open\fP(), могут различаться на разных
процессорных архитектурах и модулях слежения за производительностью.
.TP
\fBE2BIG\fP
Возвращается, если значение \fIperf_event_attr\fP \fIsize\fP слишком мало (меньше
чем \fBPERF_ATTR_SIZE_VER0\fP), слишком велико (больше размера страницы) или
больше чем поддерживает ядро и дополнительные байты не равны нулю. При
возврате \fBE2BIG\fP ядро перезаписывает поле \fIsize\fP \fIperf_event_attr\fP
размером структуры, который ожидался.
.TP
\fBEACCES\fP
Returned when the requested event requires \fBCAP_PERFMON\fP (since Linux 5.8)
or \fBCAP_SYS_ADMIN\fP permissions (or a more permissive perf_event paranoid
setting). Some common cases where an unprivileged process may encounter
this error: attaching to a process owned by a different user; monitoring all
processes on a given CPU (i.e., specifying the \fIpid\fP argument as \-1); and
not setting \fIexclude_kernel\fP when the paranoid setting requires it.
.TP
\fBEBADF\fP
Возвращается, если файловый дескриптор \fIgroup_fd\fP некорректен, или если
установлен \fBPERF_FLAG_PID_CGROUP\fP и файловый дескриптор cgroup в \fIpid\fP
некорректен.
.TP
\fBEBUSY\fP (начиная с Linux 4.1)
.\" bed5b25ad9c8a2f5d735ef0bc746ec870c01c1b0
Возвращается, если другое событие уже владеет эксклюзивным доступом к PMU.
.TP
\fBEFAULT\fP
Возвращается, если указатель \fIattr\fP указывает на некорректный адрес памяти.
.TP
\fBEINVAL\fP
Возвращается, если указано некорректное событие. Может быть по многим
причинам. Неполный список: значение \fIsample_freq\fP больше, чем максимальное
настроенное; значение \fIcpu\fP для слежения не существует; значение
\fIread_format\fP вне пределов диапазона; значение \fIsample_type\fP вне пределов
диапазона; значение \fIflags\fP вне пределов диапазона; указано значение
\fIexclusive\fP или \fIpinned\fP и событие не является лидером группы; значения
события \fIconfig\fP вне пределов диапазона или задают зарезервированные биты;
выбранное общее событие не поддерживается; не хватает места для добавления
события.
.TP
\fBEINTR\fP
Returned when trying to mix perf and ftrace handling for a uprobe.
.TP
\fBEMFILE\fP
Каждое открытое событие использует один файловый дескриптор. Если открыто
большое количество событий, то достигается процессное ограничение на
количество открытых файловых дескрипторов и больше событий создать будет
невозможно.
.TP
\fBENODEV\fP
Возвращается, когда событие используется свойство, которое не поддерживается
текущим ЦП.
.TP
\fBENOENT\fP
Возвращается, если значение \fItype\fP некорректно. Эта ошибка также
возвращается для некоторых неподдерживаемых общих событий.
.TP
\fBENOSPC\fP
.\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6
До Linux 3.3, при недостаточности места для события возвращалось значение
\fBENOSPC\fP. В Linux 3.3 она была заменена на \fBEINVAL\fP. Значение \fBENOSPC\fP
всё ещё возвращается, если вы попытаетесь добавить больше событий точек
прерывания, чем поддерживается аппаратно.
.TP
\fBENOSYS\fP
Возвращается, если установлен \fBPERF_SAMPLE_STACK_USER\fP в \fIsample_type\fP и
не поддерживается оборудованием.
.TP
\fBEOPNOTSUPP\fP
Возвращается, если требуемое событие запрашивает специального свойства
аппаратуры, но оно отсутствует. Возникает при запросе низкоуровневых
(low\-skid) событий без поддержки, трассировке ветвления без поддержки,
выборки, если отсутствует прерывание PMU и стеки ветви для программных
событий.
.TP
\fBEOVERFLOW\fP (начиная с Linux 4.8)
.\" 97c79a38cd454602645f0470ffb444b3b75ce574
Возвращается, если запрошена \fBPERF_SAMPLE_CALLCHAIN\fP и значение
\fIsample_max_stack\fP больше максимального, указанного в
\fI/proc/sys/kernel/perf_event_max_stack\fP.
.TP
\fBEPERM\fP
Возвращается на многих (но не всех) архитектурах, если указана
неподдерживаемая настройка \fIexclude_hv\fP, \fIexclude_idle\fP, \fIexclude_user\fP
или \fIexclude_kernel\fP.
.IP
.\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34
It can also happen, as with \fBEACCES\fP, when the requested event requires
\fBCAP_PERFMON\fP (since Linux 5.8) or \fBCAP_SYS_ADMIN\fP permissions (or a more
permissive perf_event paranoid setting). This includes setting a breakpoint
on a kernel address, and (since Linux 3.13) setting a kernel function\-trace
tracepoint.
.TP
\fBESRCH\fP
Возвращается при попытке присоединения к несуществующему процессу.
.SH ВЕРСИЯ
.\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e
.\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
Системный вызов \fBperf_event_open\fP() появился в Linux 2.6.31, но с именем
\fBperf_counter_open\fP(). Он был переименован в Linux 2.6.32.
.SH "СООТВЕТСТВИЕ СТАНДАРТАМ"
Данный системный вызов \fBperf_event_open\fP() существует только в Linux и не
должен использоваться переносимых программах.
.SH ЗАМЕЧАНИЯ
В glibc нет обёртки для данного системного вызова; запускайте его с помощью
\fBsyscall\fP(2). Смотрите пример ниже.
.PP
Официальным способом наличия поддержки \fBperf_event_open\fP() является
проверка существования файла \fI/proc/sys/kernel/perf_event_paranoid\fP.
.PP
\fBCAP_PERFMON\fP capability (since Linux 5.8) provides secure approach to
performance monitoring and observability operations in a system according to
the principal of least privilege (POSIX IEEE 1003.1e). Accessing system
performance monitoring and observability operations using \fBCAP_PERFMON\fP
rather than the much more powerful \fBCAP_SYS_ADMIN\fP excludes chances to
misuse credentials and makes operations more secure. \fBCAP_SYS_ADMIN\fP usage
for secure system performance monitoring and observability is discouraged in
favor of the \fBCAP_PERFMON\fP capability.
.SH ДЕФЕКТЫ
.\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5
Значение \fBF_SETOWN_EX\fP в \fBfcntl\fP(2) требуется для правильного получения
сигналов переполнения в нитях. Появилось в Linux 2.6.32.
.PP
.\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1
До Linux 2.6.33 (как минимум, на x86), ядро не проверяло возможность
планирования события для совместной работы до чтения. Это же происходит на
всех известных ядрах при включённом сторожке NMI. Чтобы увидеть, работает ли
заданный набор событий, выполните \fBperf_event_open\fP(), запуск, затем
выполните чтения, зная наверняка, что ещё не можете получить корректные
измерения.
.PP
.\" FIXME . cannot find a kernel commit for this one
До Linux 2.6.34 ограничения на события не соблюдались ядром. В этом случае
некоторые события просто возвращали «0», если ядро планировало их в
неподходящий слот счётчика.
.PP
.\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8
До Linux 2.6.34 существовала ошибка в мультиплексировании, при котором могли
вернуться некорректные результаты.
.PP
.\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd
Ядра с Linux 2.6.35 по Linux 2.6.39 могли быстро упасть, если включено
«наследование» и запускалось много нитей.
.PP
.\" commit 050735b08ca8a016bbace4445fa025b88fee770b
До Linux 2.6.35 функция \fBPERF_FORMAT_GROUP\fP не работает с присоединёнными
процессами.
.PP
.\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02
Существует ошибка в коде ядра с Linux 2.6.36 по Linux 3.0, из\-за которой
игнорируется поле «watermark» и ядро работает, как если бы было выбрано
wakeup_event, если объединение в нём не равно нулю.
.PP
.\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e
С Linux 2.6.31 по Linux 3.4 аргумент ioctl \fBPERF_IOC_FLAG_GROUP\fP работает
неправильно и постоянно применяется к указанному событию, а не ко всем
одноуровневым событиям в группе.
.PP
.\" commit fa7315871046b9a4c48627905691dbde57e51033
С Linux 3.4 по Linux 3.11, биты mmap \fIcap_usr_rdpmc\fP и \fIcap_usr_time\fP
отображаются на одно расположение. Использующий их код нужно переписать,
использовав новые поля \fIcap_user_rdpmc\fP и \fIcap_user_time\fP.
.PP
.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
Всегда дважды проверяйте результаты! Различные обобщённые события содержат
некорректные результаты. Например, прошедшие ветви измеряются неправильно на
машинах сAMD до Linux 2.6.35.
.SH ПРИМЕРЫ
Следующий короткий пример показывает как подсчитать количество инструкций в
вызове \fBprintf\fP(3).
.PP
.EX
#include
#include
#include
#include
#include
#include
#include
static long
perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
int cpu, int group_fd, unsigned long flags)
{
int ret;
ret = syscall(__NR_perf_event_open, hw_event, pid, cpu,
group_fd, flags);
return ret;
}
int
main(int argc, char **argv)
{
struct perf_event_attr pe;
long long count;
int fd;
memset(&pe, 0, sizeof(pe));
pe.type = PERF_TYPE_HARDWARE;
pe.size = sizeof(pe);
pe.config = PERF_COUNT_HW_INSTRUCTIONS;
pe.disabled = 1;
pe.exclude_kernel = 1;
pe.exclude_hv = 1;
fd = perf_event_open(&pe, 0, \-1, \-1, 0);
if (fd == \-1) {
fprintf(stderr, "Ошибка открытия лидера %llx\en", pe.config);
exit(EXIT_FAILURE);
}
ioctl(fd, PERF_EVENT_IOC_RESET, 0);
ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);
printf("Измерение счётчика количества инструкций для этого printf\en");
ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);
read(fd, &count, sizeof(count));
printf("Использовано %lld инструкций\en", count);
close(fd);
}
.EE
.SH "СМ. ТАКЖЕ"
\fBperf\fP(1), \fBfcntl\fP(2), \fBmmap\fP(2), \fBopen\fP(2), \fBprctl\fP(2), \fBread\fP(2)
.PP
\fIDocumentation/admin\-guide/perf\-security.rst\fP in the kernel source tree
.SH ЗАМЕЧАНИЯ
Эта страница является частью проекта Linux \fIman\-pages\fP версии
5.10. Описание проекта, информацию об ошибках и последнюю версию этой
страницы можно найти по адресу \%https://www.kernel.org/doc/man\-pages/.
.PP
.SH ПЕРЕВОД
Русский перевод этой страницы руководства был сделан
Alexey,
Azamat Hackimov ,
kogamatranslator49 ,
Kogan,
Max Is ,
Yuri Kozlov
и
Иван Павлов
.
.PP
Этот перевод является бесплатной документацией; прочитайте
.UR https://www.gnu.org/licenses/gpl-3.0.html
Стандартную общественную лицензию GNU версии 3
.UE
или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.
.PP
Если вы обнаружите ошибки в переводе этой страницы руководства,
пожалуйста, отправьте электронное письмо на
.MT man-pages-ru-talks@lists.sourceforge.net
.ME .