KeRegisterProcessorChangeCallback, fonction (wdm.h)

La routine KeRegisterProcessorChangeCallback inscrit une fonction de rappel auprès du système d’exploitation afin que le système d’exploitation notifie le pilote lorsqu’un nouveau processeur est ajouté à la partition matérielle.

Syntaxe

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

Paramètres

[in] CallbackFunction

Pointeur vers une fonction de rappel de modification de processeur fournie par le pilote qui doit être appelée par le système d’exploitation chaque fois qu’un nouveau processeur est ajouté à la partition matérielle. Une fonction de rappel de modification du processeur est définie comme suit :

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

CallbackContext

Contexte fourni dans le paramètre CallbackContext à la routine KeRegisterProcessorChangeCallback lorsque la fonction de rappel a été inscrite auprès du système d’exploitation.

ChangeContext

Pointeur vers une structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT qui décrit l’événement de notification de modification du processeur.

OperationStatus

Pointeur vers une variable qui contient un code NTSTATUS. Un pilote de périphérique ne doit pas modifier la valeur de cette variable, sauf si une erreur se produit pendant le traitement de la fonction de rappel lorsque le membre d’état de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT pointée par le paramètre ChangeContext contient KeProcessorAddStartNotify.

La fonction de rappel de modification du processeur est appelée à IRQL = PASSIVE_LEVEL.

[in, optional] CallbackContext

Contexte fourni par le pilote passé à la fonction de rappel. Ce paramètre peut être NULL.

[in] Flags

Indicateurs facultatifs qui modifient le comportement de la routine KeRegisterProcessorChangeCallback . Voici un indicateur possible :

KE_PROCESSOR_CHANGE_ADD_EXISTING

Si cet indicateur est défini, la fonction de rappel inscrite est immédiatement appelée pour chaque processeur actif qui existe actuellement dans la partition matérielle, en plus d’être appelée chaque fois qu’un nouveau processeur est ajouté à la partition matérielle. Si cet indicateur n’est pas défini, la fonction de rappel inscrite est appelée uniquement chaque fois qu’un nouveau processeur est ajouté au système.

Valeur retournée

KeRegisterProcessorChangeCallback retourne un handle d’inscription de rappel non NULL si la fonction de rappel est correctement inscrite auprès du système d’exploitation. Sinon, KeRegisterProcessorChangeCallback retourne NULL. Pour plus d’informations sur ce handle, consultez la section Remarques suivante.

Notes

Un pilote de périphérique appelle la routine KeRegisterProcessorChangeCallback pour inscrire une fonction de rappel qui doit être appelée par le système d’exploitation chaque fois qu’un nouveau processeur est ajouté à la partition matérielle. Lorsqu’un utilisateur active un nouveau processeur dans la partition, le système d’exploitation appelle les fonctions de rappel inscrites pour rééquilibrer les ressources système allouées entre les processeurs de la partition.

La fonction de rappel inscrite est appelée deux fois chaque fois qu’un nouveau processeur est ajouté à la partition matérielle. La première fois que la fonction de rappel est appelée, le membre d’état de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT pointée par le paramètre ChangeContext contient KeProcessorAddStartNotify. Au cours de ce rappel, le pilote de périphérique doit allouer toutes les ressources par processeur et effectuer toutes les autres tâches en préparation du nouveau processeur pour qu’il devienne actif dans la partition matérielle. Si une erreur se produit pendant que le pilote de périphérique traite ce rappel qui peut provoquer une vérification de bogue si le système d’exploitation continue d’ajouter le nouveau processeur à la partition matérielle, la fonction de rappel définit la variable pointée par le paramètre OperationStatus à un code NTSTATUS qui décrit la condition d’erreur. Par exemple, si le pilote de périphérique rencontre un échec d’allocation de mémoire pour une structure de données par processeur pour un nouveau processeur, la fonction de rappel définit cette variable sur STATUS_INSUFFICIENT_RESOURCES. Si le rappel est traité avec succès, le contenu de la variable pointée par le paramètre OperationStatus ne doit pas être modifié.

La deuxième fois que la fonction de rappel est appelée, le membre d’État de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT pointée par le paramètre ChangeContext contient KeProcessorAddCompleteNotify, ce qui indique que le système d’exploitation a ajouté le nouveau processeur à la partition matérielle correctement, ou KeProcessorAddFailureNotify , qui indique que le système d’exploitation n’a pas ajouté le nouveau processeur à la partition matérielle. Si le système d’exploitation ajoute correctement le nouveau processeur à la partition matérielle, la fonction de rappel n’est pas appelée la deuxième fois avant le démarrage du nouveau processeur et est disponible pour la planification des threads. Si le système d’exploitation n’a pas ajouté le nouveau processeur à la partition matérielle, le pilote de périphérique doit libérer toutes les ressources par processeur pendant le deuxième rappel qu’il a alloué lors du premier rappel.

Si le pilote de périphérique spécifie l’indicateur KE_PROCESSOR_CHANGE_ADD_EXISTING dans le paramètre Flags lorsqu’il appelle la routine KeRegisterProcessorChangeCallback , la fonction de rappel est immédiatement appelée une fois pour chaque processeur actif qui existe actuellement dans la partition matérielle. Pour ces rappels, le membre d’État de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT pointée par le paramètre ChangeContext contient KeProcessorAddStartNotify. Au cours de ces rappels, le pilote de périphérique doit allouer toutes les ressources par processeur et effectuer d’autres tâches pour préparer l’utilisation des processeurs existants dans la partition matérielle. Si le pilote de périphérique traite correctement ce rappel pour tous les processeurs actifs qui existent actuellement dans la partition matérielle, la fonction de rappel est immédiatement appelée à nouveau pour chaque processeur actif qui existe actuellement dans la partition matérielle. Pour ces rappels, le membre d’État de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT pointée par le paramètre ChangeContext contient KeProcessorAddCompleteNotify. KeRegisterProcessorChangeCallback retourne une fois ces rappels terminés.

Si une erreur se produit pendant que le pilote de périphérique traite le premier rappel pour l’un des processeurs actifs existants dans la partition matérielle qui pourrait entraîner une vérification de bogue si le pilote devait continuer à charger, la fonction de rappel définit la variable pointée par le paramètre OperationStatus sur un code NTSTATUS qui décrit la condition d’erreur. Par exemple, si le pilote de périphérique rencontre un échec d’allocation de mémoire pour une structure de données par processeur pour un processeur actif existant, la fonction de rappel définit cette variable sur STATUS_INSUFFICIENT_RESOURCES. Si le rappel est traité avec succès, le contenu de la variable pointée par le paramètre OperationStatus ne doit pas être modifié.

Si le pilote de périphérique indique une erreur lorsque le premier rappel de l’un des processeurs actifs existants dans la partition matérielle est traité, la fonction de rappel n’est pas appelée pour plus de processeurs actifs existants. Au lieu de cela, la fonction de rappel est immédiatement appelée une seconde fois pour chaque processeur actif pour lequel le rappel a été appelé la première fois, à l’exclusion du processeur actif pour lequel le rappel a indiqué l’erreur. Pour ces rappels, le membre de l’État de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT pointée par le paramètre ChangeContext contient KeProcessorAddFailureNotify.

Un pilote de périphérique appelle généralement la routine KeRegisterProcessorChangeCallback à partir de sa routine DriverEntry . Si l’appel à la routine KeRegisterProcessorChangeCallback retourne NULL, la routine DriverEntry du pilote de périphérique doit retourner un code NTSTATUS qui décrit la condition d’erreur.

Note Un pilote de périphérique peut utiliser le contexte passé dans le paramètre CallbackContext à la routine KeRegisterProcessorChangeCallback comme emplacement où la fonction de rappel peut stocker le code NTSTATUS qui décrit la condition d’erreur. Ce code NTSTATUS peut ensuite être utilisé comme valeur de retour pour la routine DriverEntry du pilote de périphérique.
 
Note La valeur d’état retournée par KeRegisterProcessorChangeCallback indique uniquement si l’inscription de la fonction de rappel réussit ou échoue. Il n’indique pas la réussite ou l’échec des appels aux fonctions de rappel susceptibles de se produire avant que KeRegisterProcessorChangeCallback ne retourne.
 
Une fonction de rappel inscrite pour la notification des modifications du processeur doit être annulée avant que le pilote de périphérique ne soit déchargé du système d’exploitation. Pour annuler l’inscription de la fonction de rappel, le pilote de périphérique appelle la routine KeDeregisterProcessorChangeCallback et passe, en tant que paramètre d’entrée à cette routine, le handle d’inscription retourné par l’appel à la routine KeRegisterProcessorChangeCallback .

Spécifications

   
Client minimal pris en charge Disponible dans Windows Server 2008 et versions ultérieures de Windows.
Plateforme cible Universal
En-tête wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

Voir aussi

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback