Fonction HalAllocateHardwareCounters (ntddk.h)

  • Article

La routine HalAllocateHardwareCounters alloue un ensemble de ressources de compteur de performances matérielles.

Syntaxe

NTHALAPI NTSTATUS HalAllocateHardwareCounters(
        PGROUP_AFFINITY                 GroupAffinty,
  [in]  ULONG                           GroupCount,
  [in]  PPHYSICAL_COUNTER_RESOURCE_LIST ResourceList,
  [out] PHANDLE                         CounterSetHandle
);

Paramètres

GroupAffinty

Pointeur vers un ensemble de structures GROUP_AFFINITY indiquant les ressources de compteur des processeurs que le consommateur demande. Si ce paramètre a la valeur NULL, la demande indique une allocation entre tous les processeurs du système.

[in] GroupCount

Fournit le nombre de structures GROUP_AFFINITY fournies par le paramètre GroupAffinty , ou zéro si GroupAffinity a la valeur NULL.

[in] ResourceList

Pointeur vers un PHYSICAL_COUNTER_RESOURCE_LIST contenant les ressources requises par le consommateur. Si ce paramètre a la valeur NULL, le consommateur demande la propriété exclusive de l’unité de surveillance des performances.

[out] CounterSetHandle

Pointeur vers un emplacement dans lequel la routine écrit un handle dans les ressources de compteur allouées. Pour libérer ces ressources ultérieurement, l’appelant doit passer ce handle à la routine HalFreeHardwareCounters . Si les ressources de compteur demandées ne sont pas disponibles, HalAllocateHardwareCounters définit *CounterSetHandle = NULL et retourne STATUS_INSUFFICIENT_RESOURCES.

Valeur retournée

HalAllocateHardwareCounters retourne STATUS_SUCCESS si l’appel a réussi. Les valeurs de retour d’erreur possibles incluent les codes status suivants.

Code de retour Description
STATUS_INSUFFICIENT_RESOURCES Les ressources de compteur demandées ne sont actuellement pas disponibles.
STATUS_INVALID_PARAMETER L’appelant a spécifié une valeur de paramètre non valide.
STATUS_NOT_SUPPORTED L’appelant a fourni des ressources dans la liste des ressources qui ne sont actuellement pas prises en charge.

Remarques

La plupart des processeurs ont des unités d’analyse de performances (PMU) qui contiennent un certain nombre de compteurs matériels. Les outils logiciels utilisent ces compteurs pour surveiller différents aspects des performances du système. En règle générale, un tel outil se compose d’un pilote en mode noyau personnalisé pour programmer les compteurs et d’une application en mode utilisateur qui communique avec le pilote.

Si plusieurs de ces outils sont installés sur un ordinateur, les pilotes associés doivent éviter d’essayer d’utiliser les mêmes compteurs matériels simultanément. Pour éviter de tels conflits de ressources, tous les pilotes qui utilisent des ressources de compteur doivent utiliser les routines HalAllocateHardwareCounters et HalFreeHardwareCounters pour coordonner leur partage de ces ressources.

Une ressource de compteur est un compteur matériel unique, un bloc de compteurs contigus, une interruption de dépassement de compteur ou une configuration de mémoire tampon d’événement dans un PMU.

Avant de configurer les compteurs, un pilote peut appeler la routine HalAllocateHardwareCounters pour obtenir un accès exclusif à un ensemble de ressources de compteur. Une fois que le pilote n’a plus besoin de ces ressources, il doit libérer les ressources en appelant la routine HalFreeHardwareCounters .

Dans les versions de Windows antérieures à Windows 10 version 1903, un appel réussi à HalAllocateHardwareCounters accorde à l’appelant un accès exclusif à toutes les ressources de compteur dans l’unité d’analyse de performances d’un système à processeur unique. Dans un système multiprocesseur, un appel réussi accorde à l’appelant un accès exclusif à toutes les ressources de compteur dans tous les processeurs du système. GroupAffinity et ResourceList doivent avoir la valeur NULL et GroupCount doit être égal à zéro.

À compter de Windows 10 version 1903, les ressources de compteur peuvent être allouées en fonction de la liste de ressources et des affinités de groupe fournies.

Les logiciels de virtualisation ne virtualisent généralement pas les compteurs de performances matériels. Par conséquent, ces compteurs peuvent ne pas être disponibles dans une machine virtuelle, que HalAllocateHardwareCounters retourne ou non un code status de STATUS_SUCCESS. Par exemple, les compteurs de performances matérielles ne sont pas disponibles dans une machine virtuelle Hyper-V, mais HalAllocateHardwareCounters peut toujours retourner STATUS_SUCCESS.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Disponible à partir de Windows 7.
Plateforme cible Universal
En-tête ntddk.h (inclure Ntddk.h, Ntifs.h)
Bibliothèque Hal.lib
DLL Hal.dll
IRQL PASSIVE_LEVEL

Voir aussi

GROUP_AFFINITY

HalFreeHardwareCounters

PHYSICAL_COUNTER_RESOURCE_LIST