Fonction PoFxRegisterComponentPerfStates (wdm.h)

Article
08/08/2023

La routine PoFxRegisterComponentPerfStates inscrit un composant d’appareil pour la gestion de l’état des performances par l’infrastructure de gestion de l’alimentation (PoFx).

Syntaxe

NTSTATUS PoFxRegisterComponentPerfStates(
  [in]  POHANDLE                             Handle,
  [in]  ULONG                                Component,
  [in]  ULONGLONG                            Flags,
  [in]  PPO_FX_COMPONENT_PERF_STATE_CALLBACK ComponentPerfStateCallback,
  [in]  PPO_FX_COMPONENT_PERF_INFO           InputStateInfo,
  [out] PPO_FX_COMPONENT_PERF_INFO           *OutputStateInfo
);

Paramètres

[in] Handle

Handle qui représente l’inscription de l’appareil auprès de 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 dont les états de performances seront gérés. 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 qui modifient le comportement de l’inscription de l’état des performances. Définissez ce membre sur zéro ou sur l’un des indicateurs suivants PO_FX_FLAG_PERF_ bitsXXX :

Valeur	Signification
PO_FX_FLAG_PERF_PEP_OPTIONAL 0x1	Indique que le pilote peut modifier les états de performances sans l’aide du plug-in d’extension de plateforme (PEP) ou que le pilote enregistre des états de performances auprès de PoFx uniquement à des fins de journalisation. Si cet indicateur est défini, l’appel PoFxRegisterComponentPerfStates réussit toujours si le PEP ne prend pas en charge les états de performances du composant.
PO_FX_FLAG_PERF_QUERY_ON_F0 0x2	Pour certains appareils, le PEP peut avoir besoin de placer un état de performances défini pour un composant dans un certain état de performances (connu sous le nom d’état de performances nominales) lorsqu’il inactif le composant. Les pilotes définissent cet indicateur si le composant contient des états de performances nominales, auquel cas PoFx interroge le PEP pour déterminer l’état actuel des performances lorsque le composant passe à F0.
PO_FX_FLAG_PERF_QUERY_ON_ALL_IDLE_STATES 0x4	Pour certains appareils, le PEP peut avoir besoin de placer un jeu d’état de performances pour un composant dans un certain état de performances (connu sous le nom d’état de performances nominales) lorsqu’il effectue la transition du composant entre des états inactifs. Les pilotes définissent cet indicateur si ce composant contient des états de performances nominales, auquel cas PoFx interroge le PEP pour déterminer l’état actuel des performances lorsque le composant passe d’un état inactif à l’autre.

[in] ComponentPerfStateCallback

Pointeur vers une routine ComponentPerfStateCallback . Cette routine est appelée lorsque PoFx a terminé la journalisation et la notification au PEP d’une transition d’état des performances initiée par l’appel du pilote à PoFxIssueComponentPerfStateChange ou PoFxIssueComponentPerfStateChangeMultiple. Ce rappel peut être le même pour tous les composants et tous les appareils ; PoFx fournit le handle d’appareil et l’index de composant dans chaque appel d’achèvement.

[in] InputStateInfo

Si le pilote fournit des informations d’état des performances, ce paramètre contient un pointeur vers un pilote alloué PO_FX_COMPONENT_PERF_INFO structure qui fournit des informations d’état des performances à PoFx. Si le pilote requiert des informations d’état des performances du PEP, ce paramètre doit être défini sur NULL.

[out] OutputStateInfo

Si le pilote requiert des informations d’état des performances du PEP, après une inscription réussie, ce paramètre contient un pointeur vers une structure de PO_FX_COMPONENT_PERF_INFO qui fournit des informations d’état des performances définies par le PEP. Si le pilote fournit des informations sur l’état des performances, ce paramètre doit être défini sur NULL.

La mémoire allouée pour ce paramètre est gérée par PoFx, et le pilote ne doit pas libérer cette mémoire lorsque l’appareil est supprimé. La durée de vie de cette mémoire est garantie pour dépasser la durée de vie du composant PoFx qui contient ces jeux d’états de performances.

Valeur retournée

PoFxRegisterComponentPerfStates retourne STATUS_SUCCESS si PoFx accepte l’inscription des états de performances de l’appareil. Si l’une des informations nécessaires n’est pas fournie ou est incorrecte, l’inscription échoue avec un code de retour autre que STATUS_SUCCESS. Les valeurs de retour d’erreur possibles incluent les codes status suivants.

Code de retour	Description
STATUS_NOT_IMPLEMENTED	Le paramètre Flags n’inclut pas l’indicateur PO_FX_FLAG_PERF_PEP_OPTIONAL et le PEP n’est pas en mesure de fournir une gestion de l’état des performances pour cet appareil.
STATUS_INVALID_PARAMETER	InputStateInfo et OutputStateInfo ont la valeur NULL ou ces deux paramètres ne sont pas NULL, ou il n’existe aucun jeu d’état de performances dans la structure PO_FX_COMPONENT_PERF_INFO qui a été affectée au paramètre InputStateInfo.

Remarques

Notez que PoFx effectue une copie approfondie des structures de l’appareil dans sa mémoire.

Le pilote ou le plug-in d’extension de plateforme (PEP) peut fournir des informations sur les états de performances pris en charge par chaque composant :

Si le pilote fournit des informations d’état des performances, il doit définir le paramètre InputStateInfo sur un pointeur vers une structure PO_FX_COMPONENT_PERF_INFO qui contient les informations d’état des performances. Sinon, le pilote doit définir ce paramètre sur NULL.
Si le PEP fournit des informations sur l’état des performances, le pilote doit définir le paramètre OutputStateInfo sur un pointeur valide vers une structure de PO_FX_COMPONENT_PERF_INFO qui reçoit les informations d’état des performances. Sinon, le pilote doit définir ce paramètre sur NULL.

Si le PEP ne prend pas en charge les états de performances, le pilote peut s’inscrire à la prise en charge de l’état des performances auprès de PoFx à des fins de journalisation uniquement.

Si le pilote s’inscrit à la prise en charge de l’état des performances à des fins de journalisation uniquement, ou si le pilote peut fonctionner correctement avec ou sans prise en charge PEP pour la gestion de l’état des performances, le pilote doit définir l’indicateur PO_FX_FLAG_PERF_PEP_OPTIONAL dans le paramètre Flags . Si l’indicateur est défini, l’appel d’inscription réussit même si le PEP ne prend pas en charge les états de performances.

Si le pilote exige que le PEP fournisse des informations d’état des performances, il ne peut pas définir l’indicateur PO_FX_FLAG_PERF_PEP_OPTIONAL dans le paramètre Flags .

Configuration requise

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

Voir aussi

ComponentPerfStateCallback

Gestion de l’état des performances des appareils

PO_FX_COMPONENT_PERF_INFO

PoFxRegisterDevice

Partager via