KeSetHardwareCounterConfiguration-Funktion (ntddk.h)

  • Artikel

Die KeSetHardwareCounterConfiguration-Routine gibt eine Liste der Hardwareindikatoren an, die für die Threadprofilerstellung verwendet werden sollen.

Syntax

NTSTATUS KeSetHardwareCounterConfiguration(
  [in] PHARDWARE_COUNTER CounterArray,
  [in] ULONG             Count
);

Parameter

[in] CounterArray

Ein Zeiger auf ein HARDWARE_COUNTER Array, das die Konfiguration des Hardwareindikators beschreibt, die für die Threadprofilerstellung verwendet werden soll. Jedes Arrayelement ist eine Struktur, die einen Hardwarezähler beschreibt. Bevor die Routine zurückgibt, kopiert sie den Inhalt dieses Arrays in die internen Datenstrukturen.

[in] Count

Gibt die Anzahl der Elemente im Array an, auf die vom CounterArray-Parameter verwiesen wird.

Rückgabewert

KeSetHardwareCounterConfiguration gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte sind:

Rückgabecode Beschreibung
STATUS_INVALID_PARAMETER Der Wert des Count-Parameters überschreitet die maximale Anzahl von Leistungsindikatoren, die von der MAX_HW_COUNTERS-Konstante angegeben wird, die in der Headerdatei "Ntddk.h" definiert ist.
STATUS_WMI_ALREADY_ENABLED Mindestens einer der Leistungsindikatoren, die im CounterArray-Array angegeben sind, sind bereits aktiviert.
STATUS_NOT_IMPLEMENTED Diese Routine wird nicht für die Prozessorarchitektur implementiert, auf der der Aufrufer ausgeführt wird.

Hinweise

In Windows 7 wird diese Routine nur für die x86-basierten, x64-basierten und Itanium-basierten Architekturen implementiert. Wenn ein Aufrufer in einer Prozessorarchitektur ausgeführt wird, die nicht unterstützt wird, gibt die Routine STATUS_NOT_IMPLEMENTED zurück.

Diese Routine teilt dem Betriebssystem mit, welche Hardwareindikatoren für die Threadprofilerstellung verwendet werden sollen. Rufen Sie diese Routine nur auf, wenn die Threadprofilerstellung deaktiviert ist. Wenn das CounterArray-Array Hardwareindikatoren angibt, die derzeit verwendet werden, schlägt die Routine fehl und gibt STATUS_WMI_ALREADY_ENABLED zurück.

Ein Anwendungsthread kann die Threadprofilerstellung aktivieren, um eine Reihe von Leistungsmessungen von den Hardwareindikatoren in der Leistungsüberwachungseinheit (Performance Monitoring Unit, PMU) des lokalen Prozessors zu erhalten. Das Betriebssystem unterstützt jeweils nur eine Profilerstellungsanwendung. Gleichzeitige Instanzen einer Threadprofilerstellungsanwendung werden nicht unterstützt. Ein Thread kann die Threadprofilerstellung für sich selbst aktivieren, aber nicht für andere Threads.

Wenn die Threadprofilerstellung aktiviert ist, verwendet das Betriebssystem die Hardwareindikatoren, die im letzten Aufruf von KeSetHardwareCounterConfiguration angegeben wurden. Jeder erfolgreiche KeSetHardwareCounterConfiguration-Aufruf ersetzt alle Hardwarezählerkonfigurationen, die möglicherweise in einem vorherigen KeSetHardwareCounterConfiguration-Aufruf festgelegt wurden.

Legen Sie Count = 0 fest, um eine leere Hardwareindikatorkonfiguration anzugeben. Diese Konfiguration verhindert effektiv die Verwendung von Hardwareindikatoren für die Threadprofilerstellung. Die Standardkonfiguration des Hardwareindikators, die nach dem Systemstart und vor dem anfänglichen KeSetHardwareCounterConfiguration-Aufruf vorhanden ist, ist eine leere Konfiguration.

Die Auswirkung eines erfolgreichen KeSetHardwareCounterConfiguration-Aufrufs ist global. Wenn ein Thread in einem Prozess profiliert wird, verwendet der Profiler die Hardwarezählerkonfiguration, die durch den letzten Aufruf von KeSetHardwareCounterConfiguration festgelegt wurde. In einem Multiprozessorsystem legt ein KeSetHardwareCounterConfiguration-Aufruf die Hardwarezählerkonfiguration fest, die für die Threadprofilerstellung für alle Prozessoren im System verwendet werden soll, obwohl jeder Prozessor einen eigenen Satz von Hardwareindikatoren verwendet.

Um Ressourcenkonflikte zu vermeiden, sollten alle Treiber, die Leistungsindikatorenressourcen verwenden, die Routinen HalAllocateHardwareCounters und HalFreeHardwareCounters verwenden, um die Freigabe dieser Ressourcen zu koordinieren.

Um festzustellen, ob die Threadprofilerstellung für einen bestimmten Thread aktiviert ist, rufen Sie die QueryThreadProfiling-Funktion auf .

Rufen Sie die KeQueryHardwareCounterConfiguration-Routine auf, um das Betriebssystem nach der Hardwareindikatorkonfiguration abzufragen, die derzeit für die Threadprofilerstellung gilt.

Virtualisierungssoftware virtualisiert in der Regel keine Hardwareleistungsindikatoren. Daher ist es unwahrscheinlich, dass Hardwareleistungsindikatoren auf einem virtuellen Computer verfügbar sind.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar ab Windows 7.
Zielplattform Universell
Header ntddk.h (include Ntddk.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL

Weitere Informationen

Referenz zur Profilerstellung des Hardwareindikators

HARDWARE_COUNTER

HalAllocateHardwareCounters

HalFreeHardwareCounters

KeQueryHardwareCounterConfiguration