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

Weitere Informationen

GROUP_AFFINITY

HalFreeHardwareCounters

PHYSICAL_COUNTER_RESOURCE_LIST