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 tra tutti i processori nel sistema.
[in] GroupCount
Fornisce il numero di strutture GROUP_AFFINITY fornite dal parametro GroupAffinty oppure zero se groupAffinity è null.
[in] ResourceList
Puntatore a un PHYSICAL_COUNTER_RESOURCE_LIST contenente le risorse richieste 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 allocate. 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 di errore 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 | Risorse fornite dal chiamante nell'elenco di risorse attualmente non supportate. |
Osservazioni
La maggior parte dei processori ha 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, tale 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 in un computer sono installati più strumenti di questo tipo, i driver associati devono evitare di provare a usare contemporaneamente gli stessi contatori hardware. Per evitare conflitti di risorse di questo tipo, tutti i driver che usano risorse contatore 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 interrupt di overflow del contatore o una configurazione del buffer eventi in una pmU.
Prima di configurare i contatori, un driver può chiamare il HalAllocateHardwareCounters routine per acquisire l'accesso esclusivo a un set di risorse contatore. Dopo che il driver non ha più bisogno di queste risorse, deve liberare le risorse chiamando la routine HalFreeHardwareCounters.
Nelle versioni di Windows precedenti a 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, le risorse del contatore possono essere allocate 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 restituisca 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 potrebbero comunque restituire STATUS_SUCCESS.
Fabbisogno
| 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 |