KeSetSystemAffinityThreadEx-Funktion (wdm.h)

  • Artikel

Die KeSetSystemAffinityThreadEx-Routine legt die Systemaffinität des aktuellen Threads fest.

Syntax

KAFFINITY KeSetSystemAffinityThreadEx(
  [in] KAFFINITY Affinity
);

Parameter

[in] Affinity

Eine Variable vom Typ KAFFINITY, die die neue Systemaffinität des aktuellen Threads angibt.

Rückgabewert

KeSetSystemAffinityThreadEx gibt entweder die vorherige Systemaffinität des aktuellen Threads oder null zurück, um anzugeben, dass keine vorherige Systemaffinität vorhanden war.

Hinweise

KeSetSystemAffinityThreadEx ändert die Affinitätsmaske des aktuellen Threads. Die Affinitätsmaske identifiziert eine Gruppe von Prozessoren, auf denen der Thread ausgeführt werden kann. Bei erfolgreicher Ausführung plant die Routine die Ausführung des Threads auf einem Prozessor in diesem Satz.

Aufrufer von KeSetSystemAffinityThreadEx sollten den Rückgabewert speichern und diesen Wert später an die KeRevertToUserAffinityThreadEx-Routine übergeben, um die vorherige Affinitätsmaske wiederherzustellen.

In einem Multiprozessorsystem muss eine Kernelmodustreiberroutine, die im Kontext eines Benutzermodusthreads ausgeführt wird, möglicherweise KeSetSystemAffinityThreadEx aufrufen, um die Affinitätsmaske des Threads vorübergehend zu ändern. Bevor die Routine beendet wird, sollte KeRevertToUserAffinityThreadEx aufgerufen werden, um die Affinitätsmaske des Threads auf ihren ursprünglichen Wert wiederherzustellen.

Der Begriff Benutzeraffinität bezieht sich auf die ursprüngliche Affinität des Benutzermodusthreads. Die vom Kernelmodustreiber festgelegte Affinität wird als Systemaffinität bezeichnet. Wenn ein Aufruf von KeSetSystemAffinityThreadEx die Benutzeraffinität eines Threads durch eine Systemaffinität ersetzt, gibt der Aufruf null zurück. Später stellt der Treiber die Benutzeraffinität wieder her, indem er KeRevertToUserAffinityThreadEx aufruft und diesen Rückgabewert (null) als Affinity-Wert übergibt.

Darüber hinaus kann eine Kernelmodustreiberroutine, die eine bestimmte Affinitätsmaske erfordert, eine andere Kernelmodusroutine aufrufen, die eine andere Affinitätsmaske erfordert. Jede Routine kann KeSetSystemAffinityThreadEx aufrufen, um eine neue Affinitätsmaske festzulegen, und dann KeRevertToUserAffinityThreadEx aufrufen, um die vorherige Affinitätsmaske wiederherzustellen, bevor sie zurückgegeben wird.

Die KeSetSystemAffinityThreadEx-Routine ändert die Affinitätsmaske des aktuellen Threads nur dann in den Affinitätswert , wenn beides zutrifft:

  • Der Affinitätswert ist gültig (das heißt, es werden nur Maskenbits festgelegt, die logischen Prozessoren entsprechen).
  • Mindestens einer der Prozessoren, der im Affinitätswert angegeben ist, ist aktiv.
Wenn eine dieser Bedingungen nicht erfüllt ist, hat der Aufruf von KeSetSystemAffinityThreadEx keine Auswirkung.

Windows 7 und höhere Versionen von Windows unterstützen Prozessorgruppen. Treiber, die für die Verarbeitung von Informationen zu Prozessorgruppen konzipiert sind, sollten die KeSetSystemGroupAffinityThread-Routine verwenden, die eine Prozessorgruppe angibt, anstelle von KeSetSystemAffinityThreadEx, was nicht der Fall ist. Die Implementierung von KeSetSystemAffinityThreadEx in Windows 7 und höheren Versionen von Windows bietet jedoch Kompatibilität für Treiber, die für frühere Versionen von Windows geschrieben wurden, die keine Prozessorgruppen unterstützen. In dieser Implementierung weist KeSetSystemAffinityThreadEx den Thread der Gruppe 0 zu und verwendet die Affinitätsmaske, um einen Satz logischer Prozessoren in dieser Gruppe anzugeben, für die der Thread ausgeführt werden kann. Die Routine gibt die vorherige gruppenrelative Affinitätsmaske zurück, aber nicht die vorherige Gruppe.

Wenn KeSetSystemAffinityThreadEx unter IRQL <= APC_LEVEL aufgerufen wird und der Aufruf erfolgreich ist, wird die neue Affinitätsmaske sofort wirksam. Wenn der Aufruf zurückgegeben wird, wird der aufrufende Thread bereits auf einem Prozessor ausgeführt, der in der neuen Affinitätsmaske angegeben ist. Wenn KeSetSystemAffinityThreadEx unter IRQL = DISPATCH_LEVEL aufgerufen wird und der Aufruf erfolgreich ist, wird die ausstehende Prozessoränderung zurückgestellt, bis der Aufrufer den IRQL unter DISPATCH_LEVEL senkt.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Windows Vista und späteren Windows-Versionen.
Zielplattform Universell
Header wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL (siehe Abschnitt Hinweise).

Weitere Informationen

KAFFINITY

KeRevertToUserAffinityThreadEx

KeSetSystemAffinityThread

KeSetSystemGroupAffinityThread