HalAllocateHardwareCounters-Funktion (ntddk.h)
Die HalAllocateHardwareCounters-Routine weist eine Reihe von Hardwareleistungsindikatorressourcen zu.
Syntax
NTHALAPI NTSTATUS HalAllocateHardwareCounters(
PGROUP_AFFINITY GroupAffinty,
[in] ULONG GroupCount,
[in] PPHYSICAL_COUNTER_RESOURCE_LIST ResourceList,
[out] PHANDLE CounterSetHandle
);
Parameter
GroupAffinty
Ein Zeiger auf einen Satz von GROUP_AFFINITY Strukturen, der angibt, welche Zählerressourcen von Prozessoren der Consumer anfordert. Wenn dieser Parameter NULL ist, gibt die Anforderung eine Zuordnung für alle Prozessoren im System an.
[in] GroupCount
Gibt die Anzahl GROUP_AFFINITY Strukturen an, die vom GroupAffinty-Parameter bereitgestellt werden, oder null, wenn GroupAffinityNULL ist.
[in] ResourceList
Ein Zeiger auf eine PHYSICAL_COUNTER_RESOURCE_LIST , die die vom Consumer benötigten Ressourcen enthält. Wenn dieser Parameter NULL ist, fordert der Consumer den exklusiven Besitz der Leistungsüberwachungseinheit an.
[out] CounterSetHandle
Ein Zeiger auf einen Speicherort, in den die Routine ein Handle in die zugeordneten Indikatorenressourcen schreibt. Um diese Ressourcen später freizugeben, muss der Aufrufer dieses Handle an die HalFreeHardwareCounters-Routine übergeben. Wenn die angeforderten Zählerressourcen nicht verfügbar sind, legt HalAllocateHardwareCounters *CounterSetHandle = NULL fest und gibt STATUS_INSUFFICIENT_RESOURCES zurück.
Rückgabewert
HalAllocateHardwareCounters gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Mögliche Fehlerrückgabewerte umfassen die folgenden status-Codes.
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Die angeforderten Leistungsindikatorenressourcen sind derzeit nicht verfügbar. |
| STATUS_INVALID_PARAMETER | Der Aufrufer hat einen ungültigen Parameterwert angegeben. |
| STATUS_NOT_SUPPORTED | Der Aufrufer hat Ressourcen in der Ressourcenliste bereitgestellt, die derzeit nicht unterstützt werden. |
Hinweise
Die meisten Prozessoren verfügen über Leistungsüberwachungseinheiten (Performance Monitor Units, PMUs), die eine Reihe von Hardwareindikatoren enthalten. Softwaretools verwenden diese Indikatoren, um verschiedene Aspekte der Systemleistung zu überwachen. In der Regel besteht ein solches Tool aus einem benutzerdefinierten Kernelmodustreiber zum Programmieren der Leistungsindikatoren und einer Benutzermodusanwendung, die mit dem Treiber kommuniziert.
Wenn mehr als ein solches Tool auf einem Computer installiert ist, müssen die zugehörigen Treiber vermeiden, dass sie versuchen, dieselben Hardwareindikatoren gleichzeitig zu verwenden. Um solche Ressourcenkonflikte zu vermeiden, sollten alle Treiber, die Leistungsindikatorenressourcen verwenden, die Routinen HalAllocateHardwareCounters und HalFreeHardwareCounters verwenden, um ihre Freigabe dieser Ressourcen zu koordinieren.
Eine Leistungsindikatorressource ist ein einzelner Hardwareindikator, ein Block zusammenhängender Zähler, ein Counterüberlaufunterbrechung oder eine Ereignispufferkonfiguration in einer PMU.
Vor dem Konfigurieren der Leistungsindikatoren kann ein Treiber die HalAllocateHardwareCounters-Routine aufrufen, um exklusiven Zugriff auf eine Reihe von Indikatorenressourcen zu erhalten. Nachdem der Treiber diese Ressourcen nicht mehr benötigt, muss er die Ressourcen durch Aufrufen der HalFreeHardwareCounters-Routine freigeben.
In Windows-Versionen vor Windows 10 Version 1903 gewährt ein erfolgreicher Aufruf von HalAllocateHardwareCounters dem Aufrufer exklusiven Zugriff auf alle Leistungsindikatorenressourcen in der Leistungsüberwachungseinheit eines Einprozessorsystems. In einem Multiprozessorsystem gewährt ein erfolgreicher Aufruf dem Aufrufer exklusiven Zugriff auf alle Zählerressourcen in allen Prozessoren im System. GroupAffinity und ResourceList müssen NULL und GroupCount null sein.
Ab Windows 10 Version 1903 können Leistungsindikatorenressourcen basierend auf der angegebenen Ressourcenliste und den angegebenen Gruppenaffinitäten zugeordnet werden.
Virtualisierungssoftware virtualisiert in der Regel keine Hardwareleistungsindikatoren. Daher sind diese Indikatoren möglicherweise nicht auf einem virtuellen Computer verfügbar, unabhängig davon, ob HalAllocateHardwareCounters einen status Code von STATUS_SUCCESS zurückgibt. Beispielsweise sind Hardwareleistungsindikatoren auf einem virtuellen Hyper-V-Computer nicht verfügbar, aber HalAllocateHardwareCounters gibt möglicherweise weiterhin STATUS_SUCCESS zurück.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar ab Windows 7. |
| Zielplattform | Universell |
| Header | ntddk.h (include Ntddk.h, Ntifs.h) |
| Bibliothek | Hal.lib |
| DLL | Hal.dll |
| IRQL | PASSIVE_LEVEL |