GET_IDLE_WAKE_INFO função de retorno de chamada (wdm.h)

Artigo
02/07/2025

A rotina de GetIdleWakeInfo permite que o driver de um dispositivo descubra os estados de energia do dispositivo dos quais o dispositivo pode sinalizar um evento de ativação.

Sintaxe

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

NTSTATUS GetIdleWakeInfo(
  [in, optional] PVOID Context,
  [in]           SYSTEM_POWER_STATE SystemPowerState,
  [out]          PDEVICE_WAKE_DEPTH DeepestWakeableDstate
)
{...}

Parâmetros

[in, optional] Context

Um ponteiro para informações de contexto específicas da interface. O chamador define esse parâmetro como o valor do Context membro da estrutura D3COLD_SUPPORT_INTERFACE para a interface.

[in] SystemPowerState

Estado de energia do sistema. Defina esse parâmetro como um dos seguintes valores de enumeração SYSTEM_POWER_STATE:

powersystemworking
powersystemsleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

Esses valores representam os estados de energia do sistema S0 (estado de trabalho do sistema) por meio do S4. Para o SystemPowerState valor fornecido pelo chamador, a rotina determina o estado de energia do dispositivo mais profundo do qual o dispositivo pode emitir um sinal de ativação.

[out] DeepestWakeableDstate

Estado Dx mais profundo e wakeable. Esse parâmetro é um ponteiro para uma variável DEVICE_WAKE_DEPTH. Se a chamada for bem-sucedida, a rotina gravará um dos seguintes valores de enumeração nessa variável:

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1
DeviceWakeDepthD2
DeviceWakeDepthD3hot
DeviceWakeDepthD3cold

Um valor no intervalo DeviceWakeDepthD0 para DeviceWakeDepthD3cold indica o estado Dx de menor potência do qual o dispositivo pode enviar um sinal de ativação quando o computador estiver no estado de energia do sistema especificado pelo parâmetro SystemPowerState. DeviceWakeDepthNotWakeable indica que não há nenhum estado de energia do dispositivo do qual o dispositivo possa enviar um sinal de ativação quando o computador estiver no estado de energia do sistema especificado por SystemPowerState.

Se a rotina não puder determinar o estado mais profundo do dispositivo wakeable (talvez porque o firmware da plataforma não contém essas informações), a chamada falhará e a rotina retornará um código de status de erro. Se uma chamada GetIdleWakeInfo falhar para qualquer systemPowerState valor de parâmetro no intervalo PowerSystemWorking para PowerSystemHibernate, ele falhará em todos esses valores.

Valor de retorno

A rotina GetIdleWakeInfo retorna STATUS_SUCCESS se recuperar com êxito o estado mais profundo do dispositivo wakeable. Caso contrário, ele retornará um código de status de erro apropriado.

Observações

Para o estado de energia do sistema especificado pelo chamador, essa rotina tenta determinar o estado de energia do dispositivo de menor potência do qual o dispositivo pode sinalizar um evento de ativação para o processador. Se bem-sucedida, a rotina grava o estado de energia do dispositivo no local apontado pelo parâmetro de de DeepestWakeableDstate e retorna STATUS_SUCCESS. Ou, se a rotina determinar que o dispositivo não pode sinalizar um evento de ativação de qualquer estado de energia do dispositivo, a rotina gravará o valor DeviceWakeDepthNotWakeable para esse local e retornará STATUS_SUCCESS.

O driver de um dispositivo usa as informações fornecidas pelo getIdleWakeInfo rotina para determinar as condições sob as quais o dispositivo pode sinalizar um evento de ativação. Um dispositivo que precisa ser capaz de sinalizar determinados eventos de ativação não deve entrar em um estado de energia do dispositivo do qual ele não pode sinalizar esses eventos. Para alguns tipos de dispositivos, os sinais de ativação que o dispositivo deve enviar quando o computador está no estado de energia do sistema S0 (funcionando) diferem daqueles que o dispositivo deve enviar quando o computador parece estar desativado.

Por exemplo, quando um cartão é inserido em um slot de cartão PCI Express e o dispositivo de controlador de plug-quente PCI Express para o slot está no estado de energia do dispositivo D0, esse dispositivo sinaliza uma interrupção no processador. No entanto, se o dispositivo controlador estiver em um estado Dx de baixa potência quando o cartão for inserido, o estado de energia do sistema do computador poderá determinar se esse dispositivo deve sinalizar um evento de ativação para o processador. O ideal é que o dispositivo controlador se comporte da seguinte maneira:

Se o computador estiver no estado de energia do sistema S0 (funcionando), o dispositivo deverá sinalizar um evento de ativação para o processador.
Se o computador estiver em suspensão (em um estado Sx de baixa potência), o dispositivo não deverá sinalizar um evento de ativação.

Alguns dispositivos mais antigos podem não dar suporte a esse comportamento ideal. Se o dispositivo de controlador de plug-quente PCI Express neste exemplo puder sinalizar um evento de ativação somente quando o computador estiver no estado S3, o driver (que, nesse caso, é a caixa de entrada Pci.sys driver) para o controlador deverá manter o controlador em D0 quando o computador estiver em S0 (e não estiver se preparando para entrar em um estado de suspensão).

O driver neste exemplo pode chamar a rotina GetIdleWakeInfo para determinar se o dispositivo do controlador de plug-quente deve deixar o estado D0 enquanto o computador estiver em S0. Para essa chamada, o driver define SystemPowerState = PowerSystemWorking. Esse dispositivo não deve deixar o estado D0 (quando o computador estiver em S0) em qualquer um dos seguintes casos:

A chamada GetIdleWakeInfo define o parâmetro de saída como DeviceWakeDepthNotWakeable ou DeviceWakeDepthD0 e retorna STATUS_SUCCESS.
A chamada GetIdleWakeInfo falha e retorna um código de status de erro.

O driver deve interpretar qualquer um desses resultados para significar que o dispositivo não pode sinalizar um evento de ativação quando o computador estiver em S0. Com base nessas informações, o driver deve manter o dispositivo em D0 até que o computador se prepare para sair do S0.

Os drivers da maioria dos dispositivos podem tratar um valor de saída de DeviceWakeDepthD0 o mesmo que DeviceWakeDepthNotWakeable. Apenas alguns drivers podem ter um motivo para armar um sinal de ativação quando seus dispositivos estiverem em D0. Esses são drivers para dispositivos simples que monitoram eventos externos que disparam sinais de ativação, independentemente de os dispositivos estarem em estados D0 ou Dx de baixa potência. Um exemplo desse dispositivo é um botão de energia ou um botão de suspensão em um computador.

O GetIdleWakeInfo consultas rotineiras ao driver de ônibus subjacente e ao firmware do sistema ACPI para determinar o estado de energia do dispositivo mais baixo do qual o dispositivo pode sinalizar um evento de ativação. Se o driver de ônibus e o firmware não puderem fornecer essas informações, a rotina falhará e retornará um código de status de erro.

A estrutura DEVICE_CAPABILITIES inclui um membro DeviceWake que fornece informações semelhantes às disponíveis na rotina de getIdleWakeInfo. No entanto, as informações no membro DeviceWake se aplicam somente aos estados de baixa potência do sistema S1 a S4. Para alguns dispositivos, as informações no devicewake membro também podem se aplicar ao estado de energia do sistema S0, mas os drivers não devem depender desse comportamento. Somente o GetIdleWakeInfo rotina relata de forma confiável a capacidade de um dispositivo sinalizar um evento de ativação se o computador estiver no S0.

Uma função auxiliar embutida, MapWakeDepthToDstate, é fornecida para converter o valor de saída DEVICE_WAKE_DEPTH da rotina de GetIdleWakeInfo em um valor DEVICE_POWER_STATE que pode ser usado como um parâmetro de entrada pela rotina de PoRequestPowerIrp.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível a partir do Windows 8.
da Plataforma de Destino	Área de trabalho
cabeçalho	wdm.h (inclua Wdm.h)
IRQL	PASSIVE_LEVEL