KeSetHardwareCounterConfiguration, fonction (ntddk.h)
La routine KeSetHardwareCounterConfiguration spécifie une liste de compteurs matériels à utiliser pour le profilage des threads.
Syntaxe
NTSTATUS KeSetHardwareCounterConfiguration(
[in] PHARDWARE_COUNTER CounterArray,
[in] ULONG Count
);
Paramètres
[in] CounterArray
Pointeur vers un tableau HARDWARE_COUNTER qui décrit la configuration du compteur matériel à utiliser pour le profilage de thread. Chaque élément de tableau est une structure qui décrit un compteur matériel. Avant le retour de la routine, elle copie le contenu de ce tableau dans ses structures de données internes.
[in] Count
Spécifie le nombre d’éléments du tableau vers lesquels pointe le paramètre CounterArray .
Valeur retournée
KeSetHardwareCounterConfiguration retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles sont les suivantes :
| Code de retour | Description |
|---|---|
| STATUS_INVALID_PARAMETER | La valeur du paramètre Count dépasse le nombre maximal de compteurs spécifié par la constante MAX_HW_COUNTERS, qui est définie dans le fichier d’en-tête Ntddk.h. |
| STATUS_WMI_ALREADY_ENABLED | Un ou plusieurs des compteurs spécifiés dans le tableau CounterArray sont déjà activés. |
| STATUS_NOT_IMPLEMENTED | Cette routine n’est pas implémentée pour l’architecture du processeur sur laquelle l’appelant s’exécute. |
Remarques
Dans Windows 7, cette routine est implémentée uniquement pour les architectures x86, x64 et Itanium. Si un appelant s’exécute sur une architecture de processeur qui n’est pas prise en charge, la routine retourne STATUS_NOT_IMPLEMENTED.
Cette routine indique au système d’exploitation les compteurs matériels à utiliser pour le profilage des threads. Appelez cette routine uniquement lorsque le profilage de thread est désactivé. Si le tableau CounterArray spécifie des compteurs matériels actuellement utilisés, la routine échoue et retourne STATUS_WMI_ALREADY_ENABLED.
Un thread d’application peut activer le profilage de thread pour obtenir un ensemble de mesures de performances à partir des compteurs matériels dans l’unité d’analyse des performances (PMU) du processeur local. Le système d’exploitation ne prend en charge qu’une seule application de profilage à la fois. Les instances simultanées d’une application de profilage de thread ne sont pas prises en charge. Un thread peut activer le profilage de thread pour lui-même, mais pas pour d’autres threads.
Lorsque le profilage de thread est activé, le système d’exploitation utilise les compteurs matériels spécifiés dans le dernier appel à KeSetHardwareCounterConfiguration. Chaque appel KeSetHardwareCounterConfiguration réussi remplace toute configuration de compteur matériel qui a pu être définie dans un appel KeSetHardwareCounterConfiguration précédent.
Définissez Nombre = 0 pour spécifier une configuration de compteur matériel vide. Cette configuration empêche efficacement l’utilisation de compteurs matériels pour le profilage de thread. La configuration du compteur matériel par défaut qui existe après le démarrage du système et avant l’appel initial de KeSetHardwareCounterConfiguration est une configuration vide.
L’effet d’un appel KeSetHardwareCounterConfiguration réussi est global. Si un thread d’un processus est profilé, le profileur utilise la configuration du compteur matériel qui a été définie par le dernier appel à KeSetHardwareCounterConfiguration. Dans un système multiprocesseur, un appel KeSetHardwareCounterConfiguration définit la configuration du compteur matériel à utiliser pour le profilage des threads sur tous les processeurs du système, bien que chaque processeur utilise son propre ensemble de compteurs matériels.
Pour éviter les 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.
Pour déterminer si le profilage de thread est activé pour un thread donné, appelez la fonction QueryThreadProfiling .
Pour interroger le système d’exploitation pour la configuration du compteur matériel actuellement en vigueur pour le profilage de thread, appelez la routine KeQueryHardwareCounterConfiguration .
Les logiciels de virtualisation ne virtualisent généralement pas les compteurs de performances matérielles. Par conséquent, il est peu probable que les compteurs de performances matérielles soient disponibles dans une machine virtuelle.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible à partir de Windows 7. |
| Plateforme cible | Universal |
| En-tête | ntddk.h (incluez Ntddk.h) |
| Bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
Voir aussi
Informations de référence sur le profilage des compteurs matériels