.\" -*- 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 novembre 2020" Linux "Manuel du programmeur Linux"
.SH NOM
perf_event_open \- Définir la surveillance des performances
.SH SYNOPSIS
.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
\fINote\fP\ : il n'existe pas d'enveloppe pour cet appel système dans la glibc\ ;
voir NOTES.
.SH DESCRIPTION
À partir d'une liste de paramètres, \fBperf_event_open\fP() renvoie un
descripteur de fichier, pour une utilisation dans les appels système
suivants (\fBread\fP(2), \fBmmap\fP(2), \fBprctl\fP(2), \fBfcntl\fP(2),\ etc.).
.PP
Un appel de \fBperf_event_open\fP() crée un descripteur de fichier qui permet
de mesurer les renseignements de performance. Tous les descripteurs de
fichier correspondent chacun à un événement mesuré\ ; ils peuvent être
regroupés pour mesurer plusieurs événements simultanément.
.PP
Les événements peuvent être activés et désactivés de deux façons\ : à l'aide
de \fBioctl\fP(2) ou de \fBprctl\fP(2). Quand un événement est désactivé, il ne
décompte ni ne génère de dépassement, mais continue vraiment d'exister et
maintient sa valeur de décompte.
.PP
Les événements sont de deux types\ : comptage et échantillonnage. Un
événement de \fIcomptage\fP sert à comptabiliser le nombre total d'événements
qui se produisent. En général, les résultats d'un événement de comptage sont
recueillis avec un appel \fBread\fP(2). Un événement d'\fIéchantillonnage\fP écrit
périodiquement les mesures dans un tampon qui peut ensuite être accédé à
l'aide de \fBmmap\fP(2).
.SS Arguments
Les arguments \fIpid\fP et \fIcpu\fP permettent d’indiquer le processus et le
processeur à surveiller\ :
.TP
\fBpid == 0\fP et \fBcpu == \-1\fP
Cela mesure le processus ou thread appelant sur tous les processeurs.
.TP
\fBpid == 0\fP et \fBcpu >= 0\fP
Cela ne mesure le processus ou thread appelant que s’il est en cours
d’exécution sur le processeur indiqué.
.TP
\fBpid > 0\fP et \fBcpu == \-1\fP
Cela mesure le processus ou thread indiqué sur tous les processeurs.
.TP
\fBpid > 0\fP et \fBcpu >= 0\fP
Cela ne mesure le processus ou thread indiqué que s’il est en cours
d’exécution sur le processeur indiqué.
.TP
\fBpid == \-1\fP et \fBcpu >= 0\fP
Cela mesure tous les processus et threads du processeur indiqué. Cela
nécessite la capacité \fBCAP_PERFMON\fP (depuis Linux\ 5.8) ou \fBCAP_SYS_ADMIN\fP
ou une valeur \fI/proc/sys/kernel/perf_event_paranoid\fP strictement inférieure
à \fB1\fP.
.TP
\fBpid == \-1\fP et \fBcpu == \-1\fP
Ce réglage est incorrect et renverra une erreur.
.PP
Quand \fIpid\fP est supérieur à zéro, le droit d'effectuer cet appel système
est géré par \fBCAP_PERFMON\fP (depuis Linux\ 5.9) et une vérification
\fBPTRACE_MODE_READ_REALCREDS\fP du mode d'accès ptrace sur les anciennes
versions du noyau\ ; voir \fBptrace\fP(2).
.PP
L'argument \fIgroup_fd\fP permet aux groupes d'événements d'être créés. Un
groupe d'événements a un événement qui est le leader de groupe. Le leader
est d'abord créé avec \fIgroup_fd\fP\ =\ \fB\-1\fP. Les autres membres du groupe sont
créés par les appels \fBperf_event_open\fP() suivants, avec \fIgroup_fd\fP défini
au descripteur de fichier du leader de groupe (un événement unique créé avec
\fIgroup_fd\fP\ =\ \fB\-1\fP est considéré comme formant un groupe d'un seul
membre). Un événement de groupe est programmé dans le processeur comme un
bloc\ : il ne sera mis dans le processeur que si tous les événements du
groupe peuvent être mis dans le processeur. Cela veut dire que les valeurs
des événements de tous les membres peuvent être comparées —\ ajoutées,
divisées (pour obtenir des rapports),\ etc.\ — ensemble de manière
significative, puisqu'elles ont compté les événements pendant les mêmes
instructions exécutées.
.PP
L'argument \fIflags\fP est constitué d’un \fIOU\fP binaire entre une ou plusieurs
des valeurs suivantes.
.TP
\fBPERF_FLAG_FD_CLOEXEC\fP (depuis Linux 3.14)
.\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e
Cet attribut active l’attribut «\ close\-on\-exec\ » pour le descripteur de
fichier de l’événement créé, de telle sorte que le descripteur de fichier
est automatiquement fermé par \fBexecve\fP(2). L’attribution de
«\ close\-on\-exec\ » au moment de la création, plutôt qu’ensuite avec
\fBfcntl\fP(2), évite de potentielles situations de compétition où le thread
appelant invoque \fBperf_event_open\fP() et \fBfcntl\fP() en même temps qu’un
autre thread appelle \fBfork\fP(2) puis \fBexecve\fP(2).
.TP
\fBPERF_FLAG_FD_NO_GROUP\fP
Cet attribut dit à l'événement d'ignorer le paramètre \fIgroup_fd\fP, sauf pour
initialiser la redirection de la sortie en utilisant l'attribut
\fBPERF_FLAG_FD_OUTPUT\fP.
.TP
\fBPERF_FLAG_FD_OUTPUT\fP (cassé depuis Linux 2.6.35)
.\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318
Cet attribut redirige la sortie échantillonnée de l'événement vers le tampon
mmap de l'événement indiqué par \fIgroup_fd\fP.
.TP
\fBPERF_FLAG_PID_CGROUP\fP (depuis Linux 2.6.39)
.\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25
Cet attribut active la surveillance par conteneur sur tout le système. Un
conteneur est une abstraction qui isole un ensemble de ressources à
contrôler plus finement (processeurs, mémoire,\ etc.). Dans ce mode,
l'événement n'est mesuré que si le thread exécuté sur le processeur
surveillé appartient au conteneur désigné (cgroup). Le cgroup est identifié
en passant un fichier au descripteur de fichier ouvert sur son répertoire
dans le système de fichiers cgroupfs. Par exemple, si le cgroup à surveiller
est appelé \fItest\fP, alors un descripteur de fichier ouvert sur
\fI/dev/cgroup/test\fP (en supposant que cgroupfs est monté sur \fI/dev/cgroup\fP)
doit être passé au paramètre \fIpid\fP. La surveillance de cgroup n'est
disponible que pour les événements sur tout le système et pourrait donc
nécessiter des droits supplémentaires.
.PP
La structure \fIperf_event_attr\fP fournit des renseignements de configuration
détaillés pour les événements en cours de création.
.PP
.in +4n
.EX
struct perf_event_attr {
__u32 type; /* Type d'événement */
__u32 size; /* Taille de la structure d'attributs */
__u64 config; /* Configuration spécifique au type */
union {
__u64 sample_period; /* Période d'échantillonnage */
__u64 sample_freq; /* Fréquence d'échantillonnage */
};
__u64 sample_type; /* Indique les valeurs incluses dans
l’échantillon */
__u64 read_format; /* Indique les valeurs renvoyées en
lecture */
__u64 disabled : 1, /* désactivé par défaut */
inherit : 1, /* les enfants en héritent */
pinned : 1, /* doit toujours être en PMU */
exclusive : 1, /* ne regrouper qu'en PMU */
exclude_user : 1, /* ne pas compter l'utilisateur */
exclude_kernel : 1, /* ne pas compter le noyau */
exclude_hv : 1, /* ne pas compter l'hyperviseur */
exclude_idle : 1, /* ne pas compter quand inactif */
mmap : 1, /* inclure les données mmap */
comm : 1, /* inclure les données comm */
freq : 1, /* utiliser la fréquence, pas la
période */
inherit_stat : 1, /* décomptes par tâche */
enable_on_exec : 1, /* prochain exec activé */
task : 1, /* tracer la création d’enfant
et la fin */
watermark : 1, /* wakeup_watermark */
precise_ip : 2, /* contrainte de dérapage */
mmap_data : 1, /* données mmap non exécutées */
sample_id_all : 1, /* tous les événements sample_type */
exclude_host : 1, /* ne pas compter dans l'hôte */
exclude_guest : 1, /* ne pas compter dans l'invité */
exclude_callchain_kernel : 1,
/* exclure les appels en chaîne
du noyau */
exclude_callchain_user : 1,
/* exclure les appels en chaîne
d’utilisateur */
mmap2 : 1, /* inclure mmap avec les données d'inœud */
comm_exec : 1, /* événements flag comm devant être
exécutés */
use_clockid : 1, /* utiliser clockid pour les champs de temps */
context_switch : 1, /* données de changement de contexte */
write_backward : 1, /* Écrire le tampon circulaire de la fin
vers le début */
namespaces : 1, /* inclure les données des espaces de noms */
ksymbol : 1, /* inclure les événements ksymbol */
bpf_event : 1, /* inclure les événements BPF */
aux_output : 1, /* générer les enregistrements AUX au lieu des
événements */
cgroup : 1, /* inclure les événements cgroup */
text_poke : 1, /* inclure les événements de poke de texte */
__reserved_1 : 30;
union {
__u32 wakeup_events; /* réveil tous les n événements */
__u32 wakeup_watermark; /* octets avant le réveil */
};
__u32 bp_type; /* type de point d'arrêt */
union {
__u64 bp_addr; /* adresse de point d'arrêt */
__u64 kprobe_func; /* pour perf_kprobe */
__u64 uprobe_path; /* pour perf_uprobe */
__u64 config1; /* extension de config */
};
union {
__u64 bp_len; /* taille de point d'arrêt */
__u64 kprobe_addr; /* avec kprobe_func == NULL */
__u64 probe_offset; /* pour perf_[k,u]probe */
__u64 config2; /* extension de config1 */
};
__u64 branch_sample_type; /* enum perf_branch_sample_type */
__u64 sample_regs_user; /* registres utilisateur à renvoyer
dans les échantillons */
__u32 sample_stack_user; /* taille de pile à renvoyer dans
les échantillons */
__s32 clockid; /* horloge à utiliser pour les champs
de temps */
__u64 sample_regs_intr; /* registres à renvoyer dans les
échantillons */
__u32 aux_watermark; /* octets supp. avant le réveil */
__u16 sample_max_stack; /* nombre maximal de trames dans la
chaîne d'appel */
__u32 __reserved_2; /* aligner sur u64 */
};
.EE
.in
.PP
Les champs de la structure \fIperf_event_attr\fP sont décrits en détail
ci\-dessous.
.TP
\fItype\fP
Ce champ indique le type d'événement dans son ensemble. Il a une des valeurs
suivantes\ :
.RS
.TP
\fBPERF_TYPE_HARDWARE\fP
Cela indique un des événements matériels «\ généralisés\ » fournis par le
noyau. Consultez la définition du champ \fIconfig\fP pour plus de précisions.
.TP
\fBPERF_TYPE_SOFTWARE\fP
Cela indique un des événements logiciels fournis par le noyau (même si
aucune prise en charge matérielle n'est disponible).
.TP
\fBPERF_TYPE_TRACEPOINT\fP
Cela indique un point de trace fourni par l'infrastructure de point de trace
du noyau.
.TP
\fBPERF_TYPE_HW_CACHE\fP
Cela indique un événement de cache matériel. Cela a un encodage particulier
décrit dans la définition du champ \fIconfig\fP.
.TP
\fBPERF_TYPE_RAW\fP
Cela indique un événement «\ brut\ » spécifique à l'implémentation dans le
champ \fIconfig\fP.
.TP
\fBPERF_TYPE_BREAKPOINT\fP (depuis Linux 2.6.33)
.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
Cela indique un point d'arrêt matériel tel que fourni par le processeur. Les
points d'arrêt peuvent être des accès en lecture ou écriture sur une adresse
ainsi que l'exécution d'une adresse d'instruction.
.TP
PMU dynamique
.\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19
Depuis Linux\ 2.6.38, \fBperf_event_open\fP() permet de gérer plusieurs
PMU. Pour activer cela, une valeur exportée par le noyau peut être utilisée
dans le champ \fItype\fP pour indiquer la PMU à utiliser. La valeur à utiliser
est trouvable dans le système de fichiers sysfs\ : un sous\-répertoire existe
par instance PMU sous \fI/sys/bus/event_source/devices\fP. Le fichier \fItype\fP
dans chaque sous\-répertoire contient un entier qui peut être utilisé dans le
champ \fItype\fP. Par exemple, \fI/sys/bus/event_source/devices/cpu/type\fP
contient la valeur de PMU du processeur principal, c'est\-à\-dire 4 en
général.
.TP
\fBkprobe\fP et \fBuprobe\fP (depuis Linux 4.17)
.\" commit 65074d43fc77bcae32776724b7fa2696923c78e4
.\" commit e12f03d7031a977356e3d7b75a68c2185ff8d155
.\" commit 33ea4b24277b06dbc55d7f5772a46f029600255e
Ces deux PMU dynamiques créent un kprobe/uprobe et le rattachent à un
descripteur de fichier généré par perf_event_open. kprobe/uprobe sera
détruit lors de la destruction du descripteur de fichier. Voir les champs
\fIkprobe_func\fP, \fIuprobe_path\fP, \fIkprobe_addr\fP et \fIprobe_offset\fP pour plus
de détails.
.RE
.TP
\fIsize\fP
La taille de la structure \fIperf_event_attr\fP pour compatibilités ascendante
et descendante. Définissez\-la en utilisant \fIsizeof(struct perf_event_attr)\fP
pour permettre au noyau de voir la taille de struct au moment de la
compilation.
.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
Le \fBPERF_ATTR_SIZE_VER0\fP relatif est défini à 64\ ; c'était la taille de la
première struct publiée. \fBPERF_ATTR_SIZE_VER1\fP est 72, correspondant à
l'addition des points d'arrêts dans Linux\ 2.6.33. \fBPERF_ATTR_SIZE_VER2\fP est
80, correspondant à l'addition d'échantillonnage de branchement dans
Linux\ 3.4. \fBPERF_ATR_SIZE_VER3\fP est 96, correspondant à l'addition de
\fIsample_regs_user\fP et \fIsample_stack_user\fP dans
Linux\ 3.7. \fBPERF_ATTR_SIZE_VER4\fP vaut 104, correspondant à l'ajout de
\fIsample_regs_intr\fP dans Linux\ 3.19. \fBPERF_ATTR_SIZE_VER5\fP vaut 112,
correspondant à l'ajout de \fIaux_watermark\fP dans Linux\ 4.1.
.TP
\fIconfig\fP
Cela indique l'événement voulu, en conjonction avec le champ \fItype\fP. Les
champs \fIconfig1\fP et \fIconfig2\fP sont aussi pris en compte dans les cas où
64\ bits ne suffisent pas pour spécifier complètement l'événement. L'encodage
de ces champs dépend de l'événement.
.IP
Le champ \fIconfig\fP peut être défini de différentes façons, en fonction de la
valeur du champ \fItype\fP précédemment décrit. Suivent les divers réglages
possibles pour \fIconfig\fP, distingués par \fItype\fP.
.IP
Si \fItype\fP est \fBPERF_TYPE_HARDWARE\fP, un des événements processeur matériel
généralisé est mesuré. Ils ne sont pas tous disponibles sur toutes les
plateformes. Définissez \fIconfig\fP à une des valeurs suivantes\ :
.RS 12
.TP
\fBPERF_COUNT_HW_CPU_CYCLES\fP
Nombre total de cycles. Méfiez\-vous de ce qui arrive lors de la variation de
fréquence du processeur.
.TP
\fBPERF_COUNT_HW_INSTRUCTIONS\fP
Instructions retirées. Prenez garde, elles peuvent être affectées par
plusieurs problèmes, en particulier les décomptes d'interruptions
matérielles.
.TP
\fBPERF_COUNT_HW_CACHE_REFERENCES\fP
Accès au cache. En général, cela indique les accès au cache de dernier
niveau, mais cela peut dépendre du processeur. Cela pourrait inclure des
messages de prélecture et de cohérence\ ; cela dépend toujours de la
conception du processeur.
.TP
\fBPERF_COUNT_HW_CACHE_MISSES\fP
Absences dans le cache. Cela indique généralement les absences dans le cache
de dernier niveau, c'est destiné à être utilisé en conjonction avec
l'événement \fBPERF_COUNT_HW_CACHE_REFERENCES\fP pour calculer le taux
d’absence du cache.
.TP
\fBPERF_COUNT_HW_BRANCH_INSTRUCTIONS\fP
.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
Instructions de branchements retirés. Avant Linux\ 2.6.34, cela utilisait
l’événement incorrect sur les processeurs AMD.
.TP
\fBPERF_COUNT_HW_BRANCH_MISSES\fP
Instructions de branchements mal prédits.
.TP
\fBPERF_COUNT_HW_BUS_CYCLES\fP
Cycles de bus, ce qui peut être différent du décompte total de cycles.
.TP
\fBPERF_COUNT_HW_STALLED_CYCLES_FRONTEND\fP (depuis Linux 3.0)
.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
Cycles bloqués pendant un problème.
.TP
\fBPERF_COUNT_HW_STALLED_CYCLES_BACKEND\fP (depuis Linux 3.0)
.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a
Cycles bloqués pendant un retrait.
.TP
\fBPERF_COUNT_HW_REF_CPU_CYCLES\fP (depuis Linux 3.3)
.\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890
Nombre total de cycles ; non affecté par la variation de fréquence du
processeur.
.RE
.IP
Si \fItype\fP est \fBPERF_TYPE_SOFTWARE\fP, les événements logiciels fournis par
le noyau sont mesurés. Définissez \fIconfig\fP à une des valeurs suivantes\ :
.RS 12
.TP
\fBPERF_COUNT_SW_CPU_CLOCK\fP
Cela rend compte de l'horloge du processeur, un temporisateur par processeur
à haute résolution.
.TP
\fBPERF_COUNT_SW_TASK_CLOCK\fP
Cela rend compte de l'horloge spécifique à la tâche en cours d'exécution.
.TP
\fBPERF_COUNT_SW_PAGE_FAULTS\fP
Cela rend compte du nombre d'erreurs de pagination.
.TP
\fBPERF_COUNT_SW_CONTEXT_SWITCHES\fP
.\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21
Cela compte les changements de contexte. Jusqu'à Linux\ 2.6.34, ils étaient
tous signalés comme des événements en espace utilisateur, ils sont
maintenant signalés comme ayant lieu dans le noyau.
.TP
\fBPERF_COUNT_SW_CPU_MIGRATIONS\fP
Cela rend compte du nombre de fois où le processus a migré vers un nouveau
processeur.
.TP
\fBPERF_COUNT_SW_PAGE_FAULTS_MIN\fP
Cela compte le nombre d'erreurs mineures de pagination. Elles n'ont pas
nécessité d'entrées ou sorties du disque pour les traiter.
.TP
\fBPERF_COUNT_SW_PAGE_FAULTS_MAJ\fP
Cela compte le nombre d'erreurs majeures de pagination. Elles ont nécessité
des entrées ou sorties de disque pour les traiter.
.TP
\fBPERF_COUNT_SW_ALIGNMENT_FAULTS\fP (depuis Linux 2.6.33)
.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
Cela compte le nombre de défauts d'alignement. Ils ont lieu lors d'accès non
alignés en mémoire\ ; le noyau peut les traiter mais cela réduit les
performances. Cela n'arrive que sur certaines architectures (jamais sur
x86).
.TP
\fBPERF_COUNT_SW_EMULATION_FAULTS\fP (depuis Linux 2.6.33)
.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497
Cela compte le nombre de défauts d'émulation. Le noyau intercepte parfois
des instructions non implémentées et les émule pour l'espace
utilisateur. Cela peut avoir des conséquences négatives sur les
performances.
.TP
\fBPERF_COUNT_SW_DUMMY\fP (depuis Linux 3.12)
.\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77
C’est un événement fictif qui ne compte rien. Les types d’enregistrement
d’échantillonnage informatif comme mmap ou comm doivent être associés à un
événement actif. Cet événement factice permet de récupérer ce genre
d’enregistrements sans nécessiter d’événement de comptage.
.RE
.PP
.RS
Si \fItype\fP est \fBPERF_TYPE_TRACEPOINT\fP, alors les points de trace du noyau
sont mesurés. La valeur à utiliser dans \fIconfig\fP peut être obtenue depuis
\fItracing/events/*/*/id\fP de debugfs si ftrace est activé dans le noyau.
.RE
.PP
.RS
Si \fItype\fP est \fBPERF_TYPE_HW_CACHE\fP, alors un événement de cache du
processeur matériel est mesuré. Utilisez l'équation suivante pour calculer
la valeur \fIconfig\fP appropriée.
.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
où \fIperf_hw_cache_id\fP peut être\ :
.RS 4
.TP
\fBPERF_COUNT_HW_CACHE_L1D\fP
pour mesurer le cache de données de niveau\ 1\ ;
.TP
\fBPERF_COUNT_HW_CACHE_L1I\fP
pour mesurer le cache d'instructions de niveau\ 1\ ;
.TP
\fBPERF_COUNT_HW_CACHE_LL\fP
pour mesurer le cache de dernier niveau\ ;
.TP
\fBPERF_COUNT_HW_CACHE_DTLB\fP
pour mesurer les données TLB\ ;
.TP
\fBPERF_COUNT_HW_CACHE_ITLB\fP
pour mesurer les instructions TLB\ ;
.TP
\fBPERF_COUNT_HW_CACHE_BPU\fP
pour mesurer l'unité de prédiction de branchement\ ;
.TP
\fBPERF_COUNT_HW_CACHE_NODE\fP (depuis Linux\ 3.1)
.\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477
pour mesurer les accès à la mémoire locale.
.RE
.PP
et \fIperf_hw_cache_op_id\fP est parmi\ :
.RS 4
.TP
\fBPERF_COUNT_HW_CACHE_OP_READ\fP
pour les accès en lecture\ ;
.TP
\fBPERF_COUNT_HW_CACHE_OP_WRITE\fP
pour les accès en écriture\ ;
.TP
\fBPERF_COUNT_HW_CACHE_OP_PREFETCH\fP
pour les accès de prélecture\ ;
.RE
.PP
et \fIperf_hw_cache_op_result_id\fP peut être\ :
.RS 4
.TP
\fBPERF_COUNT_HW_CACHE_RESULT_ACCESS\fP
pour mesurer les accès\ ;
.TP
\fBPERF_COUNT_HW_CACHE_RESULT_MISS\fP
pour mesurer les échecs.
.RE
.RE
.PP
Si \fItype\fP est \fBPERF_TYPE_RAW\fP, alors une valeur \fIconfig\fP «\ brute\ »
personnalisée est nécessaire. La plupart des processeurs gèrent les
événements qui ne sont pas couverts par les événements
«\ généralisés\ ». Ceux\-ci sont définis par l'implémentation\ ; consultez le
manuel du processeur (par exemple la documentation Intel Volume\ 3B ou le
guide du développeur de BIOS et noyau AMD). La bibliothèque libpfm4 peut
être utilisée pour traduire le nom, dans les manuels architecturaux, en
valeur hexadécimale brute que \fBperf_event_open\fP() attend dans ce champ.
.PP
Si \fItype\fP est \fBPERF_TYPE_BREAKPOINT\fP, alors laissez \fIconfig\fP défini à
zéro. Ses paramètres sont définis ailleurs.
.PP
Si \fItype\fP est \fBkprobe\fP ou \fBuprobe\fP, définir \fIretprobe\fP (bit \fB0\fP de
\fIconfig\fP, voir \fI/sys/bus/event_source/devices/[k,u]probe/format/retprobe\fP)
pour kretprobe/uretprobe. Voir les champs \fIkprobe_func\fP, \fIuprobe_path\fP,
\fIkprobe_addr\fP et \fIprobe_offset\fP pour plus de détails.
.RE
.TP
\fIkprobe_func\fP, \fIuprobe_path\fP, \fIkprobe_addr\fP et \fIprobe_offset\fP
Ces champs décrivent les kprobe/uprobe pour les PMU dynamiques \fBkprobe\fP et
\fBuprobe\fP. Pour \fBkprobe\fP utilisez \fIkprobe_func\fP et \fIprobe_offset\fP ou
alors utilisez \fIkprobe_addr\fP et laissez le champ \fIkprobe_func\fP à
NULL. Pour \fBuprobe\fP, utilisez \fIuprobe_path\fP et \fIprobe_offset\fP.
.TP
\fIsample_period\fP, \fIsample_freq\fP
Un compteur d'«\ échantillonnage\ » génère une notification de dépassement
tous les N\ événements, où N est donné par \fIsample_period\fP. Un compteur
d'échantillonnage a \fIsample_period\fP\ >\ 0. Quand un dépassement arrive,
les données demandées sont enregistrées dans le tampon mmap. Le champ
\fIsample_type\fP contrôle les données qui sont enregistrées à chaque
dépassement.
.IP
\fIsample_freq\fP permet d'utiliser la fréquence au lieu de la période. Dans ce
cas, l'attribut \fIfreq\fP doit être défini. Le noyau ajustera la période
d'échantillonnage pour essayer d'atteindre le taux voulu. Le taux
d'ajustement est un tic d'horloge.
.TP
\fIsample_type\fP
Les divers bits de ce champ indiquent les valeurs à inclure dans
l'échantillon. Elles seront enregistrées dans un tampon circulaire,
disponible en espace utilisateur avec \fBmmap\fP(2). L'ordre de sauvegarde des
valeurs dans l'échantillon est documenté dans la sous\-section \fBDisposition
MMAP\fP ci\-dessous\ ; ce n'est pas l'ordre \fIenum perf_event_sample_format\fP.
.RS
.TP
\fBPERF_SAMPLE_IP\fP
Enregistrement de pointeur d'instruction.
.TP
\fBPERF_SAMPLE_TID\fP
Enregistrement des identifiants de processus et de thread.
.TP
\fBPERF_SAMPLE_TIME\fP
Enregistrement d'un horodatage.
.TP
\fBPERF_SAMPLE_ADDR\fP
Enregistrement d'une adresse, si applicable.
.TP
\fBPERF_SAMPLE_READ\fP
Enregistrement des valeurs de décompte de tous les événements d'un groupe,
pas seulement du leader de groupe.
.TP
\fBPERF_SAMPLE_CALLCHAIN\fP
Enregistrement de l'appel en chaîne (backtrace de pile).
.TP
\fBPERF_SAMPLE_ID\fP
Enregistrement d'un identifiant unique pour le leader de groupe d'événements
ouvert.
.TP
\fBPERF_SAMPLE_CPU\fP
Enregistrement de numéro de processeur.
.TP
\fBPERF_SAMPLE_PERIOD\fP
Enregistrement de la période d'échantillonnage actuelle.
.TP
\fBPERF_SAMPLE_STREAM_ID\fP
Enregistrement d'un identifiant unique pour l'événement
ouvert. Contrairement à \fBPERF_SAMPLE_ID\fP, le véritable identifiant est
renvoyé, pas celui du leader de groupe. Cet identifiant est le même que
celui renvoyé par \fBPERF_FORMAT_ID\fP.
.TP
\fBPERF_SAMPLE_RAW\fP
Enregistrement de données supplémentaires, si applicable. Normalement
renvoyées par les événements de point de trace.
.TP
\fBPERF_SAMPLE_BRANCH_STACK\fP (depuis Linux 3.4)
.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
Cela fournit un enregistrement des derniers branchements tels que fournis
par le matériel d’échantillonnage de branchement processeur (comme le LBR
–\ Last Branch Record\ – d’Intel). Les matériels ne prennent pas tous en
charge cette fonctionnalité.
.IP
Consultez le champ \fIbranch_sample_type\fP pour la façon de filtrer les
branchements signalés.
.TP
\fBPERF_SAMPLE_REGS_USER\fP (depuis Linux 3.7)
.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
Enregistrement de l’état actuel du registre processeur au niveau utilisateur
(les valeurs dans le processus avant d’appeler le noyau).
.TP
\fBPERF_SAMPLE_STACK_USER\fP (depuis Linux 3.7)
.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
Enregistrement de la pile au niveau utilisateur, permettant le défilement de
la pile.
.TP
\fBPERF_SAMPLE_WEIGHT\fP (depuis Linux 3.10)
.\" commit c3feedf2aaf9ac8bad6f19f5d21e4ee0b4b87e9c
Enregistrement d’une valeur de poids fournie par le matériel qui exprime le
coût de l’événement d’échantillonnage. Cela permet au matériel de mettre en
valeur les événements coûteux dans un profil.
.TP
\fBPERF_SAMPLE_DATA_SRC\fP (depuis Linux 3.10)
.\" commit d6be9ad6c960f43800a6f118932bc8a5a4eadcd1
Enregistrement des sources de données\ : d’où viennent, dans la hiérarchie de
mémoire, les données associées à l’instruction d’échantillonnage. Ce n’est
disponible que si le matériel sous\-jacent prend en charge cette
fonctionnalité.
.TP
\fBPERF_SAMPLE_IDENTIFIER\fP (depuis Linux 3.12)
.\" commit ff3d527cebc1fa3707c617bfe9e74f53fcfb0955
Placement de la valeur \fBSAMPLE_ID\fP à un endroit fixe de l’enregistrement,
soit au début (pour les événements d’échantillonnage), soit à la fin (si ce
n’est pas un événement d’échantillonnage).
.IP
C’était nécessaire parce qu’un flux d’échantillonnage pourrait avoir des
enregistrements provenant de différentes sources d’événements avec des
réglages de \fIsample_type\fP différents. L’analyse correcte du flux
d’événements n’était pas possible parce que le format de l’enregistrement
était nécessaire pour trouver \fBSAMPLE_ID\fP, mais le format ne pouvait pas
être trouvé sans savoir à quel événement l’échantillonnage appartenait
(provoquant une dépendance circulaire).
.IP
Ce nouveau réglage \fBPERF_SAMPLE_IDENTIFIER\fP rend le flux d’événements
toujours analysable en plaçant \fBSAMPLE_ID\fP à une position fixe, même si
cela a pour conséquence de dupliquer les valeurs \fBSAMPLE_ID\fP dans les
enregistrements.
.TP
\fBPERF_SAMPLE_TRANSACTION\fP (depuis Linux 3.13)
.\" commit fdfbbd07e91f8fe387140776f3fd94605f0c89e5
Enregistrement des raisons pour les événements d’abandon de mémoire
transactionnelle (venant par exemple de la prise en charge de mémoire
transactionnelle TSX Intel).
.IP
Le réglage \fIprecise_ip\fP doit être positif et un événement d’abandon de
mémoire transactionnelle doit être mesuré sinon aucune valeur ne sera
enregistrée. Remarquez également que certaines mesures perf_event, comme le
comptage de cycles d’échantillonnage, peuvent provoquer des abandons
supplémentaires (en provoquant une interruption lors d’une transaction).
.TP
\fBPERF_SAMPLE_REGS_INTR\fP (depuis Linux 3.19)
.\" commit 60e2364e60e86e81bc6377f49779779e6120977f
Enregistrer un sous\-ensemble de l'état actuel du registre du processeur
comme indiqué par \fIsample_regs_intr\fP. Contrairement à
\fBPERF_SAMPLE_REGS_USER\fP, les valeurs du registre renverront l'état du
registre du noyau si le dépassement s'est produit alors que le code du noyau
est en cours d'exécution. Si le processeur gère l'échantillonnage matériel
de l'état du registre (à savoir PEBS sur Intel x86) et si \fIprecise_ip\fP est
supérieur à zéro, les valeurs du registre renvoyées sont celles récupérées
par le matériel au moment du retrait de l'instruction échantillonnée.
.TP
\fBPERF_SAMPLE_PHYS_ADDR\fP (depuis Linux 4.13)
.\" commit fc7ce9c74c3ad232b084d80148654f926d01ece7
Enregistrer l'adresse physique des données comme avec \fBPERF_SAMPLE_ADDR\fP.
.TP
\fBPERF_SAMPLE_CGROUP\fP (depuis Linux 5.7)
.\" commit 96aaab686505c449e24d76e76507290dcc30e008
Enregistrer (perf_event) l'identifiant cgroup du processus. Cela correspond
au champ \fIid\fP de l'événement \fBPERF_RECORD_CGROUP\fP.
.RE
.TP
\fIread_format\fP
Ce champ indique le format des données renvoyées par \fBread\fP(2) sur un
descripteur de fichier \fBperf_event_open\fP().
.RS
.TP
\fBPERF_FORMAT_TOTAL_TIME_ENABLED\fP
Ajout du champ \fItime_enabled\fP de 64\ bits. Cela peut servir à calculer les
totaux estimés si la PMU est surutilisée et qu'il y a multiplexage.
.TP
\fBPERF_FORMAT_TOTAL_TIME_RUNNING\fP
Ajout du champ \fItime_running\fP de 64\ bits. Cela peut servir pour calculer
les totaux estimés si la PMU est surutilisée et qu'il y a multiplexage.
.TP
\fBPERF_FORMAT_ID\fP
Ajout d'une valeur unique de 64\ bits qui correspond au groupe d’événements.
.TP
\fBPERF_FORMAT_GROUP\fP
Permettre à toutes les valeurs de décompte d'un groupe d'événements d'être
lues en une seule lecture.
.RE
.TP
\fIdisabled\fP
Le bit \fIdisabled\fP indique si le compteur commence désactivé ou activé. Si
désactivé, l'événement peut être activé plus tard par \fBioctl\fP(2),
\fBprctl\fP(2) ou \fIenable_on_exec\fP.
.IP
Lors de la création d’un groupe d’événements, le leader de groupe est
généralement initialisé avec \fIdisabled\fP défini à \fB1\fP et tous les
événements enfants sont initialisés avec \fIdisabled\fP défini à \fB0\fP. Bien que
\fIdisabled\fP soit \fB0\fP, les événements enfants ne démarrent pas avant que le
leader de groupe ne soit activé.
.TP
\fIinherit\fP
Le bit \fIinherit\fP indique que le compteur devrait compter les événements des
tâches enfant comme les tâches indiquées. Cela ne s'applique qu'aux nouveaux
enfants, pas à ceux existants au moment où le compteur est créé (ni aux
nouveaux enfants des enfants existants).
.IP
L'héritage ne fonctionne pas pour certaines combinaisons de \fIread_format\fP,
comme \fBPERF_FORMAT_GROUP\fP.
.TP
\fIpinned\fP
Le bit \fIpinned\fP indique que le compteur devrait toujours être sur le
processeur si c'est possible. Cela ne s'applique qu'aux compteurs matériels
et seulement aux leaders de groupe. Si un compteur épinglé ne peut pas être
mis dans le processeur (par exemple s'il n'y a pas assez de compteurs
matériels ou en cas de confit avec n'importe quel autre événement), alors le
compteur arrive en état d'«\ erreur\ », où les lectures renvoient une fin de
fichier (c'est\-à\-dire que \fBread\fP(2) renvoie \fB0\fP) jusqu'à ce que le
compteur soit ensuite activé ou désactivé.
.TP
\fIexclusive\fP
Le bit \fIexclusive\fP indique que si ce groupe du compteur est sur le
processeur, il devrait être le seul groupe utilisant les compteurs du
processeur. Cela pourrait permettre à l'avenir de surveiller des programmes
pour gérer les fonctionnalités PMU qui doivent fonctionner seules, sans
perturber d'autres compteurs matériels.
.IP
Remarquez que de nombreuses situations non attendues pourraient empêcher de
démarrer les événements avec le bit \fIexclusive\fP défini. Cela concerne tous
les utilisateurs exécutant des mesures au niveau du système ainsi que toutes
les utilisations par le noyau des compteurs de performance (y compris
l’interface NMI Watchdog Timer habituellemen activée).
.TP
\fIexclude_user\fP
Si ce bit est défini, le décompte exclut les événements qui arrivent dans
l'espace utilisateur.
.TP
\fIexclude_kernel\fP
Si ce bit est défini, le décompte exclut les événements qui arrivent dans
l'espace du noyau.
.TP
\fIexclude_hv\fP
Si ce bit est défini, le décompte exclut les événements qui arrivent dans
l'hyperviseur. C'est surtout pour les PMU avec prise en charge intégrée de
leur traitement (comme POWER). Une prise en charge supplémentaire est
nécessaire pour traiter les mesures d'hyperviseur sur la plupart des
machines.
.TP
\fIexclude_idle\fP
S'il est défini, ne pas décompter quand le processeur exécute la tâche
inactive. Si vous pouvez actuellement activer cela pour n'importe quel type
d'événement, il est ignoré pour tous, sauf ceux de type logiciel.
.TP
\fImmap\fP
Le bit \fImmap\fP active la génération des échantillons \fBPERF_RECORD_MMAP\fP
pour tous les appels \fBmmap\fP(2) qui ont \fBPROT_EXEC\fP défini. Cela permet aux
outils de remarquer le nouveau code exécutable en train d’être associé dans
un programme (les bibliothèques partagées dynamiques par exemple) de telle
sorte que les adresses peuvent être réassociées au code d’origine.
.TP
\fIcomm\fP
.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
Le bit \fIcomm\fP active le suivi du nom de commande de processus tel que
modifié par les appels systèmes \fBexec\fP(2) et \fBprctl\fP(PR_SET_NAME) ainsi
que l'écriture dans \fI/proc/self/comm\fP. Si l'attribut \fIcomm_exec\fP est
positionné avec succès (ce qui est possible depuis Linux\ 3.16), l'attribut
général \fBPERF_RECORD_MISC_COMM_EXEC\fP peut être utilisé pour différencier le
cas \fBexec\fP(2) des autres.
.TP
\fIfreq\fP
Si ce bit est activé, alors \fIsample_frequency\fP est utilisé au lieu de
\fIsample_period\fP lors du réglage de l'intervalle d'échantillonnage.
.TP
\fIinherit_stat\fP
Ce bit active la sauvegarde des décomptes d'événements lors du changement de
contexte pour les tâches héritées. Cela n'a de sens que si le champ
\fIinherit\fP est défini.
.TP
\fIenable_on_exec\fP
Si ce bit est défini, un compteur est automatiquement activé après un appel
d'\fBexec\fP(2).
.TP
\fItask\fP
Si ce bit est défini, alors les notifications de création d’enfant et de fin
sont inclues au tampon circulaire.
.TP
\fIwatermark\fP
Si défini, une notification de débordement arrive lors du passage de la
frontière \fIwakeup_watermark\fP. Sinon, les notifications arrivent après les
échantillons \fIwakeup_events\fP.
.TP
\fIprecise_ip\fP (depuis Linux 2.6.35)
.\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076
Cela contrôle la quantité de dérapage. Le dérapage est le nombre
d'instructions qui s'exécutent entre l'arrivée d'un événement d'intérêt et
la possibilité du noyau de s'arrêter pour enregistrer l'événement. Les plus
petits dérapages sont meilleurs et permettent d'associer plus précisément
les événements correspondant aux instructions, mais le matériel est souvent
limité par leur taille.
.IP
Les valeurs possibles du champ sont les suivantes\ :
.RS
.IP 0 3
\fBSAMPLE_IP\fP peut avoir un dérapage arbitraire\ ;
.IP 1
\fBSAMPLE_IP\fP doit avoir un dérapage constant\ ;
.IP 2
\fBSAMPLE_IP\fP a demandé un dérapage nul\ ;
.IP 3
\fBSAMPLE_IP\fP doit avoir un dérapage nul. Consultez aussi la description de
\fBPERF_RECORD_MISC_EXACT_IP\fP.
.RE
.TP
\fImmap_data\fP (depuis Linux 2.6.36)
.\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e
L’opposé du champ \fImmap\fP. Cela active la génération des échantillons
\fBPERF_RECORD_MMAP\fP pour les appels \fBmmap\fP(2) qui n’ont pas \fBPROT_EXEC\fP
défini (par exemple les données et la mémoire partagée SysV).
.TP
\fIsample_id_all\fP (depuis Linux 2.6.38)
.\" commit c980d1091810df13f21aabbce545fd98f545bbf7
Si défini, alors TID, TIME, ID, STREAM_ID et CPU peuvent de plus être inclus
dans les non \fBPERF_RECORD_SAMPLE\fP si le \fIsample_type\fP correspondant est
sélectionné.
.IP
Si \fBPERF_SAMPLE_IDENTIFIER\fP est indiqué, alors une valeur d’identifiant
supplémentaire est incluse en dernière valeur pour faciliter l’analyse du
flux d’enregistrement. Cela peut avoir pour conséquence de voir apparaître
la valeur \fIid\fP deux fois.
.IP
La disposition est décrite par cette pseudostructure\ :
.IP
.in +4n
.EX
struct sample_id {
{ u32 pid, tid; } /* si PERF_SAMPLE_TID est défini */
{ u64 time; } /* si PERF_SAMPLE_TIME est défini */
{ u64 id; } /* si PERF_SAMPLE_ID est défini */
{ u64 stream_id;} /* si PERF_SAMPLE_STREAM_ID est défini */
{ u32 cpu, res; } /* si PERF_SAMPLE_CPU est défini */
{ u64 id; } /* si PERF_SAMPLE_IDENTIFIER est défini */
};
.EE
.in
.TP
\fIexclude_host\fP (depuis Linux 3.2)
.\" commit a240f76165e6255384d4bdb8139895fac7988799
Quand on prend des mesures comprenant les processus exécutant des instances
de VM (à savoir si on exécute \fBioctl\fP(2) \fBKVM_RUN\fP), ne mesurer que les
événements dans l'instance de l'invité. Cela n'a de sens qu'à l'extérieur de
l'invité\ ; ce paramètre ne modifie pas les compteurs à l'intérieur d'un
invité. Actuellement, cette fonctionnalité n'existe que sur x86.
.TP
\fIexclude_guest\fP (depuis Linux 3.2)
.\" commit a240f76165e6255384d4bdb8139895fac7988799
Quand on prend des mesures comprenant les processus exécutant des instances
de VM (à savoir si on exécute \fBioctl\fP(2) \fBKVM_RUN\fP), ne pas mesurer les
événements dans l'instance de l'invité. Cela n'a de sens qu'à l'extérieur de
l'invité\ ; ce paramètre ne modifie pas les compteurs à l'intérieur d'un
invité. Actuellement, cette fonctionnalité n'existe que sur x86.
.TP
\fIexclude_callchain_kernel\fP (depuis Linux 3.7)
.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
Ne pas inclure les appels en chaîne du noyau.
.TP
\fIexclude_callchain_user\fP (depuis Linux 3.7)
.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91
Ne pas inclure les appels en chaîne d'utilisateur.
.TP
\fImmap2\fP (depuis 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
Générer un enregistrement mmap exécutable étendu contenant assez
d'informations supplémentaires pour n'identifier que les projections
partagées. L'attribut \fImmap\fP doit aussi être défini pour que cela
fonctionne.
.TP
\fIcomm_exec\fP (depuis Linux 3.16)
.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
Il s'agit d'un attribut de pure détection de fonctionnalité, il ne modifie
pas le comportement du noyau. Si cet attribut peut être positionné avec
succès, quand \fIcomm\fP est activé, l'attribut \fBPERF_RECORD_MISC_COMM_EXEC\fP
sera positionné dans le champ \fImisc\fP de l'entête de l'enregistrement comm
si l'événement de renommage signalé a été causé par un appel à
\fBexec\fP(2). Cela permet aux outils de distinguer les types de renommage du
processus.
.TP
\fIuse_clockid\fP (depuis Linux 4.1)
.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
Cela permet de sélectionner l'horloge interne du noyau Linux à utiliser lors
de la génération des horodatages à l'aide du champ \fIclockid\fP. Cela peut
faciliter la corrélation des durées d'échantillonnage des perf avec les
horodatages générés par d'autres outils.
.TP
\fIcontext_switch\fP (depuis Linux 4.3)
.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
Cela active la génération d'enregistrements \fBPERF_RECORD_SWITCH\fP lors d'un
changement de contexte. Cela active aussi la génération d'enregistrements
\fBPERF_RECORD_SWITCH_CPU_WIDE\fP lors d'un échantillonnage en mode processeur
complet. Cette fonctionnalité s'ajoute aux points de trace existants et aux
événements logiciels de mesure des changements de contexte. L'avantage de
cette méthode est qu'elle fournira toutes les informations même avec des
réglages \fIperf_event_paranoid\fP stricts.
.TP
\fIwrite_backward\fP (depuis Linux 4.6)
.\" commit 9ecda41acb971ebd07c8fb35faf24005c0baea12
Cela fait écrire le tampon circulaire de la fin vers le début. Cela permet
de gérer la lecture à partir d’un tampon circulaire réinscriptible.
.TP
\fInamespaces\fP (depuis Linux 4.11)
.\" commit e422267322cd319e2695a535e47c5b1feeac45eb
Cela active la génération d'enregistrements \fBPERF_RECORD_NAMESPACES\fP
lorsqu'une tâche entre dans un nouvel espace de noms. Chaque espace de noms
a une combinaison de numéros de périphérique et d'inœud.
.TP
\fIksymbol\fP (depuis Linux 5.0)
.\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
Cela active la génération d'enregistrements \fBPERF_RECORD_KSYMBOL\fP quand de
nouveaux symboles du noyau sont enregistrés ou désenregistrés. Cela concerne
les fonctions dynamiques d’analyse du noyau comme eBPF.
.TP
\fIbpf_event\fP (depuis Linux 5.0)
.\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
Cela active la génération d'enregistrements \fBPERF_RECORD_BPF_EVENT\fP
lorsqu'un programme eBPF est chargé ou déchargé.
.TP
\fIauxevent\fP (depuis Linux 5.4)
.\" commit ab43762ef010967e4ccd53627f70a2eecbeafefb
Cela permet aux événements normaux (non\-AUX) de générer des données pour des
événements AUX si le matériel le prend en charge.
.TP
\fIcgroup\fP (depuis Linux 5.7)
.\" commit 96aaab686505c449e24d76e76507290dcc30e008
Cela active la génération d'enregistrements \fBPERF_RECORD_CGROUP\fP quand un
nouveau cgroup est créé (et activé).
.TP
\fItext_poke\fP (depuis Linux 5.8)
.\" commit e17d43b93e544f5016c0251d2074c15568d5d963
Cela active la génération d'enregistrements \fBPERF_RECORD_TEXT_POKE\fP quand
un changement se produit dans le texte du noyau (c'est\-à\-dire quand du code
se modifie lui\-même).
.TP
\fIwakeup_events\fP, \fIwakeup_watermark\fP
Cette union indique le nombre d'échantillons (\fIwakeup_events\fP) ou d'octets
(\fIwakeup_watermark\fP) qui arrivent avant un signal de dépassement. Celui
utilisé est sélectionné par l'attribut \fIwatermark\fP.
.IP
\fIwakeup_events\fP ne compte que les types d’enregistrement
\fBPERF_RECORD_SAMPLE\fP. Pour recevoir un signal pour tous les types
\fBPERF_RECORD\fP arrivant, choisissez watermark et définissez
\fIwakeup_watermark\fP à \fB1\fP.
.IP
.\" commit f506b3dc0ec454a16d40cab9ee5d75435b39dc50
Avant Linux\ 3.0, positionner \fIwakeup_events\fP à \fB0\fP ne signalait aucun
dépassement\ ; les noyaux plus récents traitent \fB0\fP comme \fB1\fP.
.TP
\fIbp_type\fP (depuis Linux 2.6.33)
.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
Cela choisit le type de point d'arrêt. Il s'agit d'un des suivants\ :
.RS
.TP
\fBHW_BREAKPOINT_EMPTY\fP
pas de point d'arrêt\ ;
.TP
\fBHW_BREAKPOINT_R\fP
compte lors de la lecture de l'emplacement mémoire\ ;
.TP
\fBHW_BREAKPOINT_W\fP
compte lors de l'écriture à l'emplacement mémoire\ ;
.TP
\fBHW_BREAKPOINT_RW\fP
compte lors de la lecture ou l'écriture à l'emplacement mémoire\ ;
.TP
\fBHW_BREAKPOINT_X\fP
compte lors de l'exécution de code à l'emplacement mémoire.
.PP
Les valeurs peuvent être combinées à l'aide d'un OU binaire, mais les
combinaisons de \fBHW_BREAKPOINT_R\fP ou \fBHW_BREAKPOINT_W\fP avec
\fBHW_BREAKPOINT_X\fP ne sont pas permises.
.RE
.TP
\fIbp_addr\fP (depuis Linux 2.6.33)
.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
Il s'agit de l'adresse du point d'arrêt. Pour les points d'arrêt
d'exécution, c'est l'adresse mémoire de l'instruction d'intérêt\ ; pour les
points d'arrêt de lecture et écriture, c'est l'adresse mémoire de
l'emplacement mémoire d'intérêt.
.TP
\fIconfig1\fP (depuis Linux 2.6.39)
.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
\fIconfig1\fP est utilisé pour définir des événements qui ont besoin d'un
registre supplémentaire ou qui sinon ne rentrent pas dans le champ \fIconfig\fP
normal. OFFCORE_EVENTS brut sur Nehalem/Westmere/SandyBridge utilise ce
champ sur Linux\ 3.3 et les noyaux suivants.
.TP
\fIbp_len\fP (depuis Linux 2.6.33)
.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e
\fIbp_len\fP est la taille du point d'arrêt mesuré si \fItype\fP est
\fBPERF_TYPE_BREAKPOINT\fP. Les options sont \fBHW_BREAKPOINT_LEN_1\fP,
\fBHW_BREAKPOINT_LEN_2\fP, \fBHW_BREAKPOINT_LEN_4\fP et
\fBHW_BREAKPOINT_LEN_8\fP. Pour un point d'arrêt, définissez\-la à
\fIsizeof(long)\fP.
.TP
\fIconfig2\fP (depuis Linux 2.6.39)
.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6
\fIconfig2\fP est une extension supplémentaire du champ \fIconfig1\fP.
.TP
\fIbranch_sample_type\fP (depuis Linux 3.4)
.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e
Si \fBPERF_SAMPLE_BRANCH_STACK\fP est activé, alors cela indique les
branchements à inclure dans l’enregistrement de branchements.
.IP
La première partie de la valeur est le niveau de droits qui est une
combinaison d’une des valeurs suivantes. Si l’utilisateur ne définit pas
explicitement le niveau de droits, le noyau utilisera celui de
l’événement. Les niveaux de droits de l’événement et du branchement ne
doivent pas nécessairement correspondre.
.RS
.TP
\fBPERF_SAMPLE_BRANCH_USER\fP
La cible de branchement est dans l'espace utilisateur.
.TP
\fBPERF_SAMPLE_BRANCH_KERNEL\fP
La cible de branchement est dans l'espace du noyau.
.TP
\fBPERF_SAMPLE_BRANCH_HV\fP
La cible de branchement est dans l'hyperviseur.
.TP
\fBPERF_SAMPLE_BRANCH_PLM_ALL\fP
Une valeur pratique qui correspond aux trois valeurs précédentes combinées
avec un OU.
.PP
En plus de la valeur de droits, au moins un des bits suivants doit être
défini.
.TP
\fBPERF_SAMPLE_BRANCH_ANY\fP
N'importe quel type de branchement.
.TP
\fBPERF_SAMPLE_BRANCH_ANY_CALL\fP
N'importe quelle branche d'appel (y compris les appels directs, indirects et
les grands sauts).
.TP
\fBPERF_SAMPLE_BRANCH_IND_CALL\fP
Appels indirects.
.TP
\fBPERF_SAMPLE_BRANCH_CALL\fP (depuis Linux 4.4)
.\" commit c229bf9dc179d2023e185c0f705bdf68484c1e73
Appels directs.
.TP
\fBPERF_SAMPLE_BRANCH_ANY_RETURN\fP
N'importe quel branchement de retour.
.TP
\fBPERF_SAMPLE_BRANCH_IND_JUMP\fP (depuis Linux 4.2)
.\" commit c9fdfa14c3792c0160849c484e83aa57afd80ccc
Sauts indirects.
.TP
\fBPERF_SAMPLE_BRANCH_COND\fP (depuis Linux 3.16)
.\" commit bac52139f0b7ab31330e98fd87fc5a2664951050
Branches conditionnelles.
.TP
\fBPERF_SAMPLE_BRANCH_ABORT_TX\fP (depuis Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
Abandons de mémoire transactionnelle.
.TP
\fBPERF_SAMPLE_BRANCH_IN_TX\fP (depuis Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
Branchement dans une transaction de mémoire transactionnelle.
.TP
\fBPERF_SAMPLE_BRANCH_NO_TX\fP (depuis Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
.\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70
Branchement non dans la transaction de la mémoire
transactionnelle. \fBPERF_SAMPLE_BRANCH_CALL_STACK\fP (depuis Linux\ 4.1). Le
branchement faitpartie d'une pile d'appel générée par le matériel. Cela
implique la prise en charge par le matériel, qui n'existe actuellementque
sur le x86 Haswell d'Intel ou plus récent.
.RE
.TP
\fIsample_regs_user\fP (depuis Linux 3.7)
.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56
Ce masque binaire définit l’ensemble des registres processeur utilisateur à
renvoyer dans les échantillons. La disposition du masque de registre est
spécifique à l’architecture et définie dans l’en\-tête du noyau
\fIarch/ARCH/include/uapi/asm/perf_regs.h\fP.
.TP
\fIsample_stack_user\fP (depuis Linux 3.7)
.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7
Cela définit la taille de la pile utilisateur à renvoyer si
\fBPERF_SAMPLE_STACK_USER\fP est indiqué.
.TP
\fIclockid\fP (depuis Linux 4.1)
.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b
Si \fIuse_clockid\fP est positionné, ce champ sélectionne l'horloge interne de
Linux à utiliser pour les horodatages. Les horloges disponibles sont
définies dans \fIlinux/time.h\fP, où sont actuellement prises en charge
\fBCLOCK_MONOTONIC\fP, \fBCLOCK_MONOTONIC_RAW\fP, \fBCLOCK_REALTIME\fP,
\fBCLOCK_BOOTTIME\fP et \fBCLOCK_TAI\fP.
.TP
\fIaux_watermark\fP (depuis Linux\ 4.1)
.\" commit 1a5941312414c71dece6717da9a0fa1303127afa
Cela indique la quantité de données nécessaires pour récupérer un
échantillonnage \fBPERF_RECORD_AUX\fP.
.TP
\fIsample_max_stack\fP (depuis Linux\ 4.8)
.\" commit 97c79a38cd454602645f0470ffb444b3b75ce574
Quand \fIsample_type\fP comprend \fBPERF_SAMPLE_CALLCHAIN\fP, ce champ indique le
nombre de trames de pile à rendre compte lors de la génération de la chaîne
d'appels.
.SS "Lecture des résultats"
Une fois qu'un descripteur de fichier \fBperf_event_open\fP() a été ouvert, les
valeurs des événements peuvent être lues depuis le descripteur de
fichier. Les valeurs présentes sont indiquées par le champ \fIread_format\fP de
la structure \fIattr\fP au moment de l'ouverture.
.PP
Si vous essayez de lire un tampon utilisé pour la lecture qui n'est pas
assez grand pour contenir les données, \fBENOSPC\fP est renvoyé.
.PP
Voici la disposition des données renvoyées par une lecture\ :
.IP * 2
Si \fBPERF_FORMAT_GROUP\fP a été indiqué pour permettre de lire tous les
événements d'un groupe en une fois\ :
.IP
.in +4n
.EX
struct read_format {
u64 nr; /* Le nombre d'événements */
u64 time_enabled; /* si PERF_FORMAT_TOTAL_TIME_ENABLED */
u64 time_running; /* si PERF_FORMAT_TOTAL_TIME_RUNNING */
struct
u64 value; /* La valeur de l'événement */
u64 id; /* si PERF_FORMAT_ID */
} values[nr];
};
.EE
.in
.IP *
Si \fBPERF_FORMAT_GROUP\fP n'a \fIpas\fP été indiqué\ :
.IP
.in +4n
.EX
struct read_format {
u64 value; /* La valeur de l'événement */
u64 time_enabled; /* si PERF_FORMAT_TOTAL_TIME_ENABLED */
u64 time_running; /* si PERF_FORMAT_TOTAL_TIME_RUNNING */
u64 id; /* si PERF_FORMAT_ID */
};
.EE
.in
.PP
Les valeurs lues sont les suivantes.
.TP
\fInr\fP
Le nombre d'événements dans le descripteur de fichier. Seulement disponible
si \fBPERF_FORMAT_GROUP\fP a été indiqué.
.TP
\fItime_enabled\fP, \fItime_running\fP
Temps total pendant lequel l'événement a été activé et exécuté. Normalement
ce sont les mêmes. Si plus d'événements sont démarrés que d'emplacements de
compteur disponibles sur la PMU, alors il y a multiplexage et les événements
ne sont pas exécutés tout le temps. Dans ce cas, les valeurs \fItime_enabled\fP
et \fItime running\fP peuvent être utilisées pour estimer une valeur d'ordre de
grandeur du décompte.
.TP
\fIvalue\fP
Une valeur positive sur 64\ bits contenant le résultat du compteur.
.TP
\fIid\fP
Une valeur unique globale pour cet événement en particulier, seulement si
\fBPERF_FORMAT_ID\fP a été indiqué dans \fIread_format\fP.
.SS "Disposition MMAP"
En utilisant \fBperf_event_open\fP() en mode d'échantillonnage, les événements
asynchrones (comme un dépassement de compteur ou un suivi mmap \fBPROT_EXEC\fP)
sont journalisés dans un tampon circulaire. Ce tampon circulaire est créé et
accédé à l'aide de \fBmmap\fP(2).
.PP
La taille de mmap devrait être 1+2^n\ pages, où la première page est une page
de métadonnées (\fIstruct perf_event_mmap_page\fP) qui contient plusieurs
informations comme l'emplacement de la tête du tampon circulaire.
.PP
Avant le noyau\ 2.6.39, un bogue oblige à allouer un tampon circulaire mmap
lors de l'échantillonnage même s'il n'est pas prévu de l'utiliser.
.PP
La structure de la première page mmap de métadonnées est la suivante\ :
.PP
.in +4n
.EX
struct perf_event_mmap_page {
__u32 version; /* numéro de version de la structure */
__u32 compat_version; /* plus petite version compatible */
__u32 lock; /* seqlock pour synchronisation */
__u32 index; /* identifiant de compteur matériel */
__s64 offset; /* ajouter au compteur matériel */
__u64 time_enabled; /* temps d'événement actif */
__u64 time_running; /* temps d'événement sur processeur */
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]; /* remplissage à 1 k */
__u64 data_head; /* tête de la section de données */
__u64 data_tail; /* queue écrite en espace utilisateur */
__u64 data_offset; /* où commence le tampon */
__u64 data_size; /* taille du tampon de données */
__u64 aux_head;
__u64 aux_tail;
__u64 aux_offset;
__u64 aux_size;
}
}
.EE
.in
.PP
La liste suivante décrit les champs de la structure \fIperf_event_mmap_page\fP
plus précisément.
.TP
\fIversion\fP
Numéro de version de cette structure.
.TP
\fIcompat_version\fP
La plus petite version avec laquelle elle est compatible.
.TP
\fIlock\fP
Un seqlock (sequence lock) pour la synchronisation.
.TP
\fIindex\fP
Un identifiant unique de compteur matériel.
.TP
\fIoffset\fP
Quand l’instruction rdpmc est utilisée pour lire, cette valeur de position
doit être ajoutée à celle renvoyée par rdpmc pour obtenir le décompte total
actuel d’événements.
.TP
\fItime_enabled\fP
Temps d'activité de l'événement.
.TP
\fItime_running\fP
Temps d'exécution de l'événement.
.TP
\fIcap_usr_time\fP / \fIcap_usr_rdpmc\fP / \fIcap_bit0\fP (depuis Linux 3.4)
.\" commit c7206205d00ab375839bd6c7ddb247d600693c09
Un bogue existait dans la définition de \fIcap_usr_time\fP et \fIcap_usr_rdpmc\fP
de Linux\ 3.4 à Linux\ 3.11. Les deux bits étaient définis pour pointer vers
le même endroit, il était donc impossible de savoir si \fIcap_usr_time\fP ou
\fIcap_usr_rdpmc\fP étaient vraiment définis.
.IP
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Depuis Linux\ 3.12, ils ont été renommés en \fIcap_bit0\fP et vous devriez
plutôt utiliser les nouveaux champs \fIcap_user_time\fP et \fIcap_user_rdpmc\fP à
la place.
.TP
\fIcap_bit0_is_deprecated\fP (depuis Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Si défini, ce bit indique que le noyau est capable de gérer les bits
\fIcap_user_time\fP et \fIcap_user_rdpmc\fP différenciés correctement.
.IP
Si non, cela indique qu’il s’agit d’un ancien noyau où \fIcap_usr_time\fP et
\fIcap_usr_rdpmc\fP pointent vers le même bit et donc que ces deux
fonctionnalités devraient être utilisées avec prudence.
.TP
\fIcap_usr_rdpmc\fP (depuis Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Si le matériel permet la lecture en espace utilisateur des compteurs de
performance sans appel système (c'est l'instruction «\ rdpmc\ » sur x86),
alors le code suivant peut être utilisé pour faire une lecture\ :
.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 (depuis Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Ce bit indique que le matériel a un compteur temporel sans arrêt, constant
(TSC sur x86).
.TP
\fIcap_usr_time_zero\fP (depuis Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
Indique la présence de \fItime_zero\fP qui permet d’associer les valeurs
d’horodatage à l’horloge matérielle.
.TP
\fIpmc_width\fP
Si \fIcap_usr_rdpmc\fP, ce champ fournit la taille en bit de la valeur lue en
utilisant l'instruction rdpmc ou équivalente. Cela permet d'étendre avec
signe le résultat comme ceci\ :
.IP
.in +4n
.EX
pmc <<= 64 \- pmc_width;
pmc >>= 64 \- pmc_width; // déplacement du signe à droite
count += pmc;
.EE
.in
.TP
\fItime_shift\fP, \fItime_mult\fP, \fItime_offset\fP
.IP
Si \fIcap_usr_time\fP, ces champs peuvent être utilisés pour calculer la
différence de temps depuis \fItime_enabled\fP (en nanoseconde) en utilisant
rdtsc ou similaire.
.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
Où \fItime_offset\fP, \fItime_mult\fP, \fItime_shift\fP et \fIcyc\fP sont lus dans la
boucle seqcount décrite ci\-dessus. Cette différence peut être ajoutée à
\fIenabled\fP et éventuellement \fIrunning\fP (si idx), pour améliorer l'échelle\ :
.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 (depuis Linux 3.12)
.\" commit fa7315871046b9a4c48627905691dbde57e51033
.IP
Si \fIcap_usr_time_zero\fP est défini, alors l'horloge matérielle (le compteur
temporel TSC sur x86) peut être calculée à partir des valeurs \fItime_zero\fP,
\fItime_mult\fP et \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
et vice versa\ :
.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
Cela pointe vers la tête de la section de données. La valeur augmente
continuellement, elle n'est pas coupée. Vous devrez couper vous\-même la
valeur à la taille du tampon mmap avant d'accéder aux échantillons.
.IP
Sur les plateformes compatibles SMP, après la lecture de la valeur
\fIdata_head\fP, l'espace utilisateur devrait renvoyer un rmb().
.TP
\fIdata_tail\fP
Quand l'association est \fBPROT_WRITE\fP, la valeur \fIdata_tail\fP devrait être
écrite par l'espace utilisateur pour refléter les dernières données
lues. Dans ce cas, le noyau n'écrasera pas les données non lues.
.TP
\fIdata_offset\fP (depuis Linux 4.1)
.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
Contient la position de l'emplacement du tampon mmap où les données de
l'échantillon de perf commencent.
.TP
\fIdata_size\fP (depuis Linux 4.1)
.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f
Contient la taille de la zone de l'échantillon de perf dans le tampon mmap.
.TP
\fIaux_head\fP, \fIaux_tail\fP, \fIaux_offset\fP, \fIaux_size\fP (depuis Linux 4.1)
.\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff
La zone AUX permet d'appliquer à un \fBmmap\fP(2) un tampon d'échantillonnage
distinct pour les flux de données à forte bande passante (séparément du
tampon d'échantillonnage de perf principal). Un exemple de flux à forte
bande passante est la prise en charge du traçage d'une instruction telle
qu'elle se fait dans les nouveaux processeurs Intel.
.IP
Pour définir une zone AUX, il faut d'abord positionner \fIaux_offset\fP à une
position supérieure à \fIdata_offset\fP+\fIdata_size\fP puis positionner
\fIaux_size\fP à la taille de tampon désirée. La position et la taille désirée
doivent être alignées sur la page et la taille doit être une puissance de
deux. Ces valeurs sont alors passées à mmap pour projeter le tampon AUX. Les
pages du tampon AUX sont comprises dans la limite de ressource
\fBRLIMIT_MEMLOCK\fP (voir \fBsetrlimit\fP(2)) et dans la gestion des droits
\fIperf_event_mlock_kb\fP.
.IP
Par défaut, le tampon AUX sera tronqué s'il ne rentre pas dans l'espace
disponible du tampon circulaire. Si le tampon AUX est projeté en tant que
tampon en lecture seule, il agira dans le mode du tampon circulaire là où
les données seront remplacées par de nouvelles. En mode remplacement, il se
pourrait qu'il ne soit pas possible de présumer l'endroit où commencent les
données et il appartient au consommateur de désactiver la mesure pendant la
lecture pour éviter les possibles collisions de données.
.IP
Les pointeurs de tampon circulaire \fIaux_head\fP et \fIaux_tail\fP ont le même
comportement et les mêmes règles d'organisation que celles décrites
précédemment pour \fIdata_head\fP et \fIdata_tail\fP.
.PP
Les 2^n\ pages suivantes du tampon circulaire ont la disposition décrite
ci\-dessous.
.PP
Si \fIperf_event_attr.sample_id_all\fP est défini, alors tous les types
d'événements auront les champs \fIsample_type\fP sélectionnés relatifs à
l'emplacement et à la date (identité) où un événement a eu lieu (TID, TIME,
ID, CPU, STREAM_ID) conformément à la description de \fBPERF_RECORD_SAMPLE\fP
ci\-dessous, il sera stocké juste après le \fIperf_event_header\fP et les champs
déjà présents pour les champs existants, c'est\-à\-dire à la fin de la charge
utile. De cette façon, un nouveau perf.data sera pris en charge par les
outils de performances plus anciens, avec ces nouveaux champs facultatifs
ignorés.
.PP
Les valeurs mmap commencent par un en\-tête\ :
.PP
.in +4n
.EX
struct perf_event_header {
__u32 type;
__u16 misc;
__u16 size;
};
.EE
.in
.PP
Les champs \fIperf_event_header\fP sont décrits plus précisément
ci\-dessous. Par commodité de lecture, les champs avec les descriptions les
plus courtes sont d’abord présentés.
.TP
\fIsize\fP
Cela indique la taille de l'enregistrement.
.TP
\fImisc\fP
Le champ \fImisc\fP contient des renseignements supplémentaires sur
l'échantillon.
.IP
Le mode de processeur peut être déterminé à partir de cette valeur en la
masquant avec \fBPERF_RECORD_MISC_CPUMODE_MASK\fP et en recherchant un des
suivants (remarquez que ce ne sont pas des masques de bits, un seul peut
être défini à la fois).
.RS
.TP
\fBPERF_RECORD_MISC_CPUMODE_UNKNOWN\fP
Mode de processeur inconnu.
.TP
\fBPERF_RECORD_MISC_KERNEL\fP
L'échantillon a eu lieu dans le noyau.
.TP
\fBPERF_RECORD_MISC_USER\fP
L'échantillon a eu lieu dans le code utilisateur.
.TP
\fBPERF_RECORD_MISC_HYPERVISOR\fP
L'échantillon a eu lieu dans l'hyperviseur.
.TP
\fBPERF_RECORD_MISC_GUEST_KERNEL\fP (depuis Linux 2.6.35)
.\" commit 39447b386c846bbf1c56f6403c5282837486200f
L'échantillon a eu lieu dans le noyau client.
.TP
\fBPERF_RECORD_MISC_GUEST_USER\fP (depuis Linux 2.6.35)
.\" commit 39447b386c846bbf1c56f6403c5282837486200f
L'échantillon a eu lieu dans le code utilisateur client.
.RE
.PP
.RS
Comme les trois états suivants sont générés par différents types
d'enregistrement, ils constituent des alias du même bit\ :
.TP
\fBPERF_RECORD_MISC_MMAP_DATA\fP (depuis Linux 3.10)
.\" commit 2fe85427e3bf65d791700d065132772fc26e4d75
C’est défini quand l’association n’est pas exécutable\ ; sinon l’association
est exécutable.
.TP
\fBPERF_RECORD_MISC_COMM_EXEC\fP (depuis Linux 3.16)
.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871
Il est positionné pour un enregistrement \fBPERF_RECORD_COMM\fP sur les noyaux
plus récents que Linux 3.16 si le changement de nom d'un processus est causé
par un appel système \fBexec\fP(2).
.TP
\fBPERF_RECORD_MISC_SWITCH_OUT\fP (depuis Linux 4.3)
.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
Quand un enregistrement \fBPERF_RECORD_SWITCH\fP ou
\fBPERF_RECORD_SWITCH_CPU_WIDE\fP est généré, ce bit indique que le changement
de contexte est distinct du processus actuel (et n'en fait pas partie).
.RE
.PP
.RS
De plus, les bits suivants peuvent être définis\ :
.TP
\fBPERF_RECORD_MISC_EXACT_IP\fP
Cela indique que le contenu de \fBPERF_SAMPLE_IP\fP pointe vers la véritable
instruction qui a déclenché l'événement. Consultez aussi
\fIperf_event_attr.precise_ip\fP.
.TP
\fBPERF_RECORD_MISC_EXT_RESERVED\fP (depuis Linux 2.6.35)
.\" commit 1676b8a077c352085d52578fb4f29350b58b6e74
Cela indique que des données étendues sont disponibles (actuellement pas
utilisées).
.TP
\fBPERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT\fP
.\" commit 930e6fcd2bcce9bcd9d4aa7e755678d33f3fe6f4
Ce bit n'est pas défini par le noyau. Il est réservé à l'outil perf dans
l'espace utilisateur pour indiquer que l'analyse de \fI/proc/i[pid]/maps\fP a
trop duré et a été arrêtée, ainsi les enregistrements mmap peuvent être
tronqués.
.RE
.TP
\fItype\fP
La valeur \fItype\fP est une des suivantes. Les valeurs dans l'enregistrement
correspondant (qui suit l'en\-tête) dépendent du \fItype\fP sélectionné comme
c'est montré.
.RS
.TP 4
\fBPERF_RECORD_MMAP\fP
Les événements MMAP enregistrent les associations \fBPROT_EXEC\fP pour pouvoir
mettre en corrélation les pointeurs d'instruction en espace utilisateur et
le code. Ils ont la structure suivante\ :
.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
est l'identifiant de processus.
.TP
\fItid\fP
est l'identifiant de thread.
.TP
\fIaddr\fP
est l'adresse de la mémoire allouée. \fIlen\fP est la taille de la mémoire
allouée. \fIpgoff\fP est la position de la page de la mémoire
allouée. \fIfilename\fP est une chaîne décrivant la base de la mémoire allouée.
.RE
.TP
\fBPERF_RECORD_LOST\fP
Cet enregistrement indique quand des événements sont perdus.
.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
est l'identifiant unique d'événement pour les échantillons perdus.
.TP
\fIlost\fP
est le nombre d'événements perdus.
.RE
.TP
\fBPERF_RECORD_COMM\fP
Cet enregistrement indique une modification du nom de processus.
.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
est l'identifiant de processus.
.TP
\fItid\fP
est l'identifiant de thread.
.TP
\fIcomm\fP
est une chaîne contenant le nouveau nom du processus.
.RE
.TP
\fBPERF_RECORD_EXIT\fP
Cet enregistrement indique un événement de fin de processus.
.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
Cet enregistrement indique un événement de variation de fréquence du
processeur.
.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
Cet enregistrement indique un événement de création d’enfant.
.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
Cet enregistrement indique un événement de lecture.
.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
Cet enregistrement indique un échantillon.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 sample_id; /* si PERF_SAMPLE_IDENTIFIER */
u64 ip; /* si PERF_SAMPLE_IP */
u32 pid, tid; /* si PERF_SAMPLE_TID */
u64 time; /* si PERF_SAMPLE_TIME */
u64 addr; /* si PERF_SAMPLE_ADDR */
u64 id; /* si PERF_SAMPLE_ID */
u64 stream_id; /* si PERF_SAMPLE_STREAM_ID */
u32 cpu, res; /* si PERF_SAMPLE_CPU */
u64 period; /* si PERF_SAMPLE_PERIOD */
struct read_format v;
/* si PERF_SAMPLE_READ */
u64 nr; /* si PERF_SAMPLE_CALLCHAIN */
u64 ips[nr]; /* si PERF_SAMPLE_CALLCHAIN */
u32 size; /* si PERF_SAMPLE_RAW */
char data[size]; /* si PERF_SAMPLE_RAW */
u64 bnr; /* si PERF_SAMPLE_BRANCH_STACK */
struct perf_branch_entry lbr[bnr];
/* si PERF_SAMPLE_BRANCH_STACK */
u64 abi; /* si PERF_SAMPLE_REGS_USER */
u64 regs[weight(mask)];
/* si PERF_SAMPLE_REGS_USER */
u64 size; /* si PERF_SAMPLE_STACK_USER */
char data[size]; /* si PERF_SAMPLE_STACK_USER */
u64 dyn_size; /* si PERF_SAMPLE_STACK_USER &&
size != 0 */
u64 weight; /* si PERF_SAMPLE_WEIGHT */
u64 data_src; /* si PERF_SAMPLE_DATA_SRC */
u64 transaction; /* si PERF_SAMPLE_TRANSACTION */
u64 abi; /* si PERF_SAMPLE_REGS_INTR */
u64 regs[weight(mask)];
/* si PERF_SAMPLE_REGS_INTR */
u64 phys_addr; /* si PERF_SAMPLE_PHYS_ADDR */
u64 cgroup; /* si PERF_SAMPLE_CGROUP */
};
.EE
.in
.RS 4
.TP 4
\fIsample_id\fP
Si \fBPERF_SAMPLE_IDENTIFIER\fP est activé, un identifiant unique sur 64\ bits
est inclus. C’est une copie de la valeur \fIid\fP de \fBPERF_SAMPLE_ID\fP, mais
incluse au début de l’échantillon pour permettre aux analyseurs d’obtenir
facilement la valeur.
.TP
\fIip\fP
Si \fBPERF_SAMPLE_IP\fP est activé, alors une valeur de pointeur d'instruction
sur 64\ bits est incluse.
.TP
\fIpid\fP, \fItid\fP
Si \fBPERF_SAMPLE_TID\fP est activé, alors un identifiant de processus sur
32\ bits et un identifiant de thread sur 32\ bits sont inclus.
.TP
\fItime\fP
Si \fBPERF_SAMPLE_TIME\fP est activé, alors un horodatage sur 64\ bits est
inclus. C'est obtenu à l'aide de local_clock() qui est un horodatage
matériel si disponible et la valeur \fIjiffy\fP sinon.
.TP
\fIaddr\fP
Si \fBPERF_SAMPLE_ADDR\fP est activé, alors une adresse sur 64\ bits est
incluse. C'est généralement l'adresse d'un point de trace, point d'arrêt ou
événement logiciel\ ; sinon la valeur est \fB0\fP.
.TP
\fIid\fP
Si \fBPERF_SAMPLE_ID\fP est activé, un identifiant unique sur 64\ bits est
inclus. Si l'événement est membre d'un groupe d'événements, l'identifiant du
leader de groupe est renvoyé. Cet identifiant est le même que celui renvoyé
par \fBPERF_FORMAT_ID\fP.
.TP
\fIstream_id\fP
Si \fBPERF_SAMPLE_STREAM_ID\fP est activé, un identifiant unique sur 64\ bits
est inclus. Contrairement à \fBPERF_SAMPLE_ID\fP, le véritable identifiant est
renvoyé, pas celui du leader de groupe. Cet identifiant est le même que
celui renvoyé par \fBPERF_FORMAT_ID\fP.
.TP
\fIcpu\fP, \fIres\fP
Si \fBPERF_SAMPLE_CPU\fP est activé, c'est une valeur sur 32\ bits indiquant le
processeur qui a été utilisé, en supplément d'une valeur réservée (non
utilisée) sur 32\ bits.
.TP
\fIperiod\fP
Si \fBPERF_SAMPLE_PERIOD\fP est activé, une valeur sur 64\ bits indiquant la
période d'échantillonnage actuelle est écrite.
.TP
\fIv\fP
Si \fBPERF_SAMPLE_READ\fP est activé, une structure de type \fIread_format\fP est
incluse avec des valeurs pour tous les événements du groupe
d'événements. Les valeurs incluses dépendent de la valeur \fIread_format\fP
utilisée au moment de \fBperf_event_open\fP().
.TP
\fInr\fP, \fIips[nr]\fP
Si \fBPERF_SAMPLE_CALLCHAIN\fP est activé, alors un nombre sur 64\ bits est
inclus, indiquant le nombre de pointeurs d'instruction sur 64\ bits qui
suivent. C'est l'appel en chaîne actuel.
.TP
\fIsize\fP, \fIdata[size]\fP
Si \fBPERF_SAMPLE_RAW\fP est activé, alors une valeur sur 32\ bits indiquant la
taille est incluse, suivie par un tableau de valeurs sur 8\ bits de taille
\fIsize\fP. Les valeurs sont remplies avec des \fB0\fP pour avoir un alignement à
64\ bits.
.IP
Ces données brutes d'enregistrement sont opaques du point de vue de
l'ABI. L'ABI ne fait pas de promesses sur la stabilité de son contenu qui
pourrait varier en fonction de l'événement, du matériel ou de la version du
noyau.
.TP
\fIbnr\fP, \fIlbr[bnr]\fP
Si \fBPERF_SAMPLE_BRANCH_STACK\fP est activé, alors une valeur de 64\ bits
indiquant le nombre d'enregistrements est incluse, suivie des structures
\fIbnr\fP \fIperf_branch_entry\fP qui chacune contient les champs suivants.
.RS
.TP
\fIfrom\fP
Cela indique l’instruction source (qui pourrait ne pas être un branchement).
.TP
\fIto\fP
La cible de branchement.
.TP
\fImispred\fP
La cible de branchement a été mal prédite.
.TP
\fIpredicted\fP
La cible de branchement a été prédite.
.TP
\fIin_tx\fP (depuis Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
Le branchement était dans une transaction de mémoire transactionnelle.
.TP
\fIabort\fP (depuis Linux 3.11)
.\" commit 135c5612c460f89657c4698fe2ea753f6f667963
Le branchement était dans une transaction abandonnée de mémoire
transactionnelle.
.TP
\fIcycles\fP (depuis Linux 4.3)
.\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f
Cela rend compte du nombre de cycles qui se sont déroulés depuis la dernière
mise à jour de la pile de branchement.
.PP
Les entrées sont présentées dans l’ordre chronologique, de telle sorte que
la première entrée a le branchement le plus récent.
.PP
La prise en charge de \fImispred\fP, \fIpredicted\fP et \fIcycles\fP est
facultative. En absence de prise en charge, les deux valeurs seront \fB0\fP.
.PP
Le type de branchements enregistrés est indiqué par le champ
\fIbranch_sample_type\fP.
.RE
.TP
\fIabi\fP, \fIregs[weight(mask)]\fP
Si \fBPERF_SAMPLE_REGS_USER\fP est activé, alors les registres processeur
utilisateur sont enregistrés.
.IP
Le champ \fIabi\fP est parmi \fBPERF_SAMPLE_REGS_ABI_NONE\fP,
\fBPERF_SAMPLE_REGS_ABI_32\fP ou \fBPERF_SAMPLE_REGS_ABI_64\fP.
.IP
Le champ \fIregs\fP est un tableau de registres processeur qui ont été indiqués
par le champ attr \fIsample_regs_user\fP. Le nombre de valeurs est le nombre de
bits définis dans le masque binaire \fIsample_regs_user\fP.
.TP
\fIsize\fP, \fIdata[size]\fP, \fIdyn_size\fP
Si \fBPERF_SAMPLE_STACK_USER\fP est activé, la pile utilisateur est
enregistrée. Cela peut être utilisé pour générer les backtraces de la
pile. \fIsize\fP est la taille demandée par l’utilisateur dans
\fIsample_stack_user\fP ou autrement la taille maximale
d’enregistrement. \fIdata\fP contient les données de pile (un contenu brut de
la mémoire indiquée par le pointeur de pile au moment de
l'échantillonnage). \fIdyn_size\fP est la quantité de données vraiment renvoyée
(peut être inférieure à \fIsize\fP). Remarquez que \fIdyn_size\fP est omis si
\fIsize\fP vaut \fB0\fP.
.TP
\fIweight\fP
Si \fBPERF_SAMPLE_WEIGHT\fP est activé, une valeur de 64\ bits fournie par le
matériel est enregistrée pour indiquer le coût de l’événement. Cela permet
aux événements coûteux de ressortir plus clairement dans les profils.
.TP
\fIdata_src\fP
Si \fBPERF_SAMPLE_DATA_SRC\fP est activé, alors une valeur de 64\ bits est
enregistrée, constituée des champs suivants.
.RS
.TP 4
\fImem_op\fP
Type de code opération (opcode), une combinaison bit à bit de\ :
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_OP_NA\fP
Non disponible
.TP
\fBPERF_MEM_OP_LOAD\fP
Instruction de chargement
.TP
\fBPERF_MEM_OP_STORE\fP
Instruction de stockage
.TP
\fBPERF_MEM_OP_PFETCH\fP
Prélecture
.TP
\fBPERF_MEM_OP_EXEC\fP
Code exécutable
.RE
.PD
.TP
\fImem_lvl\fP
Niveau de hiérarchie de mémoire atteint ou raté, une combinaison bit à bit
de ce qui suit, envoyés à gauche par \fBPERF_MEM_LVL_SHIFT\fP\ :
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_LVL_NA\fP
Non disponible
.TP
\fBPERF_MEM_LVL_HIT\fP
Atteint
.TP
\fBPERF_MEM_LVL_MISS\fP
Raté
.TP
\fBPERF_MEM_LVL_L1\fP
Cache de niveau 1
.TP
\fBPERF_MEM_LVL_LFB\fP
Tampon de capacité
.TP
\fBPERF_MEM_LVL_L2\fP
Cache de niveau 2
.TP
\fBPERF_MEM_LVL_L3\fP
Cache de niveau 3
.TP
\fBPERF_MEM_LVL_LOC_RAM\fP
DRAM local
.TP
\fBPERF_MEM_LVL_REM_RAM1\fP
DRAM distant 1 saut
.TP
\fBPERF_MEM_LVL_REM_RAM2\fP
DRAM distant 2 sauts
.TP
\fBPERF_MEM_LVL_REM_CCE1\fP
Cache distant 1 saut
.TP
\fBPERF_MEM_LVL_REM_CCE2\fP
Cache distant 2 sauts
.TP
\fBPERF_MEM_LVL_IO\fP
Mémoire d'entrée et sortie.
.TP
\fBPERF_MEM_LVL_UNC\fP
Mémoire sans cache
.RE
.PD
.TP
\fImem_snoop\fP
Mode espionnage, une combinaison bit\-à\-bit de ce qui suit, décalé vers la
gauche par \fBPERF_MEM_SNOOP_SHIFT\fP\ :
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_SNOOP_NA\fP
Non disponible
.TP
\fBPERF_MEM_SNOOP_NONE\fP
Pas d'espionnage
.TP
\fBPERF_MEM_SNOOP_HIT\fP
Espionnage atteint
.TP
\fBPERF_MEM_SNOOP_MISS\fP
Espionnage raté
.TP
\fBPERF_MEM_SNOOP_HITM\fP
Espionnage atteint modifié
.RE
.PD
.TP
\fImem_lock\fP
Instruction de verrouillage, une combinaison bit à bit de ce qui suit,
renvoyée vers la gauche par \fBPERF_MEM_LOCK_SHIFT\fP\ :
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_LOCK_NA\fP
Non disponible
.TP
\fBPERF_MEM_LOCK_LOCKED\fP
Transaction verrouillée
.RE
.PD
.TP
\fImem_dtlb\fP
Accès TLB atteint ou raté, une combinaison bit à bit de ce qui suit,
renvoyée vers la gauche par \fBPERF_MEM_TLB_SHIFT\fP\ :
.IP
.PD 0
.RS
.TP 24
\fBPERF_MEM_TLB_NA\fP
Non disponible
.TP
\fBPERF_MEM_TLB_HIT\fP
Atteint
.TP
\fBPERF_MEM_TLB_MISS\fP
Raté
.TP
\fBPERF_MEM_TLB_L1\fP
TLB de niveau 1
.TP
\fBPERF_MEM_TLB_L2\fP
TLB de niveau 2
.TP
\fBPERF_MEM_TLB_WK\fP
Parcours matériel
.TP
\fBPERF_MEM_TLB_OS\fP
Gestionnaire d'erreur du SE
.RE
.PD
.RE
.TP
\fItransaction\fP
Si l’attribut \fBPERF_SAMPLE_TRANSACTION\fP est défini, alors un champ de
64\ bits est enregistré pour décrire les sources de tous les abandons de
mémoire transactionnelle.
.IP
Le champ est une combinaison bit à bit des valeurs suivantes\ :
.RS
.TP
\fBPERF_TXN_ELISION\fP
Abandon d’une transaction de type élision (spécifique aux processeurs
Intel).
.TP
\fBPERF_TXN_TRANSACTION\fP
Abandon d’une transaction générique.
.TP
\fBPERF_TXN_SYNC\fP
Abandon synchrone (relatif à l’instruction signalée).
.TP
\fBPERF_TXN_ASYNC\fP
Abandon asynchrone (non relatif à l’instruction signalée).
.TP
\fBPERF_TXN_RETRY\fP
Abandon réessayable (réessayer la transaction pourrait réussir).
.TP
\fBPERF_TXN_CONFLICT\fP
Abandon à cause de conflits de mémoire avec d’autres threads.
.TP
\fBPERF_TXN_CAPACITY_WRITE\fP
Abandon à cause de dépassement de la capacité d’écriture.
.TP
\fBPERF_TXN_CAPACITY_READ\fP
Abandon à cause de dépassement de la capacité de lecture.
.RE
.IP
De plus, un code d’abandon spécifique à l’utilisateur peut être obtenu à
partir des premiers 32\ bits du champ en déplaçant vers la droite avec
\fBPERF_TXN_ABORT_SHIFT\fP et en masquant avec \fBPERF_TXN_ABORT_MASK\fP.
.TP
\fIabi\fP, \fIregs[weight(mask)]\fP
Si \fBPERF_SAMPLE_REGS_INTR\fP est activé, alors les registres processeur
utilisateur sont enregistrés.
.IP
Le champ \fIabi\fP est parmi \fBPERF_SAMPLE_REGS_ABI_NONE\fP,
\fBPERF_SAMPLE_REGS_ABI_32\fP ou \fBPERF_SAMPLE_REGS_ABI_64\fP.
.IP
Le champ \fIregs\fP est un tableau des registres processeur qui ont été
indiqués par le champ attr \fIsample_regs_intr\fP. Le nombre de valeurs est le
nombre de bits définis dans le masque binaire \fIsample_regs_intr\fP.
.TP
\fIphys_addr\fP
Si l'attribut \fBPERF_SAMPLE_PHYS_ADDR\fP est positionné, l'adresse physique en
64 bits est enregistrée.
.TP
\fIcgroup\fP
Si l'attribut \fBPERF_SAMPLE_CGROUP\fP est positionné, l'identifiant de cgroup
64\ bits (pour le sous\-système perf_event) est enregistré. Pour récupérer le
chemin du cgroup, l'identifiant doit correspondre à un de ceux se trouvant
dans \fBPERF_RECORD_CGROUP\fP.
.RE
.TP
\fBPERF_RECORD_MMAP2\fP
Cet enregistrement inclut des informations étendues sur les appels
\fBmmap\fP(2) renvoyant des projections exécutables. Le format est identique à
celui de l'enregistrement \fBPERF_RECORD_MMAP\fP mais il comprend des valeurs
supplémentaires qui permettent uniquement d'identifier des projections
partagées.
.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
est l'identifiant de processus.
.TP
\fItid\fP
est l'identifiant de thread.
.TP
\fIaddr\fP
est l'adresse de la mémoire allouée.
.TP
\fIlen\fP
est la taille de la mémoire allouée.
.TP
\fIpgoff\fP
est la position de la page de la mémoire allouée.
.TP
\fImaj\fP
est l'identifiant majeur du périphérique sous\-jacent.
.TP
\fImin\fP
est l'identifiant mineur du périphérique sous\-jacent.
.TP
\fIino\fP
est le numéro d'inœud.
.TP
\fIino_generation\fP
est la génération d'inœud.
.TP
\fIprot\fP
sont les informations de protection.
.TP
\fIdrapeaux\fP
sont les informations d'attributs.
.TP
\fIfilename\fP
est une chaîne décrivant la base de la mémoire allouée.
.RE
.TP
\fBPERF_RECORD_AUX\fP (depuis Linux 4.1)
.\" commit 68db7e98c3a6ebe7284b6cf14906ed7c55f3f7f0
Cet enregistrement rend compte des nouvelles données disponibles dans la
zone séparée du tampon 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
position dans la zone mmap AUX où commencent les nouvelles données.
.TP
\fIaux_size\fP
taille des données disponibles.
.TP
\fIdrapeaux\fP
décrit la mise à jour AUX.
.RS
.TP
\fBPERF_AUX_FLAG_TRUNCATED\fP
s'il est positionné, les données renvoyées ont été tronquées pour rentrer
dans la taille du tampon disponible.
.TP
\fBPERF_AUX_FLAG_OVERWRITE\fP
.\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142
s'il est positionné, les données renvoyées ont écrasé des données
précédentes.
.RE
.RE
.TP
\fBPERF_RECORD_ITRACE_START\fP (depuis Linux 4.1)
.\" ec0d7729bbaed4b9d2d3fada693278e13a3d1368
Cet enregistrement indique le processus qui a initié un événement de traçage
d'instruction, permettant aux outils de corréler correctement les adresses
d'instruction du tampon AUX avec le bon exécutable.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u32 pid;
u32 tid;
};
.EE
.in
.RS
.TP
\fIpid\fP
identifiant de processus du thread ayant commencé un traçage d'instruction.
.TP
\fItid\fP
identifiant du thread ayant commencé le traçage d'instruction.
.RE
.TP
\fBPERF_RECORD_LOST_SAMPLES\fP (depuis Linux 4.2)
.\" f38b0dbb491a6987e198aa6b428db8692a6480f8
Lors de l'utilisation de l'échantillonnage matériel (comme les PEBS
d'Intel), cet enregistrement indique le nombre d'échantillons qui peuvent
avoir été perdus.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
u64 lost;
struct sample_id sample_id;
};
.EE
.in
.RS
.TP
\fIlost\fP
est le nombre d'échantillons potentiellement perdus.
.RE
.TP
\fBPERF_RECORD_SWITCH\fP (depuis Linux 4.3)
.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
Cet enregistrement indique qu'un changement de contexte a eu lieu. Le bit
\fBPERF_RECORD_MISC_SWITCH_OUT\fP du champ \fImisc\fP indique si ce changement
s'est fait dans ou hors du processus.
.IP
.in +4n
.EX
struct {
struct perf_event_header header;
struct sample_id sample_id;
};
.EE
.in
.TP
\fBPERF_RECORD_SWITCH_CPU_WIDE\fP (depuis Linux 4.3)
.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4
Comme avec \fBPERF_RECORD_SWITCH\fP, cet enregistrement indique qu'un
changement de contexte a eu lieu mais il n'arrive que lors de
l'échantillonnage en mode processeur complet et il fournit des informations
supplémentaires sur le processus faisant l'objet du changement. Le bit
\fBPERF_RECORD_MISC_SWITCH_OUT\fP du champ \fImisc\fP indique si le changement a
eu lieu dans ou hors du processus actuel.
.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
L'identifiant du processus précédent ou suivant (selon le sens du
changement) sur le processeur.
.TP
\fInext_prev_tid\fP
L'identifiant du thread précédent ou suivant (selon le sens du changement)
sur le processeur.
.RE
.TP
\fBPERF_RECORD_NAMESPACES\fP (depuis Linux 4.11)
.\" commit e422267322cd319e2695a535e47c5b1feeac45eb
Cet enregistrement comprend diverses informations sur l'espace de noms d'un
processus.
.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
est l'identifiant de processus.
.TP
\fItid\fP
est l'identifiant de thread.
.TP
\fInr_namespace\fP
est le nombre d'espaces de noms de cet enregistrement.
.RE
.IP
Chaque espace de noms a des champs \fIdev\fP et \fIinode\fP et il est enregistré
dans une position fixe comme celle ci\-dessous\ :
.RS
.TP
\fBNET_NS_INDEX\fP=\fB0\fP
espace de noms réseau
.TP
\fBUTS_NS_INDEX\fP=\fB1\fP
espace de noms UTS
.TP
\fBIPC_NS_INDEX\fP=\fB2\fP
espace de noms IPC
.TP
\fBPID_NS_INDEX\fP=\fB3\fP
espace de noms PID
.TP
\fBUSER_NS_INDEX\fP=\fB4\fP
espace de noms utilisateur
.TP
\fBMNT_NS_INDEX\fP=\fB5\fP
Espace de noms de montage
.TP
\fBCGROUP_NS_INDEX\fP=\fB6\fP
espace de noms de groupe de contrôle
.RE
.TP
\fBPERF_RECORD_KSYMBOL\fP (depuis Linux 5.0)
.\" commit 76193a94522f1d4edf2447a536f3f796ce56343b
Cet enregistrement indique un événement d'enregistrement/désenregistrement
des symboles du noyau.
.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
est l'adresse du symbole du noyau.
.TP
\fIlen\fP
est la taille du symbole du noyau.
.TP
\fIksym_type\fP
est le type de symbole du noyau. Actuellement, les types suivants sont
disponibles\ :
.RS
.TP
\fBPERF_RECORD_KSYMBOL_TYPE_BPF\fP
Le symbole du noyau est une fonction BPF.
.RE
.TP
\fIdrapeaux\fP
Si \fBPERF_RECORD_KSYMBOL_FLAGS_UNREGISTER\fP est positionné, cet événement se
produit lors du désenregistrement d'un symbole du noyau.
.RE
.TP
\fBPERF_RECORD_BPF_EVENT\fP (depuis Linux 5.0)
.\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106
Cet enregistrement indique si un programme BPF est chargé ou déchargé.
.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
est une des valeurs suivantes\ :
.RS
.TP
\fBPERF_BPF_EVENT_PROG_LOAD\fP
Un programme BPF est chargé.
.TP
\fBPERF_BPF_EVENT_PROG_UNLOAD\fP
Un programme BPF est déchargé
.RE
.TP
\fIid\fP
est l'identifiant du programme BPF.
.TP
\fItag\fP
est l'étiquette du programme BPF. Actuellement, \fBBPF_TAG_SIZE\fP est défini
à\ \fB8\fP.
.RE
.TP
\fBPERF_RECORD_CGROUP\fP (depuis Linux 5.7)
.\" commit 96aaab686505c449e24d76e76507290dcc30e008
Cet enregistrement indique si un cgroup est créé et activé.
.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
est l'identifiant du cgroup. Il peut aussi être récupéré à l'aide de
\fBname_to_handle_at\fP(2) sur le chemin du cgroup (en tant que gestion de
fichier).
.TP
\fIpath\fP
est le chemin du cgroup depuis la racine.
.RE
.TP
\fBPERF_RECORD_TEXT_POKE\fP (depuis Linux 5.8)
.\" commit e17d43b93e544f5016c0251d2074c15568d5d963
Cet enregistrement indique une modification dans le texte du noyau. Cela
comprend les ajouts et les suppressions de texte et la taille correspondante
est de zéro dans ce cas.
.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
est l'adresse de la modification.
.TP
\fIold_len\fP
est l'ancienne taille.
.TP
\fInew_len\fP
est la nouvelle taille.
.TP
\fIbytes\fP
contient les anciens octets immédiatement suivis des nouveaux.
.RE
.RE
.SS "Gestion du dépassement"
Des événements peuvent être positionnés pour signaler quand on dépasse une
limite, indiquant un dépassement. Les conditions d'un dépassement peuvent
être récupérées avec \fBpoll\fP(2), \fBselect\fP(2) ou
\fBepoll\fP(7). Alternativement, les évènements de dépassement peuvent être
capturés à l'aide d'un gestionnaire de signal en activant les signaux d'E/S
sur le descripteur de fichier\ ; voir le point sur les opérations \fBF_SETOWN\fP
et \fBF_SETSIG\fP dans \fBfcntl\fP(2).
.PP
Les débordements ne sont générés que par les événements d'échantillonnage
(\fIsample_period\fP doit avoir une valeur non nulle).
.PP
Deux façons permettent de générer des notifications de débordement.
.PP
La première est de paramétrer une valeur \fIwakeup_events\fP ou
\fIwakeup_watermark\fP qui générera un signal si un certain nombre
d'échantillons ou d'octets ont été écrits dans le tampon circulaire
mmap. Dans ce cas, un signal de type \fBPOLL_IN\fP est envoyé.
.PP
L'autre façon est d'utiliser l'ioctl \fBPERF_EVENT_IOC_REFRESH\fP. Cet ioctl
ajoute à un compteur qui décrémente à chaque fois que l'événement
dépasse. Quand il est non nul, un signal \fBPOLL_IN\fP est envoyé en cas de
dépassement, mais une fois que la valeur a atteint \fB0\fP, un signal de type
\fBPOLL_HUP\fP est envoyé et l'événement sous\-jacent est désactivé.
.PP
.\" See https://lkml.org/lkml/2011/5/24/337
Le rafraîchissement d'un leader de groupe d'événements rafraîchit toute la
fratrie, et un rafraîchissement avec un paramètre de \fB0\fP active un
rafraîchissement infini. Ces comportements ne sont pas gérés et ne devraient
pas être utilisés.
.PP
.\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883
À partir de Linux\ 3.18, \fBPOLL_HUP\fP est initié si l'événement à surveiller
est rattaché à un processus différent et que celui\-ci se termine.
.SS "Instruction rdpmc"
.\" commit c7206205d00ab375839bd6c7ddb247d600693c09
À partir de Linux\ 3.4 sur x86, l'instruction \fIrdpmc\fP permet d'obtenir des
lectures à faible latence sans avoir à entrer dans le noyau. Remarquez que
l'utilisation de \fIrdpmc\fP n'est pas nécessairement plus rapide que d'autres
méthodes pour lire des valeurs d'événement.
.PP
Cette prise en charge peut être détectée avec le champ \fIcap_usr_rdpmc\fP dans
la page mmap\ ; de la documentation pour calculer les valeurs d'événement est
disponible dans cette section.
.PP
.\" 7911d3f7af14a614617e38245fedf98a724e46a9
À l'origine, quand la prise en charge de rdpmc a été activée, tout processus
(pas seulement ceux ayant un événement perf actif) pouvait utiliser
l'instruction rdpmc pour accéder aux compteurs. À partir de Linux\ 4.0, la
prise en charge de rdpmc n'est autorisée que si un événement est
actuellement activé dans le contexte d'un processus. Pour restaurer l'ancien
comportement, inscrivez la valeur \fB2\fP dans \fI/sys/devices/cpu/rdpmc\fP.
.SS "Appels ioctl perf_event"
Plusieurs ioctls agissent sur les descripteurs de fichier de
\fBperf_event_open\fP().
.TP
\fBPERF_EVENT_IOC_ENABLE\fP
Cela active l'événement individuel ou le groupe d'événements indiqué par
l'argument de descripteur de fichier.
.IP
Si le bit \fBPERF_IOC_FLAG_GROUP\fP est défini dans l’argument ioctl, alors
tous les événements d’un groupe sont activés, même si l’événement indiqué
n’est pas le leader de groupe (mais consultez la section BOGUES).
.TP
\fBPERF_EVENT_IOC_DISABLE\fP
Cela désactive le compteur individuel ou le groupe d'événements indiqué par
l'argument de descripteur de fichier.
.IP
L'activation ou la désactivation du leader d'un groupe active ou désactive
la totalité du groupe. Autrement dit pendant que le leader de groupe est
désactivé, aucun des compteurs du groupe ne compte. L'activation ou la
désactivation d'un membre du groupe qui n'est pas le leader arrête ce son
compteur, mais n'affecte aucun des autres compteurs.
.IP
Si le bit \fBPERF_IOC_FLAG_GROUP\fP est défini dans l’argument ioctl, alors
tous les événements d’un groupe sont désactivés, même si l’événement indiqué
n’est pas le leader de groupe (mais consultez la section BOGUES).
.TP
\fBPERF_EVENT_IOC_REFRESH\fP
Les compteurs de dépassements non hérités peuvent utiliser cela pour activer
un compteur pour un nombre de dépassements indiqué par l'argument, après
lequel il est désactivé. Les appels suivants de cet ioctl ajoutent la valeur
de l'argument au décompte actuel. Un signal avec \fBPOLL_IN\fP défini est
envoyé à chaque dépassement jusqu'à ce que ce compte atteigne \fB0\fP\ ; quand
cela arrive, un signal avec \fBPOLL_HUP\fP défini est envoyé et l'événement est
désactivé. L'utilisation de \fB0\fP comme argument est considéré comme un
comportement indéfini.
.TP
\fBPERF_EVENT_IOC_RESET\fP
Redéfinir le compte d'événements indiqué par l'argument à zéro. Cela ne
réinitialise que les décomptes\ ; réinitialiser les valeurs de multiplexage
\fItime_enabled\fP et \fItime_running\fP est impossible.
.IP
Si le bit \fBPERF_IOC_FLAG_GROUP\fP est défini dans l’argument ioctl, alors
tous les événements d’un groupe sont réinitialisés, même si l’événement
indiqué n’est pas le leader de groupe (mais consultez la section BOGUES).
.TP
\fBPERF_EVENT_IOC_PERIOD\fP
Cela met à jour la période de dépassement pour l’événement.
.IP
.\" commit 3581fe0ef37ce12ac7a4f74831168352ae848edc
.\" commit bad7192b842c83e580747ca57104dd51fe08c223
Depuis Linux\ 3.7 (sur ARM) et Linux\ 3.14 (toutes les autres architectures),
la nouvelle période est effective immédiatement. Sur les noyaux précédents,
la nouvelle période n’était effective qu’après le dépassement suivant.
.IP
L'argument est un pointeur vers une valeur sur 64\ bits contenant la nouvelle
période voulue.
.IP
.\" commit ad0cf3478de8677f720ee06393b3147819568d6a
Avant Linux\ 2.6.36, cet ioctl échouait toujours à cause d’un bogue dans le
noyau.
.TP
\fBPERF_EVENT_IOC_SET_OUTPUT\fP
Cela indique au noyau de signaler les notifications d'événement dans le
descripteur de fichier indiqué plutôt que dans celui par défaut. Les
descripteurs de fichier doivent tous être sur le même processeur.
.IP
L'argument indique le descripteur de fichier désiré ou \fB\-1\fP si la sortie
devrait être ignorée.
.TP
\fBPERF_EVENT_IOC_SET_FILTER\fP (depuis Linux 2.6.33)
.\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830
Cela ajoute un filtre ftrace à cet événement.
.IP
L'argument est un pointeur vers le filtre ftrace voulu.
.TP
\fBPERF_EVENT_IOC_ID\fP (depuis Linux 3.12)
.\" commit cf4957f17f2a89984915ea808876d9c82225b862
Cela renvoie la valeur d’identifiant de l’événement pour le descripteur de
fichier d’événement donné.
.IP
L'argument est un pointeur vers un entier non signé de 64\ bits pour garder
le résultat.
.TP
\fBPERF_EVENT_IOC_SET_BPF\fP (depuis Linux\ 4.1)
.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5
Cela permet de rattacher un programme Berkeley Packet Filter (BPF) à un
événement de traçage d'un kprobe existant. Vous avez besoin des privilèges
\fBCAP_PERFMON\fP (depuis Linux\ 5.8) ou \fBCAP_SYS_ADMIN\fP pour utiliser cet
ioctl.
.IP
Le paramètre est un descripteur de fichier de programme BPF créé par un
appel système \fBbpf\fP(2) précédent.
.TP
\fBPERF_EVENT_IOC_PAUSE_OUTPUT\fP (depuis Linux 4.7)
.\" commit 86e7972f690c1017fd086cdfe53d8524e68c661c
Cela permet de mettre en pause et de relancer le tampon circulaire d'un
événement. Un tampon mis en pause n'empêche pas la génération d'échantillons
mais il les désactive. Les échantillons désactivés sont considérés comme
perdus et provoquent la génération d'un \fBPERF_RECORD_LOST\fP si possible. Un
signal de dépassement peut toujours être récupéré par l'échantillon
désactivé bien que le tampon circulaire reste vide.
.IP
Le paramètre est un entier 32\ bits non signé. Une valeur autre que zéro met
en pause le tampon circulaire alors qu'une valeur de zéro réactive le tampon
circulaire.
.TP
\fBPERF_EVENT_MODIFY_ATTRIBUTES\fP (depuis Linux 4.17)
.\" commit 32ff77e8cc9e66cc4fb38098f64fd54cc8f54573
Cela permet de modifier un événement existant sans le gaspillage de
fermeture et réouverture d’un nouvel événement. Actuellement, cela n'est
pris en charge que pour les événements de points d'arrêt.
.IP
L'argument est un pointeur vers une structure \fIperf_event_attr\fP contenant
les paramètres de l'événement mis à jour.
.TP
\fBPERF_EVENT_IOC_QUERY_BPF\fP (depuis Linux 4.16)
.\" commit f371b304f12e31fe30207c41ca7754564e0ea4dc
Cela permet de chercher les programmes Berkeley Packet Filter (BPF)
rattachés à un point de traçage kprobe existant. Vous ne pouvez rattacher
qu'un programme BPF par événement mais vous pouvez avoir plusieurs
événements rattachés à un point de traçage. Rechercher cette valeur sur un
événement de point de traçage renvoie l'identifiant de tous les programmes
BPF dans tous les événements rattachés au point de traçage. Il vous faut les
privilèges \fBCAP_PERFMON\fP (depuis Linux\ 5.8) ou \fBCAP_SYS_ADMIN\fP pour
utiliser cet ioctl.
.IP
L'argument est un pointeur vers une structure
.in +4n
.EX
struct perf_event_query_bpf {
__u32 ids_len;
__u32 prog_cnt;
__u32 ids[0];
};
.EE
.in
.IP
.\"
Le champ \fIids_len\fP indique le nombre d'identifiants pouvant entrer dans le
tableau \fIids\fP fourni. La valeur \fIprog_cnt\fP est remplie par le noyau avec
le nombre de programmes BPF rattachés. Le tableau \fIids\fP est rempli par
l'identifiant de chaque programme BPF rattaché. S'il y a plus de programmes
que de place dans le tableau, le noyau renverra \fBENOSPC\fP et \fIids_len\fP
indiquera le nombre d'identifiants de programme copiés avec succès.
.SS "Utilisation de prctl(2)"
Un processus peut activer ou désactiver tous les groupes d'événements
actuellement ouverts en utilisant les opérations
\fBPR_TASK_PERF_EVENTS_ENABLE\fP et \fBPR_TASK_PERF_EVENTS_DISABLE\fP de
\fBprctl\fP(2). Cela ne s'applique qu'aux événements créés localement par le
processus appelant. Cela ne s'applique pas aux événements créés par d'autres
processus rattachés au processus appelant ou aux événements d'un processus
parent. Cela n'active et désactive que les leaders de groupe, aucun autre
des membres des groupes.
.SS "Fichiers de configuration relatifs à perf_event"
Fichiers de \fI/proc/sys/kernel/\fP
.RS 4
.TP
\fI/proc/sys/kernel/perf_event_paranoid\fP
Le fichier \fIperf_event_paranoid\fP peut être défini pour restreindre l'accès
aux compteurs de performance\ :
.IP
.PD 0
.RS
.IP 2 4
.\" default changed in commit 0161028b7c8aebef64194d3d73e43bc3b53b5c66
ne permettre que les mesures en espace utilisateur (par défaut depuis
Linux\ 4.6).
.IP 1
permettre à la fois les mesures noyau et utilisateur (par défaut avant
Linux\ 4.6).
.IP 0
permettre l'accès aux données spécifiques au processeur sauf les
échantillons de point de trace bruts\ ;
.IP \-1
pas de restriction.
.RE
.PD
.IP
L'existence du fichier \fIperf_event_paranoid\fP est la méthode officielle pour
déterminer si un noyau gère \fBperf_event_open\fP().
.TP
\fI/proc/sys/kernel/perf_event_max_sample_rate\fP
Cela définit le taux d'échantillonnage maximal. Un réglage trop haut peut
permettre aux utilisateurs d'échantillonner à un taux ayant un impact sur
les performances de la machine et éventuellement planter la machine. La
valeur par défaut est 100\ 000 (échantillons par seconde).
.TP
\fI/proc/sys/kernel/perf_event_max_stack\fP
.\" Introduced in c5dfd78eb79851e278b7973031b9ca363da87a7e
Ce fichier définit la profondeur maximale des entrées de trame de pile
signalées lors de la génération d'une trace.
.TP
\fI/proc/sys/kernel/perf_event_mlock_kb\fP
Le nombre maximal de pages qu'un utilisateur sans droit peut verrouiller
avec \fBmlock\fP(2). La valeur par défaut est 516\ (ko).
.RE
.PP
Fichiers de \fI/sys/bus/event_source/devices/\fP
.PP
.RS 4
Depuis Linux\ 2.6.34, le noyau permet d'avoir plusieurs PMU disponibles pour
la surveillance. Les informations sur la façon de programmer ces PMU sont
disponibles dans \fI/sys/bus/event_source/devices/\fP. Tous les
sous\-répertoires correspondent à une PMU différente.
.TP
\fI/sys/bus/event_source/devices/*/type\fP (depuis Linux 2.6.38)
.\" commit abe43400579d5de0078c2d3a760e6598e183f871
Cela contient un entier qui peut être utilisé dans le champ \fItype\fP de
\fIperf_event_attr\fP pour indiquer la volonté d'utiliser cette PMU.
.TP
\fI/sys/bus/event_source/devices/cpu/rdpmc\fP (depuis Linux 3.4)
.\" commit 0c9d42ed4cee2aa1dfc3a260b741baae8615744f
Si ce fichier est \fB1\fP, alors l’accès direct de l’espace utilisateur aux
registres de compteurs de performance est permis à l’aide de l’instruction
rdpmc. Cela peut être désactivé en écrivant \fB0\fP dans le fichier.
.IP
.\" a66734297f78707ce39d756b656bfae861d53f62
.\" 7911d3f7af14a614617e38245fedf98a724e46a9
À partir de Linux\ 4.0, le comportement a changé pour que \fB1\fP n'autorise
désormais que l'accès aux processus ayant des événements perf actifs et que
\fB2\fP indique l'ancien comportement autorisant l'accès à n'importe quoi.
.TP
\fI/sys/bus/event_source/devices/*/format/\fP (depuis Linux 3.4)
.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
Ce sous\-répertoire contient des renseignements sur les sous\-champs
spécifiques à l’architecture disponibles pour la programmation des divers
champs \fIconfig\fP de la structure \fIperf_event_attr\fP.
.IP
Le contenu de chaque fichier est le nom du champ de configuration, suivi
d’un deux\-points, suivi d’une suite d’intervalles d’entiers séparés par des
virgules. Par exemple, le fichier \fIevent\fP pourrait contenir la valeur
\fIconfig1:1,6\-10,44\fP qui indique que l’événement est un attribut qui occupe
les bits\ 1, 6\ à\ 10 et 44 de \fIperf_event_attr::config1\fP.
.TP
\fI/sys/bus/event_source/devices/*/events/\fP (depuis Linux 3.4)
.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33
Ce sous\-répertoire contient des fichiers avec des événements prédéfinis. Les
contenus sont des chaînes décrivant les réglages d'événements exprimés en
termes des champs trouvés dans le répertoire \fI./format/\fP mentionné
précédemment. Ce ne sont pas nécessairement des listes complètes de tous les
évènements pris en charge par une PMU, mais généralement un sous\-ensemble
d'événements jugés utiles ou intéressants.
.IP
Le contenu de chaque fichier est une liste de noms d’attribut séparés par
des virgules. Chaque entrée a une valeur facultative (soit hexadécimale,
soit décimale). Si aucune valeur n’est indiquée, alors un champ d’un seul
bit de valeur \fB1\fP est supposé. Un exemple d’entrée pourrait ressembler à
\fIevent=0x2,inv,ldlat=3\fP.
.TP
\fI/sys/bus/event_source/devices/*/uevent\fP
Ce fichier est l’interface standard de périphérique du noyau pour
l’injection d’événements de branchement à chaud.
.TP
\fI/sys/bus/event_source/devices/*/cpumask\fP (depuis Linux\ 3.7)
.\" commit 314d9f63f385096580e9e2a06eaa0745d92fe4ac
Le fichier \fIcpumask\fP contient une liste d’entiers séparés par des virgules
indiquant un numéro représentatif de processeur pour chaque socket (boîtier)
de la carte mère. C’est nécessaire lors de la définition d’événements uncore
ou northbridge, puisque ces PMU présentent des événements à travers tous les
sockets.
.RE
.SH "VALEUR RENVOYÉE"
\fBperf_event_open\fP() renvoie le nouveau descripteur de fichier ou \fB\-1\fP en
cas d'erreur (auquel cas \fIerrno\fP contient le code d'erreur).
.SH ERREURS
Les erreurs renvoyées par \fBperf_event_open\fP() peuvent être incohérentes et
peuvent varier suivant les architectures de processeur et les unités de
surveillance des performances.
.TP
\fBE2BIG\fP
Renvoyé si la valeur \fIsize\fP de \fIperf_event_attr\fP est trop petite (plus
petite que \fBPERF_ATTR_SIZE_VER0\fP), trop grande (plus grande que la taille
de page) ou plus grande que ce que le noyau peut gérer et que les octets
supplémentaires ne sont pas zéro. Lorsque \fBE2BIG\fP est renvoyé, le champ
\fIsize\fP de \fIperf_event_attr\fP est remplacé, par le noyau, par la taille
attendue de la structure.
.TP
\fBEACCES\fP
Renvoyé quand l’événement demandé nécessite les droits \fBCAP_PERFMON\fP
(depuis Linux 5.8) ou \fBCAP_SYS_ADMIN\fP (ou un réglage paranoïaque de
perf_event plus permissif). Quelques cas habituels où un processus non
privilégié pourrait tomber sur cette erreur\ : l’attachement à un processus
appartenant à un autre utilisateur, la surveillance de tous les processus
sur un processeur donné (c’est\-à\-dire en indiquant \fB\-1\fP pour l’argument
\fIpid\fP) et l’absence de réglage \fIexclude_kernel\fP quand le réglage
paranoïaque le nécessite.
.TP
\fBEBADF\fP
Renvoyé si le descripteur de fichier \fIgroup_fd\fP n’est pas valable, ou, si
\fBPERF_FLAG_PID_CGROUP\fP est défini, si le descripteur de fichier cgroup dans
\fIpid\fP n’est pas valable.
.TP
\fBEBUSY\fP (depuis Linux\ 4.1)
.\" bed5b25ad9c8a2f5d735ef0bc746ec870c01c1b0
Renvoyé si un événement a déjà un accès exclusif à la PMU.
.TP
\fBEFAULT\fP
Renvoyé si le pointeur \fIattr\fP pointe vers un adresse de mémoire non
valable.
.TP
\fBEINVAL\fP
Renvoyé si l’événement indiqué n’est pas valable. De nombreuse raisons sont
possibles pour cela. Une liste non exhaustive\ : \fIsample_freq\fP est plus
grand que le réglage maximal\ ; le \fIcpu\fP à surveiller n’existe pas\ ;
\fIread_format\fP est hors intervalle\ ; \fIsample_type\fP est hors intervalle\ ; la
valeur \fIflags\fP est hors intervalle\ ; \fIexclusive\fP ou \fIpinned\fP sont définis
et l’événement n’est pas un leader de groupe\ ; les valeurs \fIconfig\fP de
l’événement sont hors de l’intervalle ou des bits réservés définis\ ;
l’événement générique sélectionné n’est pas pris en charge\ ; la place est
insuffisante pour ajouter l’événement sélectionné.
.TP
\fBEINTR\fP
Renvoyé si on essaie de mélanger la gestion de perf et de ftrace pour un
uprobe.
.TP
\fBEMFILE\fP
Chaque événement ouvert utilise un descripteur de fichier. Si un grand
nombre d’événements est ouvert, la limite de descripteurs de fichier par
processus sera atteinte et aucun événement supplémentaire ne pourra être
créé.
.TP
\fBENODEV\fP
Renvoyé quand l’événement implique une fonctionnalité non prise en charge
par le processeur actuel.
.TP
\fBENOENT\fP
Renvoyé si le réglage \fItype\fP n’est pas valable. Cette erreur est également
renvoyée pour certains événements génériques non pris en charge.
.TP
\fBENOSPC\fP
.\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6
Avant Linux\ 3.3, s'il manquait de la place pour l'événement, \fBENOSPC\fP était
renvoyé. Dans Linux\ 3.3, cela a été modifié en \fBEINVAL\fP. \fBENOSPC\fP est
toujours renvoyé en cas de tentative d’ajout de plus d’événements de point
d'arrêt que permis par le matériel.
.TP
\fBENOSYS\fP
Renvoyé si \fBPERF_SAMPLE_STACK_USER\fP est défini dans \fIsample_type\fP et que
ce n’est pas pris en charge par le matériel.
.TP
\fBEOPNOTSUPP\fP
Renvoyé si un événement nécessitant une fonctionnalité spécifique du
matériel est demandé alors qu’il n’y a pas de prise en charge
matérielle. Cela comprend la demande d’événement à faible dérapage si ce
n’est pas pris en charge, le suivi de branchement s’il n’est pas pris en
charge, l’échantillonnage si aucune interruption PMU n’est disponible et les
piles de branchement pour les événements logiciels.
.TP
\fBEOVERFLOW\fP (depuis Linux\ 4.8)
.\" 97c79a38cd454602645f0470ffb444b3b75ce574
Renvoyé si \fBPERF_SAMPLE_CALLCHAIN\fP est demandé et si \fIsample_max_stack\fP
est plus grand que le maximum indiqué dans
\fI/proc/sys/kernel/perf_event_max_stack\fP.
.TP
\fBEPERM\fP
Renvoyé sur beaucoup d’architectures (mais pas toutes) quand un des réglages
\fIexclude_hv\fP, \fIexclude_idle\fP, \fIexclude_user\fP ou \fIexclude_kernel\fP non
pris en charge est indiqué.
.IP
.\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34
Cela peut aussi arriver, comme avec \fBEACCES\fP, quand l’événement demandé
nécessite les droits \fBCAP_PERFMON\fP (depuis Linux\ 5.8) ou \fBCAP_SYS_ADMIN\fP
(ou un réglage paranoïaque de perf_event plus permissif). Cela comprend le
réglage d’un point d'arrêt sur une adresse du noyau et (depuis Linux\ 3.13)
le réglage d’un point de trace de fonction du noyau.
.TP
\fBESRCH\fP
Renvoyé en cas de tentative d’attachement à un processus qui n’existe pas.
.SH VERSIONS
.\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e
.\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6
\fBperf_event_open\fP() a été introduite dans Linux\ 2.6.31 mais était appelée
\fBperf_counter_open\fP(). Elle a été renommée dans Linux\ 2.6.32.
.SH CONFORMITÉ
Cet appel système \fBperf_event_open\fP() est spécifique à Linux et ne devrait
pas être employé dans des programmes destinés à être portables.
.SH NOTES
La glibc ne fournit pas de fonction autour de cet appel système\ ; utilisez
\fBsyscall\fP(2) pour l'appeler. Consultez l'exemple ci\-dessous.
.PP
Le moyen officiel pour savoir si la prise en charge de \fBperf_event_open\fP()
est activée est de vérifier si le fichier
\fI/proc/sys/kernel/perf_event_paranoid\fP existe.
.PP
La capacité \fBCAP_PERFMON\fP (depuis Linux\ 5.58) fournit une approche
sécurisée de la surveillance des performances et des opérations de
visibilité d'un système suivant un principe du moindre privilège (POSIX IEEE
1003.1e). Ces modalités d'accès qui utilisent \fBCAP_PERFMON\fP au lieu du
beaucoup plus puissant \fBCAP_SYS_ADMIN\fP enlève des chances d'une mauvaise
utilisation des droits et rend les opérations plus sécurisées. L'utilisation
de \fBCAP_SYS_ADMIN\fP pour la surveillance sécurisée des performances du
système et une meilleure visibilité est déconseillée et vous devriez
préférer la capacité \fBCAP_PERFMON\fP.
.SH BOGUES
.\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5
L'option \fBF_SETOWN_EX\fP de \fBfcntl\fP(2) est nécessaire pour obtenir
correctement les signaux de dépassement dans les threads. Cela a été
introduit dans Linux\ 2.6.32.
.PP
.\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1
Avant Linux\ 3.3 (en tout cas pour x86), le noyau ne vérifiait pas si les
événements pouvaient être programmés ensemble avant le moment de la
lecture. La même chose arrive sur tous les noyaux connus si le watchdog NMI
est activé. Cela signifie que pour voir si un ensemble donné d'événements
fonctionne, il faut appeler \fBperf_event_open\fP(), démarrer, puis lire avant
d'être sûr de pouvoir obtenir des mesures valables.
.PP
.\" FIXME . cannot find a kernel commit for this one
Avant Linux\ 2.6.34, les contraintes d'événements n'étaient pas renforcées
par le noyau. Dans ce cas, certains événements renverraient «\ 0\ »
silencieusement si le noyau les avait programmés dans un emplacement de
compteur incorrect.
.PP
.\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8
Avant Linux\ 2.6.34, à cause d'un bogue lors du multiplexage, de mauvais
résultats pouvaient être renvoyés.
.PP
.\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd
Les noyaux de Linux\ 2.6.35 à Linux\ 2.6.39 peuvent planter rapidement si
\fIinherit\fP est activé et que de nombreux threads sont démarrés.
.PP
.\" commit 050735b08ca8a016bbace4445fa025b88fee770b
Avant Linux\ 2.6.35, \fBPERF_FORMAT_GROUP\fP ne fonctionnait pas avec les
processus attachés.
.PP
.\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02
À cause d'un bogue dans le code du noyau entre Linux\ 2.6.36 et Linux\ 3.0, le
champ \fIwatermark\fP était ignoré et agissait comme si \fIwakeup_event\fP avait
été choisi si l'union contenait une valeur non nulle.
.PP
.\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e
De Linux\ 2.6.31 à Linux\ 3.4, l’argument ioctl \fBPERF_IOC_FLAG_GROUP\fP était
cassé et opérait à répétition sur l’événement indiqué au lieu d’itérer parmi
tous les événements d’une fratrie d’un groupe.
.PP
.\" commit fa7315871046b9a4c48627905691dbde57e51033
De Linux\ 3.4 à Linux\ 3.11, les bits mmap \fIcap_usr_rdpmc\fP et \fIcap_usr_time\fP
étaient associés au même emplacement. Le code devrait plutôt être modifié
pour utiliser les nouveaux champs \fIcap_user_rdpmc\fP et \fIcap_user_time\fP à la
place.
.PP
.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2
Vérifiez toujours deux fois les résultats. Plusieurs événements généralisés
ont eu de fausses valeurs. Par exemple, les branchements retirés ne
mesuraient pas la bonne chose sur les machines AMD jusqu'au noyau\ 2.6.35.
.SH EXEMPLES
Ce qui suit est un court exemple qui mesure le décompte total d'instructions
d'un appel à \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, "Erreur d'ouverture du leader %llx\en", pe.config);
exit(EXIT_FAILURE);
}
ioctl(fd, PERF_EVENT_IOC_RESET, 0);
ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);
printf("Mesure du décompte d'instructions pour ce printf\en");
ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);
read(fd, &count, sizeof(count));
printf("%lld instructions utilisées\en", count);
close(fd);
}
.EE
.SH "VOIR AUSSI"
\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 dans l'arborescence des
sources du noyau
.SH COLOPHON
Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP
Linux. Une description du projet et des instructions pour signaler des
anomalies et la dernière version de cette page peuvent être trouvées à
l'adresse \%https://www.kernel.org/doc/man\-pages/.
.SH TRADUCTION
La traduction française de cette page de manuel a été créée par
Christophe Blaess ,
Stéphan Rafin ,
Thierry Vignaud ,
François Micaux,
Alain Portal ,
Jean-Philippe Guérard ,
Jean-Luc Coulon (f5ibh) ,
Julien Cristau ,
Thomas Huriaux ,
Nicolas François ,
Florentin Duneau ,
Simon Paillard ,
Denis Barbier ,
David Prévot
et
Jean-Philippe MENGUAL
.
Cette traduction est une documentation libre ; veuillez vous reporter à la
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License version 3
.UE
concernant les conditions de copie et
de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel,
veuillez envoyer un message à
.MT
debian-l10n-french@lists.debian.org
.ME .