Funzione KeSetHardwareCounterConfiguration (ntddk.h)

Articolo
04/21/2023

La routine KeSetHardwareCounterConfiguration specifica un elenco di contatori hardware da usare per la profilatura dei thread.

Sintassi

NTSTATUS KeSetHardwareCounterConfiguration(
  [in] PHARDWARE_COUNTER CounterArray,
  [in] ULONG             Count
);

Parametri

[in] CounterArray

Puntatore a una matrice di HARDWARE_COUNTER che descrive la configurazione del contatore hardware da usare per la profilatura dei thread. Ogni elemento matrice è una struttura che descrive un contatore hardware. Prima della restituzione della routine, il contenuto di questa matrice viene copiato nelle relative strutture di dati interne.

[in] Count

Specifica il numero di elementi nella matrice a cui punta il parametro CounterArray .

Valore restituito

KeSetHardwareCounterConfiguration restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti di errore possibili includono quanto segue:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il valore del parametro Count supera il numero massimo di contatori specificati dalla costante MAX_HW_COUNTERS, definita nel file di intestazione Ntddk.h.
STATUS_WMI_ALREADY_ENABLED	Uno o più contatori specificati nella matrice CounterArray sono già abilitati.
STATUS_NOT_IMPLEMENTED	Questa routine non viene implementata per l'architettura del processore in cui è in esecuzione il chiamante.

Commenti

In Windows 7 questa routine viene implementata solo per le architetture basate su x86, basate su x64 e basate su Itanium. Se un chiamante è in esecuzione in un'architettura del processore non supportata, la routine restituisce STATUS_NOT_IMPLEMENTED.

Questa routine indica al sistema operativo quali contatori hardware usare per la profilatura dei thread. Chiamare questa routine solo quando la profilatura dei thread è disabilitata. Se la matrice CounterArray specifica i contatori hardware attualmente in uso, la routine ha esito negativo e restituisce STATUS_WMI_ALREADY_ENABLED.

Un thread applicazione può consentire la profilatura dei thread per ottenere un set di misurazioni delle prestazioni dai contatori hardware nell'unità di monitoraggio delle prestazioni (PMU) del processore locale. Il sistema operativo supporta una sola applicazione di profilatura alla volta. Le istanze simultanee di un'applicazione di profilatura del thread non sono supportate. Un thread può abilitare la profilatura dei thread per se stessa, ma non per altri thread.

Quando la profilatura dei thread è abilitata, il sistema operativo usa i contatori hardware specificati nell'ultima chiamata a KeSetHardwareCounterConfiguration. Ogni chiamata KeSetHardwareCounterConfiguration riesce a sostituire qualsiasi configurazione del contatore hardware che potrebbe essere stata impostata in una precedente chiamata KeSetHardwareCounterConfiguration .

Impostare Count = 0 per specificare una configurazione vuota del contatore hardware. Questa configurazione impedisce in modo efficace l'uso di contatori hardware per la profilatura dei thread. La configurazione predefinita del contatore hardware esistente dopo l'avvio del sistema e prima della chiamata iniziale KeSetHardwareCounterConfiguration è una configurazione vuota.

L'effetto di una chiamata KeSetHardwareCounterConfiguration riuscita è globale. Se viene profilato un thread in un processo, il profiler usa la configurazione del contatore hardware impostata dall'ultima chiamata a KeSetHardwareCounterConfiguration. In un sistema multiprocessore, una chiamata KeSetHardwareCounterConfiguration imposta la configurazione del contatore hardware da usare per la profilatura dei thread in tutti i processori del sistema, anche se ogni processore usa il proprio set di contatori hardware.

Per evitare conflitti di risorse, tutti i driver che usano risorse contatore devono usare le routine HalAllocateHardwareCounters e HalFreeHardwareCounters per coordinare la condivisione di queste risorse.

Per determinare se la profilatura dei thread è abilitata per un determinato thread, chiamare la funzione QueryThreadProfiling .

Per eseguire una query sul sistema operativo per la configurazione del contatore hardware attualmente attiva per la profilatura dei thread, chiamare la routine KeQueryHardwareCounterConfiguration .

Il software di virtualizzazione in genere non virtualizza i contatori delle prestazioni hardware. Pertanto, è improbabile che i contatori delle prestazioni hardware siano disponibili in una macchina virtuale.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 7.
Piattaforma di destinazione	Universale
Intestazione	ntddk.h (include Ntddk.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL