WDF_POWER_FRAMEWORK_SETTINGS 구조체(wdfdevice.h)

아티클
08/08/2023

[KMDF 및 UMDF에 적용]

WDF_POWER_FRAMEWORK_SETTINGS 구조는 단일 구성 요소 디바이스에 대한 PoFx(전원 관리 프레임워크) 설정을 설명합니다.

구문

typedef struct _WDF_POWER_FRAMEWORK_SETTINGS {
  ULONG                                         Size;
  PFN_WDFDEVICE_WDM_POST_PO_FX_REGISTER_DEVICE  EvtDeviceWdmPostPoFxRegisterDevice;
  PFN_WDFDEVICE_WDM_PRE_PO_FX_UNREGISTER_DEVICE EvtDeviceWdmPrePoFxUnregisterDevice;
  PPO_FX_COMPONENT                              Component;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK    ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK      ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK          ComponentIdleStateCallback;
  PPO_FX_POWER_CONTROL_CALLBACK                 PowerControlCallback;
  PVOID                                         PoFxDeviceContext;
  ULONGLONG                                     PoFxDeviceFlags;
  WDF_TRI_STATE                                 DirectedPoFxEnabled;
} WDF_POWER_FRAMEWORK_SETTINGS, *PWDF_POWER_FRAMEWORK_SETTINGS;

멤버

Size

이 구조체의 크기(바이트)입니다.

EvtDeviceWdmPostPoFxRegisterDevice

드라이버의 EvtDeviceWdmPostPoFxRegisterDevice 이벤트 콜백 함수 또는 NULL에 대한 포인터입니다.

EvtDeviceWdmPrePoFxUnregisterDevice

드라이버의 EvtDeviceWdmPrePoFxUnregisterDevice 이벤트 콜백 함수 또는 NULL에 대한 포인터입니다.

Component

단일 구성 요소 디바이스 또는 NULL의 유일한 구성 요소를 설명하는 PO_FX_COMPONENT 구조체에 대한 포인터입니다. NULL인 경우 KMDF는 기본적으로 이 구성 요소에 대해서만 F0 지원을 지원합니다. 이 구조체는 구성 요소가 지원하는 F 상태의 수와 특성뿐만 아니라 구성 요소가 각성할 수 있는 가장 깊은 Fx 상태를 지정합니다.

ComponentActiveConditionCallback

드라이버의 ComponentActiveConditionCallback 콜백 루틴 또는 NULL에 대한 포인터입니다. PoFx(전원 관리 프레임워크)는 구성 요소가 활성화될 때 이 콜백 함수를 호출합니다. 활성 상태인 동안 구성 요소는 F0으로 보장됩니다.

ComponentIdleConditionCallback

드라이버의 ComponentIdleConditionCallback 콜백 함수 또는 NULL에 대한 포인터입니다. PoFx는 구성 요소가 유휴 상태가 되면 이 콜백 함수를 호출합니다. 유휴 상태인 동안 구성 요소는 F0을 비롯한 모든 F 상태에 있을 수 있습니다.

ComponentIdleStateCallback

드라이버의 ComponentIdleStateCallback 콜백 함수 또는 NULL에 대한 포인터입니다. PoFx는 구성 요소의 F 상태가 변경되면 이 콜백 함수를 호출합니다.

PowerControlCallback

클라이언트 드라이버의 PowerControlCallback 콜백 함수 또는 NULL에 대한 포인터입니다. PoFx는 이 루틴을 호출하여 전원 제어 작업에 대한 요청을 드라이버에 직접 전달합니다. 드라이버가 전원 제어 코드를 지원하지 않는 경우 이 매개 변수를 NULL로 설정합니다.

PoFxDeviceContext

프레임워크가 ComponentActiveConditionCallback, ComponentIdleConditionCallback, ComponentIdleStateCallback 및 PowerControlCallback에 제공하는 컨텍스트 포인터입니다.

PoFxDeviceFlags

Directed Power Management Framework와 관련된 다음 값의 비트 OR을 포함하는 ULONGLONG 형식의 값입니다. 이 필드는 KMDF 버전 1.33 및 UMDF 2.33부터 사용할 수 있습니다.

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

디바이스에서 Directed Power Framework("DFx")를 사용하도록 설정하면 일반적으로 자식 디바이스도 DFx를 사용하도록 설정합니다. 그러나 일부 경우(예: 순수 소프트웨어 디바이스) 자식 디바이스는 전원 관리를 구현하지 않습니다. 이러한 자식 디바이스가 DFx를 건너뛸 수 있도록 이 플래그를 설정합니다.

자식 디바이스를 대신하여 이 플래그를 설정하려면 부모 WDF 드라이버가 다음을 수행해야 합니다.

DFx 옵트인
버스 드라이버가 아님
사이드 밴드 채널을 통해 하나 이상의 가상 자식 디바이스를 만듭니다(예: SwDeviceCreate를 호출하여 만든 상위 필터 또는 디바이스)

v33 이전 WDF를 대상으로 하는 드라이버의 경우 대신 INF 지시문인 WdfDirectedPowerTransitionChildrenOptional을 지정합니다. 이 지시문은 Windows 10 버전 1903부터 사용할 수 있습니다. 드라이버가 INF 지시문을 지정하고 이 플래그를 설정하는 경우 INF 지시문이 우선합니다.

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

이는 두 디바이스 간에 IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations를 구현하는 데 필요합니다.

기본적으로 WDF는 빠른 다시 시작을 구현합니다. 즉, 시스템 절전 모드 해제 중에 디바이스 스택의 전원 정책 소유자가 D0-IRP를 요청하고 완료할 때까지 기다리지 않고 S0-IRP를 완료합니다. PowerRelations에서는 제대로 작동하지 않습니다.

PowerRelations가 제대로 작동하도록 하려면 디바이스가 D0을 먼저 입력하는 다른 디바이스에 의존하는 경우 두 번째 디바이스는 이 플래그를 빠른 다시 시작에서 옵트아웃하도록 설정해야 합니다.

경우에 따라 전역 정책은 이 플래그가 설정되지 않은 경우에도 전역적으로 빠른 다시 시작을 사용하지 않도록 설정할 수 있습니다.

DirectedPoFxEnabled

디바이스에서 DFx(Directed Power Management Framework)를 사용하도록 설정할지 여부를 나타내는 WDF_TRI_STATE 형식의 열거자입니다. KMDF 버전 1.33 및 UMDF 2.33부터 사용할 수 있습니다.

WdfTrue - DFx가 사용하도록 설정됩니다. WdfFalse – DFx를 사용할 수 없습니다. WdfUseDefault - 드라이버가 설정하지 않은 경우 기본값입니다. 이 값은 WdfTrue와 의미가 같습니다.

DFx(Directed PoFx)는 SystemManagedIdleTimeout 또는 SystemManagedIdleTimeoutWithHint를 사용하는 드라이버에 대한 옵션으로 Windows 10 버전 1903부터 사용할 수 있습니다.

v31 이전 WDF를 대상으로 하는 드라이버의 경우 INF 지시문 WdfDirectedPowerTransitionEnable 을 1로 설정하여 DFx에 옵트인합니다.
v31+ WDF를 대상으로 하는 드라이버의 경우 DFx는 기본적으로 사용하도록 설정됩니다. 드라이버는 WdfDirectedPowerTransitionEnable 을 0으로 설정하여 DFx를 옵트아웃할 수 있습니다.
v33+ WDF를 대상으로 하는 드라이버의 경우 DFx도 기본적으로 사용하도록 설정됩니다. 드라이버는 WdfDirectedPowerTransitionEnable 을 0으로 설정하거나 이 필드를 WdfFalse (권장)로 설정하여 DFx를 옵트아웃할 수 있습니다. 둘 다 설정된 경우 INF 지시문이 우선합니다.

설명

WDF_POWER_FRAMEWORK_SETTINGS 구조체는 WdfDeviceWdmAssignPowerFrameworkSettings에 대한 입력을 사용합니다.

WDF_POWER_FRAMEWORK_SETTINGS 구조를 초기화하려면 드라이버가 WDF_POWER_FRAMEWORK_SETTINGS_INIT 호출해야 합니다.

UMDF의 경우 Size, PoFxDeviceFlags 및 DirectedPoFxEnabled 만 사용됩니다. 다른 필드는 무시되며 0으로 설정해야 합니다. 프레임워크는 UMDF 드라이버가 WDF_POWER_FRAMEWORK_SETTINGS_INIT 호출할 때 이 작업을 자동으로 수행합니다.

자세한 내용은 기능 전원 상태 지원 및 전원 관리 프레임워크 개요를 참조하세요.

이 구조는 여러 구성 요소 디바이스에 대한 KMDF 클라이언트 드라이버에는 적용되지 않습니다.