HalAllocateHardwareCounters, fonction (ntddk.h)
Le HalAllocateHardwareCounters routine 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 les demandes du consommateur demandent. Si ce paramètre est NULL, la requête indique une allocation sur 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 est NULL.
[in] ResourceList
Pointeur vers un PHYSICAL_COUNTER_RESOURCE_LIST contenant les ressources requises par le consommateur. Si ce paramètre est null, le consommateur demande la propriété exclusive de l’unité d’analyse 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 de retour
HalAllocateHardwareCounters retourne STATUS_SUCCESS si l’appel a réussi. Les valeurs de retour d’erreur possibles incluent les codes d’état suivants.
| Retourner le code | Description |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Les ressources de compteur demandées sont actuellement indisponibles. |
| 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 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 ces conflits de ressources, tous les pilotes qui utilisent des ressources de compteur doivent utiliser les HalAllocateHardwareCounters et HalFreeHardwareCounters routines 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 le HalAllocateHardwareCounters routine pour acquérir 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 le HalFreeHardwareCounters routine.
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 être 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 des ressources et des affinités de groupe fournies.
Le logiciel de virtualisation ne virtualise généralement pas les compteurs de performances matérielles. Par conséquent, ces compteurs peuvent ne pas être disponibles dans une machine virtuelle, que HalAllocateHardwareCounters retourne un code d’état 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 7. |
| plateforme cible | Universel |
| d’en-tête | ntddk.h (include Ntddk.h, Ntifs.h) |
| bibliothèque | Hal.lib |
| DLL | Hal.dll |
| IRQL | PASSIVE_LEVEL |