Arguments¶

pid == 0 et cpu == -1

Cela mesure le processus ou thread appelant sur tous les processeurs.

pid == 0 et cpu >= 0

Cela ne mesure le processus ou thread appelant que s’il est en cours d’exécution sur le processeur indiqué.

pid > 0 et cpu == -1

Cela mesure le processus ou thread indiqué sur tous les processeurs.

pid > 0 et cpu >= 0

Cela ne mesure le processus ou thread indiqué que s’il est en cours d’exécution sur le processeur indiqué.

pid == -1 et cpu >= 0

Cela mesure tous les processus et threads sur le processeur indiqué. Cela nécessite la capacité CAP_SYS_ADMIN ou une valeur /proc/sys/kernel/perf_event_paranoid strictement inférieure à 1.

pid == -1 et cpu == -1

Ce réglage est incorrect et renverra une erreur.

Quand pid est supérieur à zéro, le droit d'effectuer cet appel système est géré par une vérification PTRACE_MODE_READ_REALCREDS du mode d'accès ptrace ; voir ptrace(2).

L'argument group_fd 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 group_fd = -1. Les autres membres du groupe sont créés par les appels perf_event_open() suivants, avec group_fd défini au descripteur de fichier du leader de groupe (un événement unique créé avec group_fd = -1 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.

L'argument flags est constitué d’un OU binaire entre une ou plusieurs des valeurs suivantes.

PERF_FLAG_FD_CLOEXEC (depuis Linux 3.14)

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 execve(2). L’attribution de « close-on-exec » au moment de la création, plutôt qu’ensuite avec fcntl(2), évite de potentielles situations de compétition où le thread appelant invoque perf_event_open() et fcntl() en même temps qu’un autre thread appelle fork(2) puis execve(2).

PERF_FLAG_FD_NO_GROUP

Cet attribut dit à l'événement d'ignorer le paramètre group_fd, sauf pour initialiser la redirection de la sortie en utilisant l'attribut PERF_FLAG_FD_OUTPUT.

PERF_FLAG_FD_OUTPUT (cassé depuis Linux 2.6.35)

Cet attribut redirige la sortie échantillonnée de l'événement vers le tampon mmap de l'événement indiqué par group_fd.

PERF_FLAG_PID_CGROUP (depuis Linux 2.6.39)

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é test, alors un descripteur de fichier ouvert sur /dev/cgroup/test (en supposant que cgroupfs est monté sur /dev/cgroup) doit être passé au paramètre pid. 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.

La structure perf_event_attr fournit des renseignements de configuration détaillés pour les événements en cours de création.

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 actif */
          task           : 1,   /* tracer la création d’enfants 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 qui doivent être
                                   exécutés */
          use_clockid    :  1,  /* utiliser clockid pour les champs du temps */
          context_switch :  1,  /* données de changement de contexte */
          __reserved_1   : 37;
    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 */
};

Les champs de la structure perf_event_attr sont décrits en détail ci-dessous.

type

Ce champ indique le type d'événement dans son ensemble. Il a une des valeurs suivantes :

size

La taille de la structure perf_event_attr pour compatibilités ascendante et descendante. Définissez-la en utilisant sizeof(struct perf_event_attr) pour permettre au noyau de voir la taille de struct au moment de la compilation.

Le PERF_ATTR_SIZE_VER0 relatif est défini à 64 ; c'était la taille de la première struct publiée. PERF_ATTR_SIZE_VER1 est 72, correspondant à l'addition des points d'arrêts dans Linux 2.6.33. PERF_ATTR_SIZE_VER2 est 80, correspondant à l'addition d'échantillonnage de branchement dans Linux 3.4. PERF_ATR_SIZE_VER3 est 96, correspondant à l'addition de sample_regs_user et sample_stack_user dans Linux 3.7. PERF_ATTR_SIZE_VER4 vaut 104, correspondant à l'ajout de sample_regs_intr dans Linux 3.19. PERF_ATTR_SIZE_VER5 vaut 112, correspondant à l'ajout de aux_watermark dans Linux 4.1.

config

Cela indique l'événement voulu, en conjonction avec le champ type. Les champs config1 et config2 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.

Le champ config peut être défini de différentes façons, en fonction de la valeur du champ type précédemment décrit. Suivent les divers réglages possibles pour config, distingués par type.

Si type est PERF_TYPE_HARDWARE, un des événements processeur matériel généralisé est mesuré. Ils ne sont pas tous disponibles sur toutes les plateformes. Définissez config à une des valeurs suivantes :

Si type est PERF_TYPE_SOFTWARE, les événements logiciels fournis par le noyau sont mesurés. Définissez config à une des valeurs suivantes :

    (perf_hw_cache_id) | (perf_hw_cache_op_id << 8) |
    (perf_hw_cache_op_result_id << 16)

kprobe_func, uprobe_path, kprobe_addr et probe_offset

Ces champs décrivent les kprobe/uprobe pour les PMU dynamiques kprobe et uprobe. Pour kprobe utilisez kprobe_func et probe_offset ou alors utilisez kprobe_addr et laissez le champ kprobe_func à NULL. Pour uprobe, utilisez uprobe_path et probe_offset.

sample_period, sample_freq

Un compteur d'« échantillonnage » génère une notification de dépassement tous les N événements, où N est donné par sample_period. Un compteur d'échantillonnage a sample_period > 0. Quand un dépassement arrive, les données demandées sont enregistrées dans le tampon mmap. Le champ sample_type contrôle les données qui sont enregistrées à chaque dépassement.

sample_freq permet d'utiliser la fréquence au lieu de la période. Dans ce cas, l'attribut freq 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.

sample_type

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 mmap(2). L'ordre de sauvegarde des valeurs dans l'échantillon est documenté dans la sous-section Disposition MMAP ci-dessous ; ce n'est pas l'ordre enum perf_event_sample_format.

read_format

Ce champ indique le format des données renvoyées par read(2) sur un descripteur de fichier perf_event_open().

disabled

Le bit disabled indique si le compteur commence désactivé ou activé. Si désactivé, l'événement peut être activé plus tard par ioctl(2), prctl(2) ou enable_on_exec.

Lors de la création d’un groupe d’événements, le leader de groupe est généralement initialisé avec disabled défini à 1 et tous les événements enfants sont initialisés avec disabled défini à 0. Bien que disabled soit 0, les événements enfants ne démarrent pas avant que le leader de groupe ne soit activé.

inherit

Le bit inherit 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).

L'héritage ne fonctionne pas pour certaines combinaisons de read_format, comme PERF_FORMAT_GROUP.

pinned

Le bit pinned 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 read(2) renvoie 0) jusqu'à ce que le compteur soit ensuite activé ou désactivé.

exclusive

Le bit exclusive 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.

Remarquez que de nombreuses situations non attendues pourraient empêcher de démarrer les événements avec le bit exclusive 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).

exclude_user

Si ce bit est défini, le décompte exclut les événements qui arrivent dans l'espace utilisateur.

exclude_kernel

Si ce bit est défini, le décompte exclut les événements qui arrivent dans l'espace du noyau.

exclude_hv

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.

exclude_idle

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.

mmap

Le bit mmap active la génération des échantillons PERF_RECORD_MMAP pour tous les appels mmap(2) qui ont PROT_EXEC 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.

comm

Le bit comm active le suivi du nom de commande de processus tel que modifié par les appels systèmes exec(2) et prctl(PR_SET_NAME) ainsi que l'écriture dans /proc/self/comm. Si l'attribut comm_exec est positionné avec succès (ce qui est possible depuis Linux 3.16), l'attribut général PERF_RECORD_MISC_COMM_EXEC peut être utilisé pour différencier le cas exec(2) des autres.

freq

Si ce bit est activé, alors sample_frequency est utilisé au lieu de sample_period lors du réglage de l'intervalle d'échantillonnage.

inherit_stat

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 inherit est défini.

enable_on_exec

Si ce bit est défini, un compteur est automatiquement activé après un appel d'exec(2).

task

Si ce bit est défini, alors les notifications de création d’enfant et de fin sont inclues au tampon circulaire.

watermark

Si défini, une notification de débordement arrive lors du passage de la frontière wakeup_watermark. Sinon, les notifications arrivent après les échantillons wakeup_events.

precise_ip (depuis Linux 2.6.35)

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.

Les valeurs possibles du champ sont les suivantes :

mmap_data (depuis Linux 2.6.36)

L’opposé du champ mmap. Cela active la génération des échantillons PERF_RECORD_MMAP pour les appels mmap(2) qui n’ont pas PROT_EXEC défini (par exemple les données et la mémoire partagée SysV).

sample_id_all (depuis Linux 2.6.38)

Si défini, alors TID, TIME, ID, STREAM_ID et CPU peuvent de plus être inclus dans les non PERF_RECORD_SAMPLE si le sample_type correspondant est sélectionné.

Si PERF_SAMPLE_IDENTIFIER 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 id deux fois.

La disposition est décrite par cette pseudostructure :

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 */
};

    

exclude_host (depuis Linux 3.2)

Quand on prend des mesures comprenant les processus exécutant des instances de VM (à savoir si on exécute ioctl(2) KVM_RUN), 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.

exclude_guest (depuis Linux 3.2)

Quand on prend des mesures comprenant les processus exécutant des instances de VM (à savoir si on exécute ioctl(2) KVM_RUN), 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.

exclude_callchain_kernel (depuis Linux 3.7)

Ne pas inclure les appels en chaîne du noyau.

exclude_callchain_user (depuis Linux 3.7)

Ne pas inclure les appels en chaîne d'utilisateur.

mmap2 (depuis Linux 3.16)

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 mmap doit aussi être défini pour que cela fonctionne.

comm_exec (depuis Linux 3.16)

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 comm est activé, l'attribut PERF_RECORD_MISC_COMM_EXEC sera positionné dans le champ misc de l'entête de l'enregistrement comm si l'événement de renommage signalé a été causé par un appel à exec(2). Cela permet aux outils de distinguer les types de renommage du processus.

use_clockid (depuis Linux 4.1)

Cela permet de sélectionner l'horloge interne du noyau Linux à utiliser lors de la génération des horodatages à l'aide du champ clockid. Cela peut faciliter la corrélation des durées d'échantillonnage des perf avec les horodatages générés par d'autres outils.

context_switch (depuis Linux 4.3)

Cela active la génération d'enregistrements PERF_RECORD_SWITCH lors d'un changement de contexte. Cela active aussi la génération d'enregistrements PERF_RECORD_SWITCH_CPU_WIDE 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 perf_event_paranoid stricts.

wakeup_events, wakeup_watermark

Cette union indique le nombre d'échantillons (wakeup_events) ou d'octets (wakeup_watermark) qui arrivent avant un signal de dépassement. Celui utilisé est sélectionné par l'attribut watermark.

wakeup_events ne compte que les types d’enregistrement PERF_RECORD_SAMPLE. Pour recevoir un signal pour tous les types PERF_RECORD arrivant, choisissez watermark et définissez wakeup_watermark à 1.

Avant Linux 3.0, positionner wakeup_events à 0 ne signalait aucun dépassement ; les noyaux plus récents traitent 0 comme 1.

bp_type (depuis Linux 2.6.33)

Cela choisit le type de point d'arrêt. Il s'agit d'un des suivants :

bp_addr (depuis Linux 2.6.33)

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.

config1 (depuis Linux 2.6.39)

config1 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 config normal. OFFCORE_EVENTS brut sur Nehalem/Westmere/SandyBridge utilise ce champ sur Linux 3.3 et les noyaux suivants.

bp_len (depuis Linux 2.6.33)

bp_len est la taille du point d'arrêt mesuré si type est PERF_TYPE_BREAKPOINT. Les options sont HW_BREAKPOINT_LEN_1, HW_BREAKPOINT_LEN_2, HW_BREAKPOINT_LEN_4 et HW_BREAKPOINT_LEN_8. Pour un point d'arrêt, définissez-la à sizeof(long).

config2 (depuis Linux 2.6.39)

config2 est une extension supplémentaire du champ config1.

branch_sample_type (depuis Linux 3.4)

Si PERF_SAMPLE_BRANCH_STACK est activé, alors cela indique les branchements à inclure dans l’enregistrement de branchements.

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.

sample_regs_user (depuis Linux 3.7)

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 arch/ARCH/include/uapi/asm/perf_regs.h.

sample_stack_user (depuis Linux 3.7)

Cela définit la taille de la pile utilisateur à renvoyer si PERF_SAMPLE_STACK_USER est indiqué.

clockid (depuis Linux 4.1)

Si use_clockid est positionné, ce champ sélectionne l'horloge interne de Linux à utiliser pour les horodatages. Les horloges disponibles sont définies dans linux/time.h, où sont actuellement prises en charge CLOCK_MONOTONIC, CLOCK_MONOTONIC_RAW, CLOCK_REALTIME, CLOCK_BOOTTIME et CLOCK_TAI.

aux_watermark (depuis Linux 4.1)

Cela indique la quantité de données nécessaires pour récupérer un échantillonnage PERF_RECORD_AUX.

sample_max_stack (depuis Linux 4.8)

Quand sample_type comprend PERF_SAMPLE_CALLCHAIN, ce champ indique le nombre de trames de pile à rendre compte lors de la génération de la chaîne d'appels.

Lecture des résultats¶

Si vous essayez de lire un tampon utilisé pour la lecture qui n'est pas assez grand pour contenir les données, ENOSPC est renvoyé.

Voici la disposition des données renvoyées par une lecture :

*

Si PERF_FORMAT_GROUP a été indiqué pour permettre de lire tous les événements d'un groupe en une fois :

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];
};

    

*

Si PERF_FORMAT_GROUP n'a pas été indiqué :

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 */
};

    

Les valeurs lues sont les suivantes.

nr

Le nombre d'événements dans le descripteur de fichier. Seulement disponible si PERF_FORMAT_GROUP a été indiqué.

time_enabled, time_running

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 time_enabled et time running peuvent être utilisées pour estimer une valeur d'ordre de grandeur du décompte.

value

Une valeur positive sur 64 bits contenant le résultat du compteur.

id

Une valeur unique globale pour cet événement en particulier, seulement si PERF_FORMAT_ID a été indiqué dans read_format.

Disposition MMAP¶

La taille de mmap devrait être 1+2^n pages, où la première page est une page de métadonnées (struct perf_event_mmap_page) qui contient plusieurs informations comme l'emplacement de la tête du tampon circulaire.

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.

La structure de la première page mmap de métadonnées est la suivante :

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;
}
}

La liste suivante décrit les champs de la structure perf_event_mmap_page plus précisément.

version

Numéro de version de cette structure.

compat_version

La plus petite version avec laquelle elle est compatible.

lock

Un seqlock (sequence lock) pour la synchronisation.

index

Un identifiant unique de compteur matériel.

offset

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.

time_enabled

Temps d'activité de l'événement.

time_running

Temps d'exécution de l'événement.

cap_usr_time / cap_usr_rdpmc / cap_bit0 (depuis Linux 3.4)

Un bogue existait dans la définition de cap_usr_time et cap_usr_rdpmc 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 cap_usr_time ou cap_usr_rdpmc étaient vraiment définis.

Depuis Linux 3.12, ils ont été renommés en cap_bit0 et vous devriez plutôt utiliser les nouveaux champs cap_user_time et cap_user_rdpmc à la place.

cap_bit0_is_deprecated (depuis Linux 3.12)

Si défini, ce bit indique que le noyau est capable de gérer les bits cap_user_time et cap_user_rdpmc différenciés correctement.

Si non, cela indique qu’il s’agit d’un ancien noyau où cap_usr_time et cap_usr_rdpmc pointent vers le même bit et donc que ces deux fonctionnalités devraient être utilisées avec prudence.

cap_usr_rdpmc (depuis Linux 3.12)

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 :

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);

    

cap_user_time (depuis Linux 3.12)

Ce bit indique que le matériel a un compteur temporel sans arrêt, constant (TSC sur x86).

cap_usr_time_zero (depuis Linux 3.12)

Indique la présence de time_zero qui permet d’associer les valeurs d’horodatage à l’horloge matérielle.

pmc_width

Si cap_usr_rdpmc, 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 :

pmc <<= 64 - pmc_width;
pmc >>= 64 - pmc_width; // déplacement du signe à droite
count += pmc;

    

time_shift, time_mult, time_offset

Si cap_usr_time, ces champs peuvent être utilisés pour calculer la différence de temps depuis time_enabled (en nanoseconde) en utilisant rdtsc ou similaire.

    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);
    

Où time_offset, time_mult, time_shift et cyc sont lus dans la boucle seqcount décrite ci-dessus. Cette différence peut être ajoutée à enabled et éventuellement running (si idx), pour améliorer l'échelle :

    enabled += delta;
    if (idx)
        running += delta;
    quot = count / running;
    rem  = count % running;
    count = quot * enabled + (rem * enabled) / running;
    

time_zero (depuis Linux 3.12)

Si cap_usr_time_zero est défini, alors l'horloge matérielle (le compteur temporel TSC sur x86) peut être calculée à partir des valeurs time_zero, time_mult et time_shift :

    time = timestamp - time_zero;
    quot = time / time_mult;
    rem  = time % time_mult;
    cyc = (quot << time_shift) + (rem << time_shift) / time_mult;
    

et vice versa :

    quot = cyc >> time_shift;
    rem  = cyc & (((u64)1 << time_shift) - 1);
    timestamp = time_zero + quot * time_mult +
        ((rem * time_mult) >> time_shift);
    

data_head

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.

Sur les plateformes compatibles SMP, après la lecture de la valeur data_head, l'espace utilisateur devrait renvoyer un rmb().

data_tail

Quand l'association est PROT_WRITE, la valeur data_tail 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.

data_offset (depuis Linux 4.1)

Contient la position de l'emplacement du tampon mmap où les données de l'échantillon de perf commencent.

data_size (depuis Linux 4.1)

Contient la taille de la zone de l'échantillon de perf dans le tampon mmap.

aux_head, aux_tail, aux_offset, aux_size (depuis Linux 4.1)

La zone AUX permet d'appliquer à un mmap(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.

Pour définir une zone AUX, il faut d'abord positionner aux_offset à une position supérieure à data_offset+data_size puis positionner aux_size à 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 RLIMIT_MEMLOCK (voir setrlimit(2)) et dans la gestion des droits perf_event_mlock_kb.

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.

Les pointeurs de tampon circulaire aux_head et aux_tail ont le même comportement et les mêmes règles d'organisation que celles décrites précédemment pour data_head et data_tail.

Les 2^n pages suivantes du tampon circulaire ont la disposition décrite ci-dessous.

Si perf_event_attr.sample_id_all est défini, alors tous les types d'événements auront les champs sample_type 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 PERF_RECORD_SAMPLE ci-dessous, il sera stocké juste après le perf_event_header 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.

Les valeurs mmap commencent par un en-tête :

struct perf_event_header {
    __u32   type;
    __u16   misc;
    __u16   size;
};

Les champs perf_event_header 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.

size

Cela indique la taille de l'enregistrement.

misc

Le champ misc contient des renseignements supplémentaires sur l'échantillon.

Le mode de processeur peut être déterminé à partir de cette valeur en la masquant avec PERF_RECORD_MISC_CPUMODE_MASK et en recherchant un des suivants (remarquez que ce ne sont pas des masques de bits, un seul peut être défini à la fois).

type

La valeur type est une des suivantes. Les valeurs dans l'enregistrement correspondant (qui suit l'en-tête) dépendent du type sélectionné comme c'est montré.

Gestion du dépassement¶

Les débordements ne sont générés que par les événements d'échantillonnage (sample_period doit avoir une valeur non nulle).

Deux façons permettent de générer des notifications de débordement.

La première est de paramétrer une valeur wakeup_events ou wakeup_watermark 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 POLL_IN est envoyé.

L'autre façon est d'utiliser l'ioctl PERF_EVENT_IOC_REFRESH. Cet ioctl ajoute à un compteur qui décrémente à chaque fois que l'événement dépasse. Quand il est non nul, un signal POLL_IN est envoyé en cas de dépassement, mais une fois que la valeur a atteint 0, un signal de type POLL_HUP est envoyé et l'événement sous-jacent est désactivé.

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 0 active un rafraîchissement infini. Ces comportements ne sont pas gérés et ne devraient pas être utilisés.

À partir de Linux 3.18, POLL_HUP est initié si l'événement à surveiller est rattaché à un processus différent et que celui-ci se termine.

Instruction rdpmc¶

Cette prise en charge peut être détectée avec le champ cap_usr_rdpmc dans la page mmap ; de la documentation pour calculer les valeurs d'événement est disponible dans cette section.

À 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 2 dans /sys/devices/cpu/rdpmc.

Appels ioctl perf_event¶

PERF_EVENT_IOC_ENABLE

Cela active l'événement individuel ou le groupe d'événements indiqué par l'argument de descripteur de fichier.

Si le bit PERF_IOC_FLAG_GROUP 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).

PERF_EVENT_IOC_DISABLE

Cela désactive le compteur individuel ou le groupe d'événements indiqué par l'argument de descripteur de fichier.

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.

Si le bit PERF_IOC_FLAG_GROUP 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).

PERF_EVENT_IOC_REFRESH

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 POLL_IN défini est envoyé à chaque dépassement jusqu'à ce que ce compte atteigne 0 ; quand cela arrive, un signal avec POLL_HUP défini est envoyé et l'événement est désactivé. L'utilisation de 0 comme argument est considéré comme un comportement indéfini.

PERF_EVENT_IOC_RESET

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 time_enabled et time_running est impossible.

Si le bit PERF_IOC_FLAG_GROUP 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).

PERF_EVENT_IOC_PERIOD

Cela met à jour la période de dépassement pour l’événement.

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.

L'argument est un pointeur vers une valeur sur 64 bits contenant la nouvelle période voulue.

Avant Linux 2.6.36, cet ioctl échouait toujours à cause d’un bogue dans le noyau.

PERF_EVENT_IOC_SET_OUTPUT

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.

L'argument indique le descripteur de fichier désiré ou -1 si la sortie devrait être ignorée.

PERF_EVENT_IOC_SET_FILTER (depuis Linux 2.6.33)

Cela ajoute un filtre ftrace à cet événement.

L'argument est un pointeur vers le filtre ftrace voulu.

PERF_EVENT_IOC_ID (depuis Linux 3.12)

Cela renvoie la valeur d’identifiant de l’événement pour le descripteur de fichier d’événement donné.

L'argument est un pointeur vers un entier non signé de 64 bits pour garder le résultat.

PERF_EVENT_IOC_SET_BPF (depuis Linux 4.1)

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 CAP_SYS_ADMIN pour utiliser cet ioctl.

Le paramètre est un descripteur de fichier de programme BPF créé par un appel système bpf(2) précédent.

PERF_EVENT_IOC_PAUSE_OUTPUT (depuis Linux 4.7)

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 PERF_RECORD_LOST 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.

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.

PERF_EVENT_MODIFY_ATTRIBUTES (depuis Linux 4.17)

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.

L'argument est un pointeur vers une structure perf_event_attr contenant les paramètres de l'événement mis à jour.

PERF_EVENT_IOC_QUERY_BPF (depuis Linux 4.16)

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 CAP_SYS_ADMIN pour utiliser cet ioctl.

L'argument est un pointeur vers une structure

struct perf_event_query_bpf {
    __u32    ids_len;
    __u32    prog_cnt;
    __u32    ids[0];
};
    

Le champ ids_len indique le nombre d'identifiants pouvant entrer dans le tableau ids fourni. La valeur prog_cnt est remplie par le noyau avec le nombre de programmes BPF rattachés. Le tableau ids 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 ENOSPC et ids_len indiquera le nombre d'identifiants de programme copiés avec succès.

Utilisation de prctl(2)¶

Fichiers de configuration relatifs à perf_event¶

Fichiers de /sys/bus/event_source/devices/