PO_FX_COMPONENT_IDLE_STATE_CALLBACK fonction de rappel (wdm.h)

Article
02/29/2024

La routine de rappel ComponentIdleStateCallback avertit le pilote d’une modification en attente de l’état d’alimentation Fx du composant spécifié.

Syntaxe

PO_FX_COMPONENT_IDLE_STATE_CALLBACK PoFxComponentIdleStateCallback;

void PoFxComponentIdleStateCallback(
  [in] PVOID Context,
  [in] ULONG Component,
  [in] ULONG State
)
{...}

Paramètres

[in] Context

Pointeur vers le contexte de l’appareil. Le pilote de périphérique utilise ce contexte pour stocker des informations sur l’état d’alimentation actuel de l’appareil. Le pilote de périphérique a spécifié ce pointeur dans le membre DeviceContext de la structure PO_FX_DEVICE utilisée par le pilote pour inscrire l’appareil auprès de l’infrastructure de gestion de l’alimentation (PoFx). Ce contexte est opaque à PoFx.

[in] Component

Spécifie le numéro de 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 Components contient N éléments, les index de composant vont de 0 à N-1.

[in] State

Spécifie le nouvel état d’alimentation Fx auquel le composant va changer. Si ce paramètre est égal à zéro, le nouvel état est F0 ; si ce paramètre est un, le nouvel état est F1 ; et ainsi de suite.

Valeur de retour

None

Remarques

Lorsque PoFx appelle la routine ComponentIdleStateCallback du pilote, le pilote peut avoir besoin de se préparer au changement d’état Fx en attente. Une fois les préparations nécessaires terminées, le pilote doit appeler la routine PoFxCompleteIdleState pour informer PoFx que le pilote a terminé sa réponse au rappel ComponentIdleStateCallback . L’appel PoFxCompleteIdleState peut se produire avant ou après le retour de la routine ComponentIdleStateCallback .

Si le composant doit passer de F0 à un état Fx de faible consommation dans lequel l’appareil perd l’état matériel du composant, le pilote doit enregistrer l’état matériel du composant avant que la transition vers le nouvel état Fx se produise. Si le composant doit passer d’un état Fx de faible consommation à F0 et que l’état du matériel a été précédemment enregistré, le pilote doit restaurer l’état du matériel après la restauration de l’alimentation du composant.

Pour certains appareils, l’état d’alimentation d’un composant peut être contrôlé dans le matériel de l’appareil. Pour ces appareils, le pilote est généralement chargé de modifier l’état d’alimentation du composant. Pour d’autres appareils, l’état d’alimentation d’un composant peut être contrôlé par du matériel externe à l’appareil, et le pilote doit généralement s’appuyer sur PoFx pour configurer l’état d’alimentation du composant.

Si le pilote est responsable de la configuration de l’état d’alimentation du composant, il doit modifier l’état d’alimentation en réponse au rappel ComponentIdleStateCallback . Pour une transition de F0 à un état Fx de faible consommation, le composant est dans F0 lors de l’entrée dans la routine ComponentIdleStateCallback , et le pilote doit basculer le nouveau état Fx du composant avant d’appeler PoFxCompleteIdleState. Pour passer d’un état Fx de faible puissance à F0, le composant est à l’état Fx de faible puissance lors de l’entrée dans la routine ComponentIdleStateCallback , et le pilote doit basculer le composant vers F0 avant d’appeler PoFxCompleteIdleState.

Si le pilote n’est pas responsable de la configuration de l’état d’alimentation du composant, il doit supposer que le composant est toujours dans l’état F0 lors de l’entrée dans la routine ComponentIdleStateCallback . Pour une transition en attente de F0 vers un état Fx de faible puissance, la transition vers le nouvel état Fx ne se produit qu’après que le pilote a appelé PoFxCompleteIdleState. Pour une transition d’un état Fx de faible puissance vers F0, la transition vers F0 se produit avant l’appel de la routine ComponentIdleStateCallback .

PoFx n’appelle jamais la routine ComponentIdleStateCallback pour passer directement d’un état Fx de faible puissance à un autre état Fx de faible puissance. Par exemple, PoFx peut avoir besoin de basculer un composant d’un état Fx basse consommation vers un autre en réponse à un appel à la routine PoFxSetComponentLatency, PoFxSetComponentResidency ou PoFxSetComponentWake . Dans ce cas, PoFx appelle d’abord la routine ComponentIdleStateCallback pour passer de l’ancien état Fx à F0, puis appelle la routine ComponentIdleStateCallback une deuxième fois pour passer de F0 au nouvel état Fx.

Exemples

Pour définir une routine de rappel ComponentIdleStateCallback , vous devez d’abord fournir une déclaration de fonction qui identifie le type de routine de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une routine de rappel ComponentIdleStateCallback nommée MyComponentIdleStateCallback, utilisez le type PO_FX_COMPONENT_IDLE_STATE_CALLBACK comme indiqué dans cet exemple de code :

PO_FX_COMPONENT_IDLE_STATE_CALLBACK MyComponentIdleStateCallback;

Ensuite, implémentez votre routine de rappel comme suit :

_Use_decl_annotations_
VOID
  MyComponentIdleStateCallback(
    PVOID Context,
    ULONG Component,
    ULONG State
    )
  {
      // Function body
  }

Le type de fonction PO_FX_COMPONENT_IDLE_STATE_CALLBACK est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation _Use_decl_annotations_ à votre définition de fonction. L’annotation _Use_decl_annotations_ garantit que les annotations appliquées au type de fonction PO_FX_COMPONENT_IDLE_STATE_CALLBACK dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur _Use_decl_annotations_, consultez Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans Windows 8 et versions ultérieures de Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (inclure Wudfwdm.h)
IRQL	Appelé à IRQL <= DISPATCH_LEVEL.