KeRegisterProcessorChangeCallback-Funktion (wdm.h)

Die KeRegisterProcessorChangeCallback-Routine registriert eine Rückruffunktion mit dem Betriebssystem, damit das Betriebssystem den Treiber benachrichtigt, wenn ein neuer Prozessor zur Hardwarepartition 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änderungsfunktion, die vom Betriebssystem aufgerufen werden soll, wenn ein neuer Prozessor der Hardwarepartition hinzugefügt wird. Eine Rückruffunktion des Prozessors wird wie folgt definiert:

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

CallbackContext

Der Kontext, der im CallbackContext-Parameter an die KeRegisterProcessorChangeCallback-Routine bereitgestellt wurde, wenn die Rückruffunktion mit dem 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 Variable nicht ändern, außer wenn während der Verarbeitung der Rückruffunktion ein Fehler auftritt, wenn der Mitgliedstaat der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT-Struktur , auf die der ChangeContext-Parameter verweist, KeProcessorAddStartNotify enthält.

Die Rückruffunktion des Prozessors wird bei 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. Das folgende ist ein mögliches Flag:

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, zusätzlich dazu, wenn ein neuer Prozessor der Hardwarepartition hinzugefügt wird. Wenn dieses Flag nicht festgelegt ist, wird die registrierte Rückruffunktion nur aufgerufen, wenn ein neuer Prozessor dem System hinzugefügt wird.

Rückgabewert

KeRegisterProcessorChangeCallback gibt einen Nicht-NULL-Rückrufregistrierungspunkt zurück, wenn die Rückruffunktion erfolgreich mit dem Betriebssystem registriert wird. Andernfalls gibt KeRegisterProcessorChangeCallbackNULL zurück. Weitere Informationen zu diesem Handle finden Sie im folgenden Abschnitt "Hinweise".

Bemerkungen

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

Die registrierte Rückruffunktion wird zweimal aufgerufen, wenn ein neuer Prozessor der Hardwarepartition hinzugefügt wird. Das erste Mal, wenn die Rückruffunktion aufgerufen wird, enthält das Mitgliedstaatmitglied der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT Struktur, auf die der ChangeContext-Parameter verweist, KeProcessorAddStartNotify. Während dieses Rückrufs sollte der Gerätetreiber jede Prozessorressourcen zuweisen und alle anderen Aufgaben ausführen, die für den neuen Prozessor vorbereitet werden, um in der Hardwarepartition aktiv zu werden. Wenn ein Fehler auftritt, während der Gerätetreiber diesen Rückruf verarbeitet, der zu einem Fehlercheck führen könnte, wenn das Betriebssystem weiterhin den neuen Prozessor zur Hardwarepartition hinzugibt, legt die Rückruffunktion die Variable fest, die vom OperationStatus-Parameter auf einen NTSTATUS-Code verweist, der die Fehlerbedingung beschreibt. Wenn der Gerätetreiber beispielsweise einen Speicherzuweisungsfehler für eine Datenstruktur pro Prozessor für einen neuen Prozessor aufweist, legt die Rückruffunktion diese Variable auf STATUS_INSUFFICIENT_RESOURCES fest. Wenn der Rückruf erfolgreich verarbeitet wird, sollte der Inhalt der Variable, auf die der OperationStatus-Parameter verweist, nicht geändert werden.

Das zweite Mal, wenn die Rückruffunktion aufgerufen wird, enthält das Mitgliedstaatmitglied der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT Struktur, auf die der ChangeContext-Parameter verweist, entweder KeProcessorAddCompleteNotify, was angibt, dass das Betriebssystem den neuen Prozessor zur Hardwarepartition erfolgreich 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 nach dem Start des neuen Prozessors aufgerufen und steht für die Threadplanung zur Verfügung. 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 zugewiesen hat, eine beliebige Prozessorressourcen freizugeben.

Wenn der Gerätetreiber das KE_PROCESSOR_CHANGE_ADD_EXISTING Flag im Flags-Parameter angibt, wenn er die KeRegisterProcessorChangeCallback-Routine aufruft, 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 Mitgliedstaat der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT Struktur, auf die der ChangeContext-Parameter verweist, KeProcessorAddStartNotify. Während dieser Rückrufe sollte der Gerätetreiber jede Prozessorressourcen zuweisen und alle anderen Aufgaben ausführen, um die vorhandenen Prozessoren in der Hardwarepartition zu verwenden. 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 für jeden aktiven Prozessor aufgerufen, der derzeit in der Hardwarepartition vorhanden ist. Für diese Rückrufe enthält der Mitgliedstaat 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 einem Fehlercheck führen könnte, wenn der Treiber weiterhin geladen werden soll, legt die Rückruffunktion die Variable fest, die vom OperationStatus-Parameter auf einen NTSTATUS-Code verweist, der die Fehlerbedingung beschreibt. Wenn der Gerätetreiber beispielsweise einen Speicherzuweisungsfehler für eine Datenstruktur pro Prozessor für einen vorhandenen aktiven Prozessor aufweist, legt die Rückruffunktion diese Variable auf STATUS_INSUFFICIENT_RESOURCES fest. Wenn der Rückruf erfolgreich verarbeitet wird, sollte der Inhalt der Variable, auf die der OperationStatus-Parameter verweist, nicht geändert werden.

Wenn der Gerätetreiber einen Fehler angibt, wenn der erste Rückruf für einen der vorhandenen aktiven Prozessoren in der Hardwarepartition verarbeitet wird, wird die Rückruffunktion nicht für mehr der vorhandenen aktiven Prozessoren aufgerufen. Stattdessen wird die Rückruffunktion sofort für jeden aktiven Prozessor aufgerufen, für den der Rückruf zum ersten Mal aufgerufen wurde, ohne den aktiven Prozessor, für den der Rückruf den Fehler angibt. Für diese Rückrufe enthält der Mitgliedstaat der KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT Struktur, auf die der ChangeContext-Parameter verweist, KeProcessorAddFailureNotify.

Ein Gerätetreiber ruft in der Regel die KeRegisterProcessorChangeCallback-Routine innerhalb 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.

Hinweis Ein Gerätetreiber kann den Kontext verwenden, der im CallbackContext-Parameter an die KeRegisterProcessorChangeCallback-Routine übergeben wird, als Ort, 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.
 
Hinweis Der statuswert, der von KeRegisterProcessorChangeCallback zurückgegeben wird, gibt nur an, ob die Registrierung der Rückruffunktion erfolgreich ist oder fehlschlägt. Es gibt nicht den Erfolg oder Fehler aller Aufrufe an Rückruffunktionen an, die auftreten können, bevor KeRegisterProcessorChangeCallback zurückgegeben wird.
 
Eine Rückruffunktion, die für die Benachrichtigung von Prozessoränderungen registriert wurde, muss nicht registriert werden, bevor der Gerätetreiber vom Betriebssystem geladen wird. Um die Registrierung der Rückruffunktion zu aufheben, ruft der Gerätetreiber die KeDeregisterProcessorChangeCallback-Routine auf und übergibt als Eingabeparameter an diese Routine den Registrierungshandpunkt, der vom Aufruf an die KeRegisterProcessorChangeCallback-Routine zurückgegeben wurde.

Requirements (Anforderungen)

   
Unterstützte Mindestversion (Client) Verfügbar in Windows Server 2008 und späteren Versionen von Windows.
Zielplattform Universell
Header wdm.h (enthalten Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

Weitere Informationen

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback