Funzione HalAllocateHardwareCounters (ntddk.h)
La routine HalAllocateHardwareCounters alloca un set di risorse del contatore delle prestazioni hardware.
Sintassi
NTHALAPI NTSTATUS HalAllocateHardwareCounters(
PGROUP_AFFINITY GroupAffinty,
[in] ULONG GroupCount,
[in] PPHYSICAL_COUNTER_RESOURCE_LIST ResourceList,
[out] PHANDLE CounterSetHandle
);
Parametri
GroupAffinty
Puntatore a un set di strutture GROUP_AFFINITY che indicano le risorse contatori dei processori richieste dal consumer. Se questo parametro è NULL, la richiesta indica un'allocazione in tutti i processori del sistema.
[in] GroupCount
Specifica il numero di strutture GROUP_AFFINITY fornite dal parametro GroupAffinty o zero se GroupAffinity è NULL.
[in] ResourceList
Puntatore a un PHYSICAL_COUNTER_RESOURCE_LIST contenente le risorse necessarie dal consumer. Se questo parametro è NULL, il consumer richiede la proprietà esclusiva dell'unità di monitoraggio delle prestazioni.
[out] CounterSetHandle
Puntatore a una posizione in cui la routine scrive un handle nelle risorse del contatore allocato. Per rilasciare queste risorse in un secondo momento, il chiamante deve passare questo handle alla routine HalFreeHardwareCounters . Se le risorse del contatore richieste non sono disponibili, HalAllocateHardwareCounters imposta *CounterSetHandle = NULL e restituisce STATUS_INSUFFICIENT_RESOURCES.
Valore restituito
HalAllocateHardwareCounters restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. I valori restituiti degli errori possibili includono i codici di stato seguenti.
| Codice restituito | Descrizione |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Le risorse del contatore richieste non sono attualmente disponibili. |
| STATUS_INVALID_PARAMETER | Il chiamante ha specificato un valore di parametro non valido. |
| STATUS_NOT_SUPPORTED | Il chiamante ha fornito risorse nell'elenco di risorse attualmente non supportato. |
Commenti
La maggior parte dei processori include unità di monitoraggio delle prestazioni (PMU) che contengono un numero di contatori hardware. Gli strumenti software usano questi contatori per monitorare vari aspetti delle prestazioni del sistema. In genere, questo strumento è costituito da un driver in modalità kernel personalizzato per programmare i contatori e un'applicazione in modalità utente che comunica con il driver.
Se più di uno strumento di questo tipo è installato in un computer, i driver associati devono evitare di provare a usare contemporaneamente gli stessi contatori hardware. Per evitare conflitti di tali risorse, tutti i driver che usano le risorse contatori devono usare le routine HalAllocateHardwareCounters e HalFreeHardwareCounters per coordinare la condivisione di queste risorse.
Una risorsa contatore è un singolo contatore hardware, un blocco di contatori contigui, un interruzione del overflow del contatore o una configurazione del buffer eventi in un PMU.
Prima di configurare i contatori, un driver può chiamare la routine HalAllocateHardwareCounters per acquisire l'accesso esclusivo a un set di risorse contatori. Dopo che il driver non ha più bisogno di queste risorse, deve liberare le risorse chiamando la routine HalFreeHardwareCounters .
Nelle versioni di Windows prima di Windows 10 versione 1903, una chiamata riuscita a HalAllocateHardwareCounters concede al chiamante l'accesso esclusivo a tutte le risorse del contatore nell'unità di monitoraggio delle prestazioni di un sistema a processore singolo. In un sistema multiprocessore, una chiamata riuscita concede al chiamante l'accesso esclusivo a tutte le risorse del contatore in tutti i processori del sistema. GroupAffinity e ResourceList devono essere NULL e GroupCount deve essere zero.
A partire da Windows 10 versione 1903, è possibile allocare le risorse contatori in base all'elenco di risorse e alle affinità di gruppo fornite.
Il software di virtualizzazione in genere non virtualizza i contatori delle prestazioni hardware. Pertanto, questi contatori potrebbero non essere disponibili in una macchina virtuale, indipendentemente dal fatto che HalAllocateHardwareCounters restituisce un codice di stato di STATUS_SUCCESS. Ad esempio, i contatori delle prestazioni hardware non sono disponibili in una macchina virtuale Hyper-V, ma HalAllocateHardwareCounters potrebbe comunque restituire STATUS_SUCCESS.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile a partire da Windows 7. |
| Piattaforma di destinazione | Universale |
| Intestazione | ntddk.h (include Ntddk.h, Ntifs.h) |
| Libreria | Hal.lib |
| DLL | Hal.dll |
| IRQL | PASSIVE_LEVEL |