Fonction PoFxRegisterDevice (wdm.h)

Article
02/27/2024

La routine PoFxRegisterDevice inscrit un appareil auprès du framework de gestion de l’alimentation (PoFx).

Syntaxe

NTSTATUS PoFxRegisterDevice(
  [in]  PDEVICE_OBJECT Pdo,
  [in]  PPO_FX_DEVICE  Device,
  [out] POHANDLE       *Handle
);

Paramètres

[in] Pdo

Pointeur vers un objet d’appareil physique (PDO). Ce paramètre pointe vers une structure DEVICE_OBJECT qui représente l’appareil physique inscrit. L’appelant est le propriétaire de la stratégie d’alimentation de l’appareil, qui est généralement le pilote de fonction de l’appareil.

[in] Device

Pointeur vers une structure de PO_FX_DEVICE allouée à l’appelant qui contient les informations d’inscription de l’appareil. Cette structure contient des pointeurs vers un ensemble de routines de rappel implémentées par le pilote de périphérique. PoFx appelle ces routines pour communiquer avec le pilote.

[out] Handle

Pointeur vers un emplacement dans lequel la routine écrit un handle qui représente l’inscription de l’appareil auprès de PoFx. Le pilote de périphérique transmet ce handle en tant que paramètre d’entrée aux autres routines PoFxXxx qu’il appelle. Le pilote doit d’abord appeler PoFxRegisterDevice pour inscrire l’appareil avant que le pilote appelle d’autres routines PoFxXxx pour gérer l’appareil sous tension.

Valeur retournée

PoFxRegisterDevice retourne STATUS_SUCCESS si la routine enregistre correctement l’appareil. Les valeurs de retour d’erreur possibles incluent les codes status suivants.

Code de retour	Description
STATUS_INVALID_PARAMETER	Pdo a la valeur NULL ; ou la structure PPO_FX_DEVICE a un numéro de version non valide ou un nombre de composants de zéro ; ou le nombre d’états inactifs spécifiés pour un composant est égal à zéro ; ou la description d’un état inactif n’est pas valide.
STATUS_DEVICE_NOT_READY	Le périphérique n’est pas prêt.
STATUS_INSUFFICIENT_RESOURCES	Les ressources disponibles sont insuffisantes pour terminer l’inscription.

Remarques

Un pilote de périphérique appelle généralement cette routine à partir du gestionnaire de requêtes IRP_MN_START_DEVICE du pilote. Le pilote ne doit pas appeler cette routine avant que l’appareil reçoive une demande de IRP_MN_START_DEVICE . L’appareil reçoit la première IRP_MN_START_DEVICE demande lorsque l’appareil est démarré pour la première fois. L’appareil reçoit une demande de IRP_MN_START_DEVICE supplémentaire chaque fois que l’appareil est redémarré après avoir été arrêté pour l’équilibrage des ressources. Un appel PoFxRegisterDevice pour inscrire un appareil déjà inscrit est une erreur irrécupérable et provoque un bogue case activée. Notez que PoFx effectue une copie approfondie des structures de l’appareil dans sa mémoire.

Avant que le pilote appelle PoFxRegisterDevice, l’appareil doit remplir les conditions suivantes :

L’appareil (autrement dit, le PDO) n’est pas déjà inscrit auprès de PoFx.
L’appareil est à l’état d’alimentation D0 (entièrement activé).
L’appareil est en état d’exécution.
Chaque composant de l’appareil est à l’état d’alimentation F0 (entièrement activé).
Chaque composant est dans la condition active.

En inscrivant l’appareil auprès de PoFx, le pilote assume la responsabilité d’informer PoFx lorsqu’un composant est activement utilisé et quand le composant est inactif. Lorsque l’appareil est inscrit, le pilote doit appeler la routine PoFxActivateComponent pour accéder aux registres matériels d’un composant, et le pilote doit appeler la routine PoFxIdleComponent pour avertir PoFx lorsque le pilote n’a plus besoin d’accéder au composant.

Une fois qu’un pilote appelle PoFxRegisterDevice pour inscrire un appareil auprès de PoFx, tous les composants de l’appareil sont entièrement activés et dans l’état actif afin que le pilote puisse terminer l’initialisation du matériel. Pour démarrer la gestion de l’alimentation active, le pilote doit appeler la routine PoFxStartDevicePowerManagement .

Par défaut, PoFxStartDevicePowerManagement bascule tous les composants vers la condition d’inactivité. Si le pilote nécessite qu’un composant soit en état actif immédiatement après le démarrage de la gestion de l’alimentation, il doit activer explicitement le composant en appelant la routine PoFxActivateComponent , et cet appel doit se produire après l’appel PoFxRegisterDevice , mais avant l’appel PoFxStartDevicePowerManagement .

En règle générale, le pilote KMDF (Kernel-Mode Driver Framework) pour un appareil à composant unique n’appelle pas PoFxRegisterDevice pour inscrire l’appareil auprès de PoFx. Au lieu de cela, ce pilote reçoit un handle d’inscription PoFx lorsque KMDF appelle la fonction de rappel EvtDeviceWdmPostPoFxRegisterDevice du pilote. Pour plus d’informations, consultez Prise en charge de plusieurs états d’alimentation fonctionnels pour les appareils Single-Component.

Pour plus d’informations sur la façon dont le pilote KMDF pour un appareil à plusieurs composants s’inscrit auprès de PoFx, consultez Prise en charge de plusieurs états d’alimentation fonctionnels pour les appareils Multiple-Component.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.
Plateforme cible	Universal
En-tête	wdm.h
Bibliothèque	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL