estrutura WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS (wdfdevice.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

A estrutura WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS contém informações fornecidas pelo driver sobre a capacidade de um dispositivo de ativar a si mesmo e ao sistema, quando ambos estão em um estado de baixa potência.

Sintaxe

typedef struct _WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS {
  ULONG                                 Size;
  DEVICE_POWER_STATE                    DxState;
  WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings;
  WDF_TRI_STATE                         Enabled;
  BOOLEAN                               ArmForWakeIfChildrenAreArmedForWake;
  BOOLEAN                               IndicateChildWakeOnParentWake;
} WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_WAKE_SETTINGS;

Membros

Size

O tamanho, em bytes, dessa estrutura.

DxState

Um enumerador de tipo DEVICE_POWER_STATE que identifica o estado de baixa energia do dispositivo que o dispositivo inserirá quando o estado de energia do sistema cair para um estado de baixa energia desativada. O valor de DxState não pode ser PowerDeviceD0. DEVICE_POWER_STATE valores são definidos em wdm.h.

UserControlOfWakeSettings

Um enumerador de tipo WDF_POWER_POLICY_SX_WAKE_USER_CONTROL que indica se os usuários têm a capacidade de modificar as configurações de ativação do dispositivo.

Enabled

Um enumerador de tipo WDF_TRI_STATE que indica se o dispositivo pode ativar o sistema (ou seja, restaurar o sistema para S0) quando o sistema estiver em um estado de baixa potência. Esse membro pode ter um dos seguintes valores:

WdfTrue - A ativação do sistema está habilitada.

WdfFalse - A ativação do sistema está desabilitada.

WdfUseDefault - A ativação do sistema é inicialmente habilitada por padrão; mas se o membro UserControlOfWakeSettings estiver definido como WakeAllowUserControl, a configuração do usuário ou o arquivo INF do driver substituirá o valor inicial.

Se o sistema estiver habilitado e o sistema estiver prestes a entrar em um estado de baixa potência, a estrutura chamará a função de retorno de chamada EvtDeviceArmWakeFromSx ou EvtDeviceArmWakeFromSxWithReason do driver antes que o dispositivo entre em um estado de baixa potência.

ArmForWakeIfChildrenAreArmedForWake

Um valor booliano que, se definido como TRUE, indica que a capacidade de um dispositivo pai de ativar a si mesmo e o sistema deve ser habilitado quando essa capacidade está habilitada para os dispositivos filho do dispositivo. Para obter mais informações, consulte a seção Comentários a seguir. Esse membro está disponível na versão 1.7 e versões posteriores do KMDF.

IndicateChildWakeOnParentWake

Um valor booliano que, se definido como TRUE, indica que a estrutura fornecerá status de ativação para dispositivos filho se um dispositivo pai detectar um sinal de ativação. Para obter mais informações, consulte a seção Comentários a seguir. Esse membro está disponível na versão 1.7 e versões posteriores do KMDF.

Comentários

A estrutura WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS é usada como entrada para WdfDeviceAssignSxWakeSettings.

Para inicializar sua estrutura de WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS , o driver deve chamar WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT.

Na primeira vez que um driver chama WdfDeviceAssignSxWakeSettings, as seguintes ações ocorrem:

A estrutura armazena os valores de todos os membros da estrutura WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS .
Se o membro UserControlOfWakeSettings estiver definido como WakeAllowUserControl e se o membro Enabled estiver definido como WdfUseDefault, a estrutura lerá o Registro para descobrir se o usuário habilitou a ativação do sistema.

Durante as chamadas subsequentes para WdfDeviceAssignSxWakeSettings, a estrutura não armazena o valor do membro UserControlOfWakeSettings . Em outras palavras, a estrutura executa as seguintes etapas na primeira vez que o driver chama WdfDeviceAssignSxWakeSettings , mas não durante chamadas posteriores:

Armazena o valor do membro UserControlOfWakeSettings .
Procura uma configuração de usuário no registro, se o valor do membro Enabled for WdfUseDefault.

As regras a seguir se aplicam ao valor especificado para o membro DxState :

O valor não pode ser PowerDeviceD0.
Se você especificar PowerDeviceMaximum, a estrutura usará o valor que o driver do barramento do dispositivo forneceu no membro DeviceWake de sua estrutura WDF_DEVICE_POWER_CAPABILITIES .
Não é possível especificar um estado de energia do dispositivo inferior ao estado de energia do dispositivo no membro DeviceWake da estrutura de WDF_DEVICE_POWER_CAPABILITIES do driver de barramento. (Em outras palavras, se o valor DeviceWake do driver de barramento for PowerDeviceD2, o valor DxState do driver de função não poderá ser PowerDeviceD3.)

Para obter informações sobre entradas do Registro que controlam os recursos de ativação de um dispositivo, consulte Controle de usuário do dispositivo ocioso e comportamento de ativação.

Se o dispositivo que a estrutura WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS descreve for um dispositivo pai, o driver para o dispositivo pai poderá usar os membros ArmForWakeIfChildrenAreArmedForWake e IndicateChildWakeOnParentWake da seguinte maneira:

Se o driver definir o membro ArmForWakeIfChildrenAreArmedForWake como TRUE, a estrutura chamará a função de retorno de chamada EvtDeviceArmWakeFromSx ou EvtDeviceArmWakeFromSxWithReason do driver quando a capacidade de ativação de um dispositivo filho estiver habilitada, mesmo que a capacidade de ativação do dispositivo pai não esteja habilitada.
Para reduzir o consumo de energia, talvez você não queira habilitar a capacidade de ativação do dispositivo, a menos que um dispositivo filho que também dê suporte a uma capacidade de ativação esteja conectado. Se o driver definir o membro ArmForWakeIfChildrenAreArmedForWake como TRUE, os valores do membro Enabled terão os seguintes significados:
- Se Habilitado for WdfFalse, a estrutura habilitará a capacidade de ativação do driver somente se a capacidade de ativação de um dispositivo filho estiver habilitada.
- Se Habilitado for WdfTrue, a estrutura sempre habilitará a capacidade de ativação do driver, quer seu dispositivo tenha dispositivos filho habilitados para ativação ou não.
- Se Enabled for WdfUseDefault e UserControlOfWakeSettings for WakeAllowUserControl, os usuários poderão controlar se o dispositivo está sempre habilitado para ativação ou se ele está habilitado para ativação somente quando seu dispositivo tem dispositivos filho habilitados para ativação.
Se o driver definir o membro IndicateChildWakeOnParentWake como TRUE, a estrutura chamará a função de retorno de chamada EvtDeviceWakeFromSxTriggered no driver do dispositivo pai e no driver para cada dispositivo filho habilitado para ativação. Se o driver definir esse membro como FALSE, a estrutura chamará a função de retorno de chamada EvtDeviceWakeFromSxTriggered somente no driver do dispositivo pai. O driver deve definir IndicateChildWakeOnParentWake como TRUE se os drivers para os filhos do dispositivo precisarem examinar o hardware para determinar por que o sistema foi despertado.