Fonction PoFxActivateComponent (wdm.h)

Article
08/08/2023

La routine PoFxActivateComponent incrémente le nombre de références d’activation sur le composant spécifié.

Syntaxe

void PoFxActivateComponent(
  [in] POHANDLE Handle,
  [in] ULONG    Component,
  [in] ULONG    Flags
);

Paramètres

[in] Handle

Handle qui représente l’inscription de l’appareil auprès de l’infrastructure de gestion de l’alimentation (PoFx). Le pilote de périphérique a déjà reçu ce handle de la routine PoFxRegisterDevice .

[in] Component

Index qui identifie le composant. Ce paramètre est un index dans le tableau Components de la structure PO_FX_DEVICE que le pilote de périphérique a utilisé pour inscrire l’appareil auprès de PoFx. Si le tableau Composants contient N éléments, les index des composants vont de 0 à N–1.

[in] Flags

Indicateurs de l’opération d’activation. Définissez ce membre sur zéro ou sur l’un des indicateurs suivants PO_FX_FLAG_ bitsXXX :

Ces deux bits d’indicateur s’excluent mutuellement. Pour plus d'informations, consultez la section Notes.

Valeur	Signification
PO_FX_FLAG_BLOCKING 0x1	Rendez la modification de condition synchrone. Si cet indicateur est défini, la routine qui demande la modification de condition ne retourne pas le contrôle au pilote appelant tant que le matériel du composant n’a pas terminé la transition vers la nouvelle condition. Cet indicateur ne peut être utilisé que si l’appelant est en cours d’exécution à l'< DISPATCH_LEVEL IRQL.
PO_FX_FLAG_ASYNC_ONLY 0x2	Rendez la modification de condition entièrement asynchrone. Si cet indicateur est défini, la routine de rappel du pilote appelant est appelée à partir d’un thread autre que le thread dans lequel la routine qui demande la modification de condition est appelée. Ainsi, la routine qui demande la modification de la condition retourne toujours de manière asynchrone sans attendre que le rappel se termine.

Valeur

Signification

PO_FX_FLAG_BLOCKING
0x1

Rendez la modification de condition synchrone. Si cet indicateur est défini, la routine qui demande la modification de condition ne retourne pas le contrôle au pilote appelant tant que le matériel du composant n’a pas terminé la transition vers la nouvelle condition. Cet indicateur ne peut être utilisé que si l’appelant est en cours d’exécution à l'< DISPATCH_LEVEL IRQL.

PO_FX_FLAG_ASYNC_ONLY
0x2

Rendez la modification de condition entièrement asynchrone. Si cet indicateur est défini, la routine de rappel du pilote appelant est appelée à partir d’un thread autre que le thread dans lequel la routine qui demande la modification de condition est appelée. Ainsi, la routine qui demande la modification de la condition retourne toujours de manière asynchrone sans attendre que le rappel se termine.

Valeur de retour

None

Remarques

Avant qu’un pilote de périphérique puisse accéder à un composant d’un appareil, celui-ci doit d’abord appeler PoFxActivateComponent pour obtenir une référence d’activation au composant. Si le composant n’est pas déjà dans l’état actif, cet appel lance une transition de la condition inactive à la condition active. Une fois cette transition terminée, PoFx appelle la routine ComponentActiveConditionCallback du pilote pour avertir le pilote. Le pilote peut accéder aux registres matériels dans un composant uniquement lorsque le composant est dans l’état actif.

Si le composant est déjà dans l’état actif lorsque PoFxActivateComponent est appelé, aucune transition n’est requise et la routine ComponentActiveConditionCallback n’est pas appelée.

Une fois qu’un composant a entré la condition active, il reste dans l’état actif tant que le pilote contient une ou plusieurs références d’activation sur le composant. Pour publier une référence d’activation, le pilote appelle la routine PoFxIdleComponent . Lorsque le pilote publie la dernière référence d’activation sur un composant, PoFxIdleComponent lance une transition de la condition active à la condition inactive. Un composant qui est en état d’inactivité peut potentiellement entrer dans un état Fx de faible puissance.

Si les = indicateurs PO_FX_FLAG_BLOCKING, l’appel PoFxActivateComponent est synchrone. Si le composant est déjà dans la condition active, l’appel incrémente le nombre de références d’activation et retourne sans attendre. Sinon, PoFxActivateComponent attend de revenir jusqu’à ce que le composant termine la transition vers la condition active. Dans ce cas, si le composant n’est pas déjà à l’état F0 lors de l’appel, PoFxActivateComponent appelle la routine ComponentIdleStateCallback du pilote pour lancer la transition vers F0. Une fois que le composant entre dans l’état F0, PoFxActivateComponent appelle la routine ComponentActiveConditionCallback du pilote pour informer le pilote que le composant est en état actif. Ces rappels se produisent dans le même thread que l’appel à PoFxActivateComponent, et PoFxActivateComponent retourne uniquement après le retour du rappel ComponentActiveConditionCallback .

Si les = indicateursPO_FX_FLAG_ASYNC_ONLY, l’appel PoFxActivateComponent est asynchrone. Si le composant est déjà dans la condition active, l’appel incrémente le nombre de références d’activation et retourne. Sinon, PoFxActivateComponent planifie les rappels ComponentIdleStateCallback (si nécessaire) et ComponentActiveConditionCallback pour qu’ils se produisent dans un autre thread, puis retourne sans attendre que l’un ou l’autre rappel se produise. Les rappels peuvent se produire avant ou après le retour de PoFxActivateComponent . Le pilote s’appuie sur le rappel ComponentActiveConditionCallback pour déterminer quand le composant termine la transition vers la condition active.

Le pilote peut définir Flags = 0 pour indiquer qu’il ne se soucie pas de savoir si l’appel PoFxActivateComponent est synchrone ou asynchrone. Dans ce cas, PoFx décide s’il faut rendre l’appel synchrone ou asynchrone.

Deux chemins de code ou plus dans le même pilote peuvent avoir besoin d’accéder simultanément à un composant particulier. Les routines PoFxActivateComponent et PoFxIdleComponent utilisent le nombre de références d’activation pour permettre aux différentes parties du pilote de maintenir indépendamment l’accès au composant sans nécessiter que le pilote gère de manière centralisée l’accès au composant.

PoFx gère un nombre de références d’activation pour chaque composant d’un appareil. Un appel PoFxActivateComponent incrémente ce nombre d’un, et un appel PoFxIdleComponent décrémente le nombre d’un. Lorsque le nombre est différent de zéro, le composant est en état actif ou est en train de basculer vers la condition active. Un composant dont le nombre est égal à zéro est en état d’inactivité ou est en cours de basculement vers la condition inactive.

Lorsqu’un appel PoFxActivateComponent fait passer le nombre de références d’activation de 0 à 1, PoFxActivateComponent initie une transition de la condition inactive à la condition active. Lorsqu’un appel PoFxIdleComponent entraîne la décrémentation du nombre de 1 à 0, PoFxIdleComponent initie une transition de la condition active à la condition inactive.

PoFx avertit le pilote lorsqu’une transition entre la condition active et la condition d’inactivité se produit. Un rappel ComponentActiveConditionCallback avertit le pilote d’une transition vers la condition active, et un rappel ComponentIdleConditionCallback avertit le pilote d’une transition vers la condition inactive. Lorsqu’un appel PoFxActivateComponent ou PoFxIdleComponent incrémente ou décrémente simplement le nombre de références d’activation sans provoquer une telle transition, le pilote ne reçoit aucune notification.

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	<= DISPATCH_LEVEL