Sous-routine pm_init

Objectif

Initialise les API du moniteur de performances.

Bibliothèque

Bibliothèque d'API Performance Monitor (libpmapi.a)

Syntaxe

#include <pmapi.h>

int pm_init ( filter, *pminfo, *pm_groups_info)
int filter;
pm_info_t *pminfo;
pm_groups_info_t *pm_groups_info;

Descriptif

La sous-routine pm_init initialise la bibliothèque de l'API Performance Monitor. Elle renvoie, après avoir pris en compte un filtre sur le statut des événements, le nombre de compteurs disponibles sur ce processeur et une table par compteur avec la liste des événements disponibles. Pour chaque événement, un identificateur d'événement, un statut, un indicateur indiquant si l'événement peut être utilisé avec un seuil, deux noms et une description sont fournis.

L'identificateur d'événement est utilisé avec toutes les interfaces pm_set_program et est également renvoyé par toutes les interfaces pm_get_program . Seuls les identificateurs d'événement présents dans la table renvoyée peuvent être utilisés. En d'autres termes, le filtre est effectif pour tous les appels d'API.

Le statut indique si l'événement a été vérifié, s'il n'est pas encore vérifié ou s'il fonctionne avec un certain avertissement, comme expliqué dans la description. Cette zone est nécessaire car le filtre peut être n'importe quelle combinaison des trois bits de statut disponibles. L'indicateur pointe vers des événements qui peuvent être utilisés avec un seuil.

Seuls les événements catégorisés comme vérifiés ont fait l'objet d'une vérification complète. Les événements classés comme avertissement ont été vérifiés uniquement dans les limites indiquées dans la description de l'événement. Les événements classés comme non vérifiés ont une exactitude non définie. Soyez prudent avec les événements non vérifiés ; le logiciel Performance Monitor fournit essentiellement un service pour lire les registres matériels qui peuvent ou non avoir un contenu significatif. Les utilisateurs peuvent expérimenter avec des compteurs d'événements non vérifiés et déterminer eux-mêmes ce qu'ils peuvent utiliser pour des situations d'optimisation spécifiques.

Le nom mnémonique abrégé est fourni pour faciliter la recherche par mot clé dans la table des événements (voir l'exemple de programme /usr/samples/pmapi/sysapit2.c pour le code utilisant les noms mnémoniques). Le nom complet de l'événement est également disponible et une description complète de chaque événement est renvoyée.

La structure renvoyée comporte également le multiplicateur de seuil pour ce processeur et le nom du processeur

Sur certaines plateformes, il est possible de spécifier des groupes d'événements à la place d'événements individuels. Les groupes d'événements sont des ensembles prédéfinis d'événements. Au lieu de spécifier chaque événement individuellement, un ID de groupe unique est spécifié. Sur certaines plateformes, telles que POWER4, l'utilisation des groupes d'événements est requise et les tentatives de spécification d'événements individuels renvoient une erreur.

L'interface de pm_init a été améliorée pour renvoyer la liste des groupes d'événements pris en charge dans un troisième paramètre facultatif. Pour la compatibilité binaire, le troisième paramètre doit être explicitement demandé en utilisant l'indicateur de bit PM_GET_GROUPS dans le paramètre filter .

Si le paramètre pm_groups_info renvoyé par pm_init est NULL, aucun groupe d'événements n'est pris en charge pour la plateforme. Sinon, un tableau de structures pm_groups_t est renvoyé dans la zone event_groups . La longueur du tableau est donnée par la zone max_groups .

La structure pm_groups_t contient un identificateur de groupe, deux noms et une description similaires à ceux des événements individuels. En outre, il existe un tableau d'entiers qui spécifient les événements contenus dans le groupe.

Paramètres

Valeurs renvoyées

Codes d'erreur

Voir la sous-routine pm_error (pm_error Subroutine).

Fichiers