KeRegisterProcessorChangeCallback-Funktion (wdm.h)

Die KeRegisterProcessorChangeCallback-Routine registriert eine Rückruffunktion beim Betriebssystem, sodass das Betriebssystem den Treiber benachrichtigt, wenn der Hardwarepartition ein neuer Prozessor hinzugefügt wird.

Syntax

PVOID KeRegisterProcessorChangeCallback(
  [in]           PPROCESSOR_CALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID                        CallbackContext,
  [in]           ULONG                        Flags
);

Parameter

[in] CallbackFunction

Ein Zeiger auf eine vom Treiber bereitgestellte Prozessoränderungsrückruffunktion, die vom Betriebssystem aufgerufen werden soll, wenn der Hardwarepartition ein neuer Prozessor hinzugefügt wird. Eine Prozessoränderungsrückruffunktion ist wie folgt definiert:

VOID
  ProcessorCallback(
    __in PVOID CallbackContext,
    __in PKE_PROCESSOR_CHANGE_NOTIFY_CONTEXT ChangeContext,
    __inout PNTSTATUS OperationStatus
    );

CallbackContext

Der Kontext, der im Parameter CallbackContext für die KeRegisterProcessorChangeCallback-Routine bereitgestellt wurde, als die Rückruffunktion beim Betriebssystem registriert wurde.

ChangeContext

Ein Zeiger auf eine KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT Struktur, die das Änderungsbenachrichtigungsereignis des Prozessors beschreibt.

OperationStatus

Ein Zeiger auf eine Variable, die einen NTSTATUS-Code enthält. Ein Gerätetreiber darf den Wert dieser Variablen nicht ändern, es sei denn, während der Verarbeitung der Rückruffunktion tritt ein Fehler auf, wenn der State-Member der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT Struktur, auf die vom ChangeContext-Parameter verwiesen wird, KeProcessorAddStartNotify enthält.

Die Prozessoränderungsrückruffunktion wird unter IRQL = PASSIVE_LEVEL aufgerufen.

[in, optional] CallbackContext

Ein vom Treiber bereitgestellter Kontext, der an die Rückruffunktion übergeben wird. Dieser Parameter kann NULL sein.

[in] Flags

Optionale Flags, die das Verhalten der KeRegisterProcessorChangeCallback-Routine ändern. Im Folgenden ist ein mögliches Flag aufgeführt:

KE_PROCESSOR_CHANGE_ADD_EXISTING

Wenn dieses Flag festgelegt ist, wird die registrierte Rückruffunktion sofort für jeden aktiven Prozessor aufgerufen, der derzeit in der Hardwarepartition vorhanden ist. Außerdem wird aufgerufen, wenn der Hardwarepartition ein neuer Prozessor hinzugefügt wird. Wenn dieses Flag nicht festgelegt ist, wird die registrierte Rückruffunktion nur aufgerufen, wenn dem System ein neuer Prozessor hinzugefügt wird.

Rückgabewert

KeRegisterProcessorChangeCallback gibt ein Rückrufregistrierungshandle ungleich NULL zurück, wenn die Rückruffunktion erfolgreich beim Betriebssystem registriert wurde. Andernfalls gibt KeRegisterProcessorChangeCallbackNULL zurück. Weitere Informationen zu diesem Handle finden Sie im folgenden Abschnitt "Hinweise".

Hinweise

Ein Gerätetreiber ruft die KeRegisterProcessorChangeCallback-Routine auf, um eine Rückruffunktion zu registrieren, die vom Betriebssystem aufgerufen werden soll, wenn der Hardwarepartition ein neuer Prozessor hinzugefügt wird. Wenn ein Benutzer einen neuen Prozessor in die Partition einsteckt, ruft das Betriebssystem die registrierten Rückruffunktionen auf, um die Systemressourcen neu auszugleichen, die den Prozessoren in der Partition zugeordnet sind.

Die registrierte Rückruffunktion wird zweimal aufgerufen, wenn der Hardwarepartition ein neuer Prozessor hinzugefügt wird. Wenn die Rückruffunktion zum ersten Mal aufgerufen wird, enthält der State-Member der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT-Struktur , auf die der ChangeContext-Parameter verweist, KeProcessorAddStartNotify. Während dieses Rückrufs sollte der Gerätetreiber alle Prozessorressourcen zuordnen und alle anderen Aufgaben ausführen, damit der neue Prozessor in der Hardwarepartition aktiv wird. Wenn ein Fehler auftritt, während der Gerätetreiber diesen Rückruf verarbeitet, der zu einer Fehlerüberprüfung führen kann, wenn das Betriebssystem den neuen Prozessor weiterhin zur Hardwarepartition hinzugibt, legt die Rückruffunktion die Variable, auf die der Parameter OperationStatus verweist, auf einen NTSTATUS-Code fest, der die Fehlerbedingung beschreibt. Wenn der Gerätetreiber beispielsweise einen Speicherbelegungsfehler für eine Prozessordatenstruktur pro Prozessor für einen neuen Prozessor auftritt, legt die Rückruffunktion diese Variable auf STATUS_INSUFFICIENT_RESOURCES fest. Wenn der Rückruf erfolgreich verarbeitet wurde, sollte der Inhalt der Variablen, auf die vom Parameter OperationStatus verwiesen wird, nicht geändert werden.

Beim zweiten Aufruf der Rückruffunktion enthält der State-Member der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT-Struktur , auf die der ChangeContext-Parameter verweist, entweder KeProcessorAddCompleteNotify, was angibt, dass das Betriebssystem den neuen Prozessor erfolgreich zur Hardwarepartition hinzugefügt hat, oder KeProcessorAddFailureNotify., was angibt, dass das Betriebssystem den neuen Prozessor nicht zur Hardwarepartition hinzugefügt hat. Wenn das Betriebssystem den neuen Prozessor erfolgreich zur Hardwarepartition hinzufügt, wird die Rückruffunktion erst zum zweiten Mal aufgerufen, nachdem der neue Prozessor gestartet wurde und für die Threadplanung verfügbar ist. Wenn das Betriebssystem den neuen Prozessor nicht zur Hardwarepartition hinzugefügt hat, sollte der Gerätetreiber während des zweiten Rückrufs, den er während des ersten Rückrufs zugeordnet hat, alle Pro-Prozessor-Ressourcen freigeben.

Wenn der Gerätetreiber beim Aufrufen der KeRegisterProcessorChangeCallback-Routine das flag KE_PROCESSOR_CHANGE_ADD_EXISTING im Flags-Parameter angibt, wird die Rückruffunktion sofort einmal für jeden aktiven Prozessor aufgerufen, der derzeit in der Hardwarepartition vorhanden ist. Für diese Rückrufe enthält der State-Member der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT-Struktur , auf die der ChangeContext-Parameter verweist , KeProcessorAddStartNotify. Während dieser Rückrufe sollte der Gerätetreiber alle Prozessorressourcen zuordnen und alle anderen Aufgaben ausführen, um die Verwendung der vorhandenen Prozessoren in der Hardwarepartition vorzubereiten. Wenn der Gerätetreiber diesen Rückruf erfolgreich für alle aktiven Prozessoren verarbeitet, die derzeit in der Hardwarepartition vorhanden sind, wird die Rückruffunktion sofort wieder für jeden aktiven Prozessor aufgerufen, der derzeit in der Hardwarepartition vorhanden ist. Für diese Rückrufe enthält der State-Member der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT-Struktur , auf die der ChangeContext-Parameter verweist , KeProcessorAddCompleteNotify. KeRegisterProcessorChangeCallback gibt nach Abschluss dieser Rückrufe zurück.

Wenn ein Fehler auftritt, während der Gerätetreiber den ersten Rückruf für einen der vorhandenen aktiven Prozessoren in der Hardwarepartition verarbeitet, der zu einer Fehlerüberprüfung führen kann, wenn der Treiber weiterhin geladen werden soll, legt die Rückruffunktion die Variable, auf die der Parameter OperationStatus verweist, auf einen NTSTATUS-Code fest, der die Fehlerbedingung beschreibt. Wenn der Gerätetreiber beispielsweise einen Speicherbelegungsfehler für eine Prozessordatenstruktur pro Prozessor für einen vorhandenen aktiven Prozessor auftritt, legt die Rückruffunktion diese Variable auf STATUS_INSUFFICIENT_RESOURCES fest. Wenn der Rückruf erfolgreich verarbeitet wurde, sollte der Inhalt der Variablen, auf die vom Parameter OperationStatus verwiesen wird, nicht geändert werden.

Wenn der Gerätetreiber einen Fehler anzeigt, wenn der erste Rückruf für einen der vorhandenen aktiven Prozessoren in der Hardwarepartition verarbeitet wird, wird die Rückruffunktion für keine weiteren aktiven Prozessoren aufgerufen. Stattdessen wird die Rückruffunktion sofort ein zweites Mal für jeden aktiven Prozessor aufgerufen, für den der Rückruf zum ersten Mal aufgerufen wurde, mit Ausnahme des aktiven Prozessors, für den der Rückruf den Fehler angegeben hat. Für diese Rückrufe enthält der State-Member der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT-Struktur , auf die der ChangeContext-Parameter verweist , KeProcessorAddFailureNotify.

Ein Gerätetreiber ruft in der Regel die KeRegisterProcessorChangeCallback-Routine aus seiner DriverEntry-Routine auf. Wenn der Aufruf der KeRegisterProcessorChangeCallback-RoutineNULL zurückgibt, sollte die DriverEntry-Routine des Gerätetreibers einen NTSTATUS-Code zurückgeben, der die Fehlerbedingung beschreibt.

Ein Gerätetreiber kann den Kontext, der im CallbackContext-Parameter an die KeRegisterProcessorChangeCallback-Routine übergeben wird, als Ort verwenden, an dem die Rückruffunktion den NTSTATUS-Code speichern kann, der die Fehlerbedingung beschreibt. Dieser NTSTATUS-Code kann dann als Rückgabewert für die DriverEntry-Routine des Gerätetreibers verwendet werden.

Der status Wert, der von KeRegisterProcessorChangeCallback zurückgegeben wird, gibt nur an, ob die Registrierung der Rückruffunktion erfolgreich ist oder fehlschlägt. Er gibt nicht den Erfolg oder Fehler von Rückruffunktionen an, die vor der Rückgabe von KeRegisterProcessorChangeCallback auftreten können.

Eine Rückruffunktion, die für die Benachrichtigung über Prozessoränderungen registriert wurde, muss die Registrierung aufgehoben werden, bevor der Gerätetreiber vom Betriebssystem entladen wird. Um die Registrierung der Rückruffunktion aufzuheben, ruft der Gerätetreiber die KeDeregisterProcessorChangeCallback-Routine auf und übergibt als Eingabeparameter an diese Routine das Registrierungshandle, das vom Aufruf der KeRegisterProcessorChangeCallback-Routine zurückgegeben wurde.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Weitere Informationen

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback