Fonction KeRegisterProcessorChangeCallback (wdm.h)

La routine KeRegisterProcessorChangeCallback inscrit une fonction de rappel auprès du système d’exploitation afin que le système d’exploitation informe 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 changement 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 State de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT pointée vers laquelle 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 qui est 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.

Remarques

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 branche à chaud 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 State de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT pointée par le paramètre ChangeContext contient KeProcessorAddStartNotify. C’est au cours de ce rappel que le pilote de périphérique doit allouer toutes les ressources par processeur et effectuer d’autres tâches en préparation pour que le nouveau processeur devienne actif dans la partition matérielle. Si une erreur se produit pendant que le pilote de périphérique traite ce rappel, ce qui peut entraîner 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 vers laquelle le paramètre OperationStatus pointe vers 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 State 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 correctement ajouté le nouveau processeur à la partition matérielle, ou KeProcessorAddFailureNotify, ce 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 a correctement ajouté le nouveau processeur à la partition matérielle, la fonction de rappel n’est appelée la deuxième fois qu’après 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 lors du 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 État de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT pointée par le paramètre ChangeContext contient KeProcessorAddStartNotify. C’est au cours de ces rappels que 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 pour chaque processeur actif qui existe actuellement dans la partition matérielle. Pour ces rappels, le membre State 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, ce qui peut 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 lors du traitement du premier rappel de l’un des processeurs actifs existants dans la partition matérielle, la fonction de rappel n’est pas appelée pour les processeurs actifs existants. Au lieu de cela, la fonction de rappel est immédiatement appelée une deuxième 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 d’État de la structure KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT vers laquelle pointe 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 renvoie NULL, la routine DriverEntry du pilote de périphérique doit retourner un code NTSTATUS qui décrit la condition d’erreur.

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.

La valeur status 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 qui peuvent se produire avant le retour de KeRegisterProcessorChangeCallback .

Une fonction de rappel qui a été inscrite pour la notification des modifications du processeur doit être désinscrire 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 .

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

Voir aussi

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeDeregisterProcessorChangeCallback