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

Artigo
02/27/2024

A rotina 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 membro Context da estrutura D3COLD_SUPPORT_INTERFACE da 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 funcionamento do sistema) por meio do S4. Para o valor SystemPowerState 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 wakeable mais profundo. 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 está 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 pelo 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 erro status código. Se uma chamada GetIdleWakeInfo falhar para qualquer valor de parâmetro SystemPowerState no intervalo PowerSystemWorking para PowerSystemHibernate, ele falhará em todos esses valores.

Retornar valor

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

Comentários

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 for bem-sucedida, a rotina gravará o estado de energia do dispositivo no local apontado pelo parâmetro DeepestWakeableDstate e retornará 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 nesse local e retornará STATUS_SUCCESS.

O driver de um dispositivo usa as informações fornecidas pela rotina GetIdleWakeInfo 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, a ativação sinaliza que o dispositivo deve enviar quando o computador está no estado de energia do sistema S0 (em funcionamento) difere daqueles que o dispositivo deve enviar quando o computador parece estar desativado.

Por exemplo, quando uma cartão é inserida em um slot de cartão do 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 para o processador. No entanto, se o dispositivo controlador estiver em um estado Dx de baixa potência quando a cartão for inserida, 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 (em funcionamento), o dispositivo deverá sinalizar um evento de ativação para o processador.
Se o computador estiver dormindo (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 controlador de hot-plug 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 nenhum 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 erro status código.

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 para a maioria dos dispositivos podem tratar um valor de saída de DeviceWakeDepthD0 da mesma forma que DeviceWakeDepthNotWakeable. Apenas alguns drivers podem ter um motivo para armar um sinal de ativação quando seus dispositivos estão 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.

A rotina GetIdleWakeInfo consulta o driver de barramento subjacente e o 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 do barramento e o firmware não puderem fornecer essas informações, a rotina falhará e retornará um erro status código.

A estrutura DEVICE_CAPABILITIES inclui um membro DeviceWake que fornece informações semelhantes às disponíveis na rotina 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 membro DeviceWake também podem se aplicar ao estado de energia do sistema S0, mas os drivers não devem depender desse comportamento. Somente a rotina GetIdleWakeInfo 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 GetIdleWakeInfo para um valor DEVICE_POWER_STATE que pode ser usado como um parâmetro de entrada pela rotina PoRequestPowerIrp .

Requisitos

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