estrutura WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS (wdfdevice.h)

[Aplica-se a KMDF e UMDF]

A estrutura WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS contém informações fornecidas pelo driver que a estrutura usa quando um dispositivo está ocioso e o sistema está no estado de trabalho do sistema (S0).

Sintaxe

typedef struct _WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS {
  ULONG                                 Size;
  WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps;
  DEVICE_POWER_STATE                    DxState;
  ULONG                                 IdleTimeout;
  WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings;
  WDF_TRI_STATE                         Enabled;
  WDF_TRI_STATE                         PowerUpIdleDeviceOnSystemWake;
  WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE    IdleTimeoutType;
  WDF_TRI_STATE                         ExcludeD3Cold;
} WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_IDLE_SETTINGS;

Membros

Size

O tamanho, em bytes, dessa estrutura.

IdleCaps

Um enumerador do tipo WDF_POWER_POLICY_S0_IDLE_CAPABILITIES que identifica a capacidade do dispositivo de se ativar depois de ser definido como um estado de baixa potência, enquanto o sistema permanece em seu estado de trabalho (S0).

DxState

Um enumerador do tipo DEVICE_POWER_STATE que identifica o estado de energia do dispositivo baixo que o dispositivo inserirá após o término do período de tempo limite ocioso. DEVICE_POWER_STATE valores são definidos em wdm.h.

IdleTimeout

A quantidade de tempo, em milissegundos, que o dispositivo permanecerá ocioso antes que a estrutura o coloque no estado de baixa energia fornecido pelo DxState. Para usar o valor de tempo limite ocioso padrão da estrutura, especifique IdleTimeoutDefaultValue. Para obter mais informações sobre quando a estrutura considera o dispositivo ocioso, consulte Suporte à ociosidade de energia para baixo.

UserControlOfIdleSettings

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

Enabled

Um enumerador do tipo WDF_TRI_STATE que indica se o dispositivo será desligado se permanecer ocioso e enquanto a energia do sistema estiver em S0. Esse membro pode ter um dos seguintes valores:

WdfTrue – a desligar está habilitada.

WdfFalse – a desligar está desabilitada.

WdfUseDefault – a desligar é inicialmente habilitada por padrão; mas se o membro UserControlOfIdleSettings estiver definido como IdleAllowUserControl, a configuração do usuário ou o arquivo INF do driver substituirá o valor inicial.

Se a ativação estiver habilitada, o dispositivo terá uma funcionalidade de ativação e o valor de tempo limite ocioso expirará, a estrutura chamará a função de retorno de chamada EvtDeviceArmWakeFromS0 do driver antes que o dispositivo entre em um estado de baixa potência.

PowerUpIdleDeviceOnSystemWake

Um enumerador do tipo WDF_TRI_STATE que indica se o dispositivo retornará ao estado de trabalho (D0) quando o sistema retornar ao estado de trabalho (S0). Esse membro só será válido se o driver definir o membro IdleCaps como IdleCannotWakeFromS0. O membro PowerUpIdleDeviceOnSystemWake pode ter um dos seguintes valores:

WdfTrue - Se o dispositivo e o sistema estiverem em um estado de baixa potência, o dispositivo retornará ao seu estado de trabalho quando o sistema retornar ao seu estado de trabalho.

WdfFalse – se o dispositivo e o sistema estiverem em um estado de baixa potência, o dispositivo permanecerá no estado de baixa potência quando o sistema retornar ao seu estado de trabalho.

WdfUseDefault - O valor padrão que a estrutura usa se o driver não definir um valor diferente. Esse valor tem o mesmo significado que WdfFalse.

Se o membro PowerUpIdleDeviceOnSystemWake estiver definido como WdfFalse ou WdfUseDefault, o dispositivo retornará ao seu estado de trabalho somente quando o software acessar o dispositivo, como quando um aplicativo envia uma solicitação de E/S para o dispositivo. Para obter mais informações, consulte Um dispositivo retorna ao seu estado de trabalho.

O membro PowerUpIdleDeviceOnSystemWake está disponível na versão 1.9 e versões posteriores do KMDF e a partir da versão 2.0 do UMDF.

IdleTimeoutType

Um enumerador do tipo WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE que indica como o membro IdleTimeout é usado.

O membro IdleTimeoutType está disponível na versão 1.11 e versões posteriores do KMDF e começando na versão 2.0 do UMDF. Consulte informações adicionais em Comentários.

ExcludeD3Cold

Um enumerador do tipo WDF_TRI_STATE que indica se o estado de energia D3cold deve ser uma opção permitida para o estado de baixa potência que o dispositivo inserirá quando o período de tempo limite ocioso expirar. O membro ExcludeD3Cold pode ter um dos seguintes valores:

WdfTrue – a estrutura moverá um dispositivo para um estado D de baixa potência quando o período de tempo limite ocioso expirar. Se esse estado D for D3, o dispositivo será movido para D3hot. Se ExcludeD3Cold estiver definido como WdfTrue, nenhuma transição adicional de D3hot para D3cold será permitida.

WdfFalse - O dispositivo pode inserir o estado de energia D3cold quando o período de tempo limite ocioso expirar, se todos os seguintes critérios forem atendidos:

• O membro DxState dessa estrutura especifica PowerDeviceD3 ou PowerDeviceMaximum.
• O firmware ACPI indica que o dispositivo dá suporte ao estado de energia D3cold.
• Se o driver especificou IdleCanWakeFromS0 ou IdleUsbSelectiveSuspend no membro IdleCaps dessa estrutura, o dispositivo poderá responder a um evento de ativação externo enquanto estiver no estado de energia D3cold. Caso contrário, esse requisito não se aplicará.

WdfUseDefault - A estrutura examina a DDInstall. Seção HW do arquivo INF do driver. Se as seguintes linhas estiverem presentes, esse valor terá o mesmo significado que WdfFalse:

Include = machine.inf
Needs = PciD3ColdSupported

Caso contrário, esse valor tem o mesmo significado que WdfTrue.

O membro ExcludeD3Cold está disponível a partir do KMDF versão 1.11, bem como a partir da versão 2.0 do UMDF, e é ignorado em sistemas operacionais anteriores a Windows 8. Consulte informações adicionais em Comentários.

Comentários

A estrutura WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS é usada como entrada para WdfDeviceAssignS0IdleSettings.

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

• A estrutura armazena os valores de todos os membros da estrutura WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS .
• Se o membro UserControlOfIdleSettings estiver definido como IdleAllowUserControl 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 dispositivo quando ele estiver ocioso.

Durante as chamadas subsequentes para WdfDeviceAssignS0IdleSettings, a estrutura armazena apenas os valores dos membros DxState, IdleTimeout e Enabled . Além disso, no KMDF 1.9 e anterior, a estrutura armazena o valor do membro IdleCaps, a menos que o valor seja IdleUsbSelectiveSuspend. Portanto, o driver deve usar as seguintes regras:

• Se o driver especificar IdleUsbSelectiveSuspend para o valor do membro IdleCaps , ele deverá fazer isso na primeira vez que chamar WdfDeviceAssignS0IdleSettings e não poderá alterar esse valor posteriormente.
• Se o driver especificar IdleCanWakeFromS0 ou IdleCannotWakeFromS0 na primeira vez que chamar WdfDeviceAssignS0IdleSettings, ele poderá chamar WdfDeviceAssignS0IdleSettings novamente para alterar esse valor (mas ele não pode alterar o valor para IdleUsbSelectiveSuspend).

Começando no KMDF 1.11 e no UMDF 2.0, um driver KMDF pode alternar entre IdleUsbSelectiveSuspend e IdleCannotWakeFromS0 a qualquer momento.

A partir de Windows 8, definir o membro IdleTimeoutType como SystemManagedIdleTimeout ou SystemManagedIdleTimeoutWithHint faz com que a estrutura se registre na PoFx (estrutura de gerenciamento de energia).

Se o driver estiver implementando suporte funcional de estado de energia para um dispositivo de vários componentes, o driver deverá definir IdleTimeoutType como DriverManagedIdleTimeout ou não chamar WdfDeviceAssignS0IdleSettings .

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

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

• O valor não pode ser PowerDeviceD0.
• Para dispositivos USB, o valor não pode ser PowerDeviceD0 ou PowerDeviceD3.
• 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 .
• Se o valor do membro IdleCaps for IdleCanWakeFromS0, você não poderá 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 motorista do 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.)

Em sistemas operacionais anteriores a Windows 8, o estado de energia D3 significa que o dispositivo está em um estado de baixa potência, mas que alguma energia para o barramento ainda é mantida. A partir de Windows 8, o antigo estado de energia D3 é chamado de D3hot e um novo estado de energia (D3cold) está disponível. Um dispositivo pode inserir o estado D3cold enquanto o sistema estiver em seu estado de trabalho (S0) ou em um estado de baixa potência. Quando um dispositivo está no estado de energia D3cold, o barramento está inativo e o dispositivo deve disparar seu próprio sinal de ativação quando uma ação externa (por exemplo, conectar um cabo de rede) causa um evento de hardware.

A partir do KMDF 1.11 e do UMDF 2.0, um dispositivo que dá suporte à energia ociosa pode usar o membro ExcludeD3Cold dessa estrutura para especificar se o estado de energia D3cold deve ser uma opção permitida para o estado de energia do dispositivo baixo que o dispositivo entrará após o término do período de tempo limite ocioso.

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

Para inicializar sua estrutura de WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS , o driver deve chamar WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT.

Requisitos

Requisito	Valor
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfdevice.h (inclua Wdf.h)