GET_IDLE_WAKE_INFO 콜백 함수(wdm.h)

아티클
08/08/2023

GetIdleWakeInfo 루틴을 사용하면 디바이스가 절전 모드 해제 이벤트를 신호로 표시할 수 있는 디바이스 전원 상태를 검색할 수 있습니다.

구문

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

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

매개 변수

[in, optional] Context

인터페이스별 컨텍스트 정보에 대한 포인터입니다. 호출자는 이 매개 변수를 인터페이스에 대한 D3COLD_SUPPORT_INTERFACE 구조체의 Context 멤버 값으로 설정합니다.

[in] SystemPowerState

시스템 전원 상태입니다. 이 매개 변수를 다음 SYSTEM_POWER_STATE 열거형 값 중 하나로 설정합니다.

PowerSystemWorking
PowerSystemSleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

이러한 값은 S4를 통한 시스템 전원 상태 S0(시스템 작업 상태)을 나타냅니다. 호출자가 제공하는 SystemPowerState 값의 경우 루틴은 디바이스가 절전 모드 해제 신호를 실행할 수 있는 가장 깊은 디바이스 전원 상태를 결정합니다.

[out] DeepestWakeableDstate

절전 모드 해제 가능한 가장 깊은 Dx 상태입니다. 이 매개 변수는 DEVICE_WAKE_DEPTH 변수에 대한 포인터입니다. 호출이 성공하면 루틴은 다음 열거형 값 중 하나를 이 변수에 씁니다.

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1
DeviceWakeDepthD2
DeviceWakeDepthD3hot
DeviceWakeDepthD3cold

DeviceWakeDepthD0에서 DeviceWakeDepthD3cold 범위의 값은 컴퓨터가 SystemPowerState 매개 변수로 지정된 시스템 전원 상태에 있을 때 디바이스가 절전 모드 해제 신호를 보낼 수 있는 가장 낮은 전원 Dx 상태를 나타냅니다. DeviceWakeDepthNotWakeable 은 컴퓨터가 SystemPowerState에 지정된 시스템 전원 상태일 때 디바이스가 절전 모드 해제 신호를 보낼 수 있는 디바이스 전원 상태가 없음을 나타냅니다.

루틴이 절전 모드 해제 가능한 가장 깊은 디바이스 상태를 확인할 수 없는 경우(플랫폼 펌웨어에 이 정보가 포함되어 있지 않기 때문일 수 있음) 호출이 실패하고 루틴은 코드에 상태 오류를 반환합니다. PowerSystemWorking에서 PowerSystemHibernate 범위의 SystemPowerState 매개 변수 값에 대해 GetIdleWakeInfo 호출이 실패하면 이러한 모든 값에 대해 실패합니다.

반환 값

GetIdleWakeInfo 루틴은 절전 모드 해제 가능한 가장 깊은 디바이스 상태를 성공적으로 검색하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 적절한 오류 상태 코드를 반환합니다.

설명

호출자가 지정한 시스템 전원 상태의 경우 이 루틴은 디바이스가 절전 모드 해제 이벤트를 프로세서에 신호할 수 있는 가장 낮은 전원 디바이스 전원 상태를 확인하려고 합니다. 성공하면 루틴은 DeepestWakeableDstate 매개 변수가 가리키는 위치에 디바이스 전원 상태를 쓰고 STATUS_SUCCESS 반환합니다. 또는 루틴이 디바이스 전원 상태에서 절전 모드 해제 이벤트를 신호할 수 없다고 판단하는 경우 루틴은 DeviceWakeDepthNotWakeable 값을 이 위치에 쓰고 STATUS_SUCCESS 반환합니다.

디바이스의 드라이버는 GetIdleWakeInfo 루틴에서 제공하는 정보를 사용하여 디바이스가 절전 모드 해제 이벤트를 신호로 표시할 수 있는 조건을 확인합니다. 특정 절전 모드 해제 이벤트를 신호할 수 있어야 하는 디바이스는 이러한 이벤트를 신호할 수 없는 디바이스 전원 상태로 들어가면 안 됩니다. 일부 유형의 디바이스에서 절전 모드 해제 신호는 컴퓨터가 S0(작동 중) 시스템 전원 상태일 때 디바이스가 전송해야 한다는 신호와 컴퓨터가 꺼져 있는 것처럼 보일 때 디바이스가 보내야 하는 것과 다릅니다.

예를 들어 카드 PCI Express 카드 슬롯에 삽입되고 슬롯에 대한 PCI Express 핫 플러그 컨트롤러 디바이스가 D0 디바이스 전원 상태에 있는 경우 이 디바이스는 프로세서에 인터럽트 신호를 보냅니다. 그러나 카드 삽입할 때 컨트롤러 디바이스가 저전력 Dx 상태인 경우 컴퓨터의 시스템 전원 상태는 이 디바이스가 절전 모드 해제 이벤트를 프로세서에 신호해야 하는지 여부를 결정할 수 있습니다. 이상적으로 컨트롤러 디바이스는 다음과 같이 동작해야 합니다.

컴퓨터가 S0(작동 중) 시스템 전원 상태인 경우 디바이스는 절전 모드 해제 이벤트를 프로세서에 신호해야 합니다.
컴퓨터가 절전 모드(저전력 Sx 상태)인 경우 디바이스는 절전 모드 해제 이벤트를 신호로 표시해서는 안 됩니다.

일부 이전 디바이스는 이 이상적인 동작을 지원하지 않을 수 있습니다. 이 예제의 PCI Express 핫 플러그 컨트롤러 디바이스가 컴퓨터가 S3 상태일 때만 절전 모드 해제 이벤트를 신호로 표시할 수 있는 경우 컨트롤러의 드라이버(이 경우 받은 편지함 Pci.sys 드라이버)는 컴퓨터가 S0에 있을 때 컨트롤러를 D0(절전 모드 상태로 설정할 준비를 하지 않음)로 유지해야 합니다.

이 예제의 드라이버는 GetIdleWakeInfo 루틴을 호출하여 컴퓨터가 S0에 있는 동안 핫 플러그 컨트롤러 디바이스가 D0 상태를 유지해야 하는지 여부를 결정할 수 있습니다. 이 호출의 경우 드라이버는 SystemPowerState = PowerSystemWorking을 설정합니다. 이 디바이스는 다음 경우 중 하나에서 D0 상태(컴퓨터가 S0에 있는 경우)를 벗어나지 않아야 합니다.

GetIdleWakeInfo 호출은 출력 매개 변수를 DeviceWakeDepthNotWakeable 또는 DeviceWakeDepthD0으로 설정하고 STATUS_SUCCESS 반환합니다.
GetIdleWakeInfo 호출이 실패하고 코드에 상태 오류를 반환합니다.

드라이버는 컴퓨터가 S0에 있을 때 디바이스가 절전 모드 해제 이벤트를 신호할 수 없음을 의미하도록 이러한 결과 중 하나를 해석해야 합니다. 이 정보에 따라 드라이버는 컴퓨터가 S0 종료를 준비할 때까지 디바이스를 D0에 유지해야 합니다.

대부분의 디바이스에 대한 드라이버는 DeviceWakeDepthD0 의 출력 값을 DeviceWakeDepthNotWakeable과 동일하게 처리할 수 있습니다. 디바이스가 D0에 있을 때 일부 드라이버만 절 해제 신호를 무장해야 할 이유가 있을 수 있습니다. 디바이스가 D0 또는 저전력 Dx 상태인지에 관계없이 절전 모드 해제 신호를 트리거하는 외부 이벤트를 모니터링하는 간단한 디바이스용 드라이버입니다. 이러한 디바이스의 예로는 컴퓨터의 전원 단추 또는 절전 모드 단추가 있습니다.

GetIdleWakeInfo 루틴은 기본 버스 드라이버 및 ACPI 시스템 펌웨어를 쿼리하여 디바이스가 절전 모드 해제 이벤트를 신호할 수 있는 가장 낮은 디바이스 전원 상태를 확인합니다. 버스 드라이버와 펌웨어가 이 정보를 제공할 수 없는 경우 루틴이 실패하고 코드에 상태 오류를 반환합니다.

DEVICE_CAPABILITIES 구조에는 GetIdleWakeInfo 루틴에서 사용할 수 있는 것과 유사한 정보를 제공하는 DeviceWake 멤버가 포함됩니다. 그러나 DeviceWake 멤버의 정보는 S1에서 S4까지의 시스템 저전력 상태에만 적용됩니다. 일부 디바이스의 경우 DeviceWake 멤버의 정보가 S0 시스템 전원 상태에도 적용될 수 있지만 드라이버는 이러한 동작에 의존해서는 안 됩니다. GetIdleWakeInfo 루틴만 컴퓨터가 S0에 있는 경우 절전 모드 해제 이벤트를 신호하는 디바이스의 기능을 안정적으로 보고합니다.

인라인 도우미 함수 MapWakeDepthToDstate는 getIdleWakeInfo 루틴의 DEVICE_WAKE_DEPTH 출력 값을 PoRequestPowerIrp 루틴에서 입력 매개 변수로 사용할 수 있는 DEVICE_POWER_STATE 값으로 변환하기 위해 제공됩니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8 시작해서 사용할 수 있습니다.
대상 플랫폼	데스크톱
머리글	wdm.h(Wdm.h 포함)
IRQL	PASSIVE_LEVEL