estrutura WDF_POWER_FRAMEWORK_SETTINGS (wdfdevice.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

A estrutura WDF_POWER_FRAMEWORK_SETTINGS descreve as configurações da PoFx (estrutura de gerenciamento de energia) para dispositivos de componente único.

Sintaxe

typedef struct _WDF_POWER_FRAMEWORK_SETTINGS {
  ULONG                                         Size;
  PFN_WDFDEVICE_WDM_POST_PO_FX_REGISTER_DEVICE  EvtDeviceWdmPostPoFxRegisterDevice;
  PFN_WDFDEVICE_WDM_PRE_PO_FX_UNREGISTER_DEVICE EvtDeviceWdmPrePoFxUnregisterDevice;
  PPO_FX_COMPONENT                              Component;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK    ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK      ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK          ComponentIdleStateCallback;
  PPO_FX_POWER_CONTROL_CALLBACK                 PowerControlCallback;
  PVOID                                         PoFxDeviceContext;
  ULONGLONG                                     PoFxDeviceFlags;
  WDF_TRI_STATE                                 DirectedPoFxEnabled;
} WDF_POWER_FRAMEWORK_SETTINGS, *PWDF_POWER_FRAMEWORK_SETTINGS;

Membros

Size

O tamanho, em bytes, dessa estrutura.

EvtDeviceWdmPostPoFxRegisterDevice

Um ponteiro para a função de retorno de chamada de evento EvtDeviceWdmPostPoFxRegisterDevice do driver ou NULL.

EvtDeviceWdmPrePoFxUnregisterDevice

Um ponteiro para a função de retorno de chamada de evento EvtDeviceWdmPrePoFxUnregisterDevice do driver ou NULL.

Component

Um ponteiro para uma estrutura PO_FX_COMPONENT que descreve o único componente no dispositivo de componente único ou NULL. Se NULL, KMDF usará como padrão o suporte a F0 somente para esse componente. Essa estrutura especifica o número e os atributos dos estados F aos quais o componente dá suporte, bem como o estado fx mais profundo do qual o componente pode despertar.

ComponentActiveConditionCallback

Um ponteiro para a rotina de retorno de chamada ComponentActiveConditionCallback do driver ou NULL. A PoFx (estrutura de gerenciamento de energia) chama essa função de retorno de chamada quando um componente fica ativo. Enquanto estiver na condição Ativo, é garantido que o componente esteja em F0.

ComponentIdleConditionCallback

Um ponteiro para a função de retorno de chamada ComponentIdleConditionCallback do driver ou NULL. PoFx chama essa função de retorno de chamada quando um componente fica ocioso. Enquanto estiver na condição Ociosa, o componente pode estar em qualquer estado F, incluindo F0.

ComponentIdleStateCallback

Um ponteiro para a função de retorno de chamada ComponentIdleStateCallback do driver ou NULL. PoFx chama essa função de retorno de chamada quando o estado F do componente é alterado.

PowerControlCallback

Um ponteiro para a função de retorno de chamada PowerControlCallback do driver cliente ou NULL. A PoFx chama essa rotina para passar uma solicitação de uma operação de controle de energia diretamente para o driver. Se o driver não der suporte a nenhum código de controle de energia, defina esse parâmetro como NULL.

PoFxDeviceContext

Um ponteiro de contexto que a estrutura fornece para ComponentActiveConditionCallback, ComponentIdleConditionCallback, ComponentIdleStateCallback e PowerControlCallback.

PoFxDeviceFlags

Um valor do tipo ULONGLONG que contém o OR bit a bit dos seguintes valores relacionados ao Directed Power Management Framework. Esse campo está disponível a partir do KMDF versão 1.33 e UMDF 2.33.

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

Quando o Power Framework Direcionado ("DFx") está habilitado em um dispositivo, normalmente os dispositivos filho também habilitam o DFx. No entanto, em alguns casos (por exemplo, um dispositivo de software puro), um dispositivo filho não implementa o gerenciamento de energia. Defina esse sinalizador para permitir que esse dispositivo filho ignore o DFx.

Para definir esse sinalizador em nome de dispositivos filho, o driver do WDF pai deve:

Aceitar o DFx
Não ser motorista de ônibus
Ter pelo menos um dispositivo filho virtual criado por meio de um canal de banda lateral (por exemplo, um filtro superior ou dispositivo criado chamando SwDeviceCreate

Para drivers direcionados ao WDF pré-v33, especifique a diretiva INF: WdfDirectedPowerTransitionChildrenOptional, que está disponível a partir de Windows 10, versão 1903. Se o driver especificar a diretiva INF e definir esse sinalizador, a diretiva INF terá precedência.

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

Isso é necessário para implementar IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations entre dois dispositivos.

Por padrão, o WDF implementa o currículo rápido, o que significa que, durante a ativação do sistema, o proprietário da política de energia em uma pilha de dispositivos conclui um S0-IRP sem esperar para solicitar e concluir um D0-IRP. Isso não funciona bem com o PowerRelations.

Para que o PowerRelations funcione corretamente, se um dispositivo depender de outro dispositivo para inserir d0 primeiro, o segundo dispositivo deverá definir esse sinalizador para recusar a retomada rápida.

Em alguns casos, a política global pode desabilitar a retomada rápida globalmente, mesmo que esse sinalizador não esteja definido.

DirectedPoFxEnabled

Um enumerador do tipo WDF_TRI_STATE que indica se o dispositivo habilita o DFx (Directed Power Management Framework). Disponível a partir do KMDF versão 1.33 e UMDF 2.33.

WdfTrue – O DFx está habilitado. WdfFalse – O DFx está desabilitado. WdfUseDefault - O valor padrão se o driver não definir um. Esse valor tem o mesmo significado que WdfTrue.

O DFx (Directed PoFx) está disponível a partir de Windows 10, versão 1903 como uma opção para drivers que usam SystemManagedIdleTimeout ou SystemManagedIdleTimeoutWithHint.

Para um driver direcionado ao WDF pré-v31, defina a diretiva INF WdfDirectedPowerTransitionEnable como 1 para aceitar o DFx.
Para um driver que tem como destino o WDF v31+, o DFx é habilitado por padrão. O driver pode definir WdfDirectedPowerTransitionEnable como zero para recusar o DFx.
Para um driver direcionado para v33+ WDF, o DFx também está habilitado por padrão. O driver pode definir WdfDirectedPowerTransitionEnable como zero ou definir esse campo como WdfFalse (recomendado) para recusar o DFx. Se ambos estiverem definidos, a diretiva INF terá precedência.

Comentários

A estrutura WDF_POWER_FRAMEWORK_SETTINGS é usada como entrada para WdfDeviceWdmAssignPowerFrameworkSettings.

Para inicializar sua estrutura de WDF_POWER_FRAMEWORK_SETTINGS , o driver deve chamar WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Para UMDF, somente Size, PoFxDeviceFlags e DirectedPoFxEnabled são usados. Outros campos são ignorados e devem ser definidos como zero. A estrutura faz isso automaticamente quando um driver UMDF chama WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Para obter mais informações, consulte Suporte a estados de energia funcionais e Visão geral do Power Management Framework.

Essa estrutura não é aplicável aos drivers de cliente KMDF para dispositivos de vários componentes.