HalAllocateHardwareCounters-Funktion (ntddk.h)
Die HalAllocateHardwareCounters Routine weist eine Reihe von Hardwareleistungsindikatorenressourcen 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 eine Reihe von GROUP_AFFINITY Strukturen, die angeben, welche Gegenressourcen der Prozessoren die Verbraucheranforderungen erfüllen. Wenn dieser Parameter NULL-ist, gibt die Anforderung eine Zuordnung für alle Prozessoren im System an.
[in] GroupCount
Stellt die Anzahl der vom GroupAffinty Parameter bereitgestellten GROUP_AFFINITY Strukturen oder Null bereit, wenn GroupAffinity-NULL-ist.
[in] ResourceList
Ein Zeiger auf eine PHYSICAL_COUNTER_RESOURCE_LIST, die die vom Verbraucher benötigten Ressourcen enthält. Wenn dieser Parameter NULL-ist, fordert der Verbraucher den exklusiven Besitz der Leistungsüberwachungseinheit an.
[out] CounterSetHandle
Ein Zeiger auf eine Position, in die die Routine ein Handle in die zugeordneten Zählerressourcen schreibt. Um diese Ressourcen später freizugeben, muss der Aufrufer dieses Handle an die HalFreeHardwareCounters Routine übergeben. Wenn die angeforderten Leistungsindikatorressourcen nicht verfügbar sind, HalAllocateHardwareCounters sets *CounterSetHandle = NULL- und gibt STATUS_INSUFFICIENT_RESOURCES zurück.
Rückgabewert
HalAllocateHardwareCounters gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Mögliche Fehlerrückgabewerte sind die folgenden Statuscodes.
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Die angeforderten Leistungsindikatorenressourcen sind zurzeit 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. |
Bemerkungen
Die meisten Prozessoren verfügen über Leistungsüberwachungseinheiten (PMUs), die eine Reihe von Hardwarezählern enthalten. Softwaretools verwenden diese Leistungsindikatoren, um verschiedene Aspekte der Systemleistung zu überwachen. In der Regel besteht ein solches Tool aus einem benutzerdefinierten Kernelmodustreiber, um die Zähler und eine Benutzermodusanwendung zu programmieren, die mit dem Treiber kommuniziert.
Wenn mehr als ein solches Tool auf einem Computer installiert ist, müssen die zugehörigen Treiber nicht gleichzeitig versuchen, dieselben Hardwarezähler zu verwenden. Um solche Ressourcenkonflikte zu vermeiden, sollten alle Treiber, die Leistungsressourcen verwenden, die HalAllocateHardwareCounters und HalFreeHardwareCounters Routinen verwenden, um ihre Freigabe dieser Ressourcen zu koordinieren.
Eine Zählerressource ist ein einzelner Hardwarezähler, ein Block zusammenhängender Zähler, ein Zählerüberlaufunterbruch 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 Leistungsindikatorenressourcen zu erhalten. Nachdem der Treiber diese Ressourcen nicht mehr benötigt, muss er die Ressourcen freigeben, indem er die HalFreeHardwareCounters Routine aufruft.
In Versionen von Windows vor Windows 10, Version 1903, gewährt ein erfolgreicher Aufruf von HalAllocateHardwareCounters dem Aufrufer exklusiven Zugriff auf alle Leistungsindikatorenressourcen in der Leistungsüberwachungseinheit eines Einzelprozessorsystems. In einem Multiprozessorsystem gewährt ein erfolgreicher Aufruf dem Aufrufer exklusiven Zugriff auf alle Gegenressourcen in allen Prozessoren im System. "GroupAffinity" und "ResourceList" müssen NULL- sein, und "GroupCount" muss null sein.
Ab Windows 10, Version 1903, können Leistungsressourcen basierend auf der bereitgestellten Ressourcenliste und Gruppenaffinität zugeordnet werden.
Virtualisierungssoftware virtualisiert in der Regel keine Hardwareleistungsindikatoren. Daher sind diese Leistungsindikatoren möglicherweise nicht auf einem virtuellen Computer verfügbar, unabhängig davon, ob HalAllocateHardwareCounters einen Statuscode von STATUS_SUCCESS zurückgibt. Beispielsweise sind Hardwareleistungsindikatoren in einem Hyper-V virtuellen Computer nicht verfügbar, aber HalAllocateHardwareCounters können weiterhin STATUS_SUCCESS zurückgeben.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar ab Windows 7. |
| Zielplattform- | Universal |
| Header- | ntddk.h (enthalten Ntddk.h, Ntifs.h) |
| Library | Hal.lib |
| DLL- | Hal.dll |
| IRQL- | PASSIVE_LEVEL |