USB UMDF 드라이버의 선택적 일시 중단

아티클
01/17/2024

이 항목에서는 UMDF 함수 드라이버가 USB 선택적 일시 중단을 지원하는 방법을 설명합니다.

중요 API

UMDF 함수 드라이버는 다음 두 가지 방법 중 하나로 USB 선택적 일시 중단을 지원할 수 있습니다.

전원 정책 소유권을 주장하고 디바이스 유휴 전원 다운 및 다시 시작을 처리합니다.
Microsoft에서 제공하는 WinUSB.sys 드라이버에 의존하여 선택적 일시 중단을 처리합니다. WinUSB.sys UMDF USB 드라이버를 설치하는 동안 커널 모드 디바이스 스택의 일부로 설치됩니다. WinUSB.sys USB 디바이스 작업을 일시 중단 및 다시 시작할 수 있는 기본 메커니즘을 구현합니다.

두 방법 모두 소량의 코드만 필요합니다. WDK에서 제공되는 IdleWake 샘플은 UMDF USB 드라이버에서 선택적 일시 중단을 지원하는 방법을 보여줍니다. 이 샘플은 %WinDDK%\BuildNumber\Src\Usb\OsrUsbFx2\ UMDF\Fx2_Driver\IdleWake에서 찾을 수 있습니다. 폴더에는 샘플의 PPO 및 비 PPO 버전이 모두 포함되어 있습니다.

선택적 일시 중단을 지원하는 UMDF 드라이버는 다음 지침을 따라야 합니다.

UMDF 드라이버는 디바이스 스택에 대한 전원 정책 소유권을 클레임할 수 있지만 그렇게 할 필요는 없습니다. 기본적으로 기본 WinUSB.sys 드라이버는 전원 정책을 소유합니다.
선택적 일시 중단을 지원하고 PPO인 UMDF 드라이버는 전원 관리형 큐 또는 전원 관리되지 않는 큐를 사용할 수 있습니다. 선택적 일시 중단을 지원하지만 PPO가 아닌 UMDF 드라이버는 전원 관리형 큐를 사용하면 안 됩니다.

UMDF USB 드라이버의 전원 정책 소유권

기본적으로 WinUSB.sys UMDF USB 드라이버가 포함된 디바이스 스택의 PPO입니다. WDF 1.9부터 UMDF 기반 USB 드라이버는 전원 정책 소유권을 클레임할 수 있습니다. 각 디바이스 스택에서 하나의 드라이버만 PPO일 수 있으므로 PPO인 UMDF USB 드라이버는 WinUSB.sys 전원 정책 소유권을 명시적으로 사용하지 않도록 설정해야 합니다.

UMDF USB 드라이버에서 전원 정책 소유권을 요청하려면

IWDFDeviceInitialize::SetPowerPolicyOwnership을 호출하고 일반적으로 드라이버 콜백 개체의 IDriverEntry::OnDeviceAdd 메서드에서 TRUE를 전달합니다. 예를 들면 다음과 같습니다.
```
FxDeviceInit->SetPowerPolicyOwnership(TRUE);
```
WinUSB에서 전원 정책 소유권을 사용하지 않도록 설정합니다. 드라이버의 INF 파일에 레지스트리의 WinUsbPowerPolicyOwnershipDisabled 값을 0이 아닌 값으로 설정하는 AddReg 지시문을 포함합니다. AddReg 지시문은 DDInstall.HW 섹션에 표시되어야 합니다. 예를 들면 다음과 같습니다.
```
[MyDriver_Install.NT.hw]
AddReg=MyDriver_AddReg

[MyDriver_AddReg]
HKR,,"WinUsbPowerPolicyOwnershipDisabled",0x00010001,1
```

선택적 일시 중단을 지원하고 1.9 이전의 WDF 버전으로 빌드된 UMDF USB 드라이버는 전원 정책 소유권을 주장해서는 안됩니다. 이러한 이전 버전의 WDF에서는 WinUSB.sys PPO인 경우에만 USB 선택적 일시 중단이 제대로 작동합니다.

UMDF USB 드라이버의 I/O 큐

선택적 일시 중단을 지원하는 UMDF 드라이버의 경우 UMDF 드라이버가 디바이스에 대한 전원 정책을 소유하는지 여부에 따라 사용할 수 있는 I/O 큐 유형이 결정됩니다. 선택적 일시 중단을 지원하고PPO인 UMDF 드라이버는 전원 관리 또는 전원 관리되지 않는 큐를 사용할 수 있습니다. 선택적 일시 중단을 지원하지만 PPO가 아닌 UMDF USB 드라이버는 전원 관리형 I/O 큐를 사용하면 안 됩니다.

디바이스가 일시 중단되는 동안 전원 관리 큐에 대한 I/O 요청이 도착하면 USB 드라이버의 선택적 일시 중단 이미지에 표시된 것처럼 드라이버가 PPO가 아닌 한 프레임워크는 요청을 표시하지 않습니다. UMDF 드라이버가 디바이스의 PPO가 아닌 경우 프레임워크는 디바이스를 대신하여 전원을 공급할 수 없습니다. 결과적으로 요청은 전원 관리 큐에 남아 있습니다. 요청이 WinUSB에 도달하지 않으므로 WinUSB는 디바이스의 전원을 공급할 수 없습니다. 따라서 디바이스 스택이 중단 될 수 있습니다.

큐가 전원 관리되지 않는 경우 프레임워크는 디바이스 전원이 다운된 경우에도 UMDF 드라이버에 I/O 요청을 제공합니다. UMDF 드라이버는 요청의 형식을 지정하고 디바이스 스택 아래로 일반적인 방식으로 기본 I/O 대상으로 전달합니다. 특수 코드는 필요하지 않습니다. 요청이 PPO(WinUSB.sys)에 도달하면 WinUSB.sys 디바이스의 전원을 들이고 필요한 I/O 작업을 수행합니다.

%WinDDK%\BuildNumber\Src\Usb\OsrUsbFx2\umdf\Fx2_Driver\IdleWake의 샘플 드라이버는 PPO가 아닌 버전의 드라이버를 빌드할 때 상수 _NOT_POWER_POLICY_OWNER_ 정의합니다. 드라이버는 읽기 및 쓰기 요청에 대한 큐를 만들 때 상수를 확인하여 전원 관리형 큐를 만들지 여부를 결정합니다.

큐를 만들기 위해 드라이버는 다음 세 개의 매개 변수를 사용하는 드라이버 정의 CMyQueue::Initialize 메서드를 호출합니다.

DispatchType은 큐가 요청을 디스패치하는 방법을 나타내는 WDF_IO_QUEUE_DISPATCH_TYPE 열거형 값입니다.
기본값은 큐가 기본 큐인지 여부를 나타내는 부울입니다.
PowerManaged는 큐가 전원 관리되는지 여부를 나타내는 부울입니다.

다음 코드 조각은 읽기-쓰기 큐 만들기의 일부로 CMyQueue::Initialize 메서드에 대한 드라이버의 호출을 보여줍니다.

#if defined(_NOT_POWER_POLICY_OWNER_)
    powerManaged = false;
#else
    powerManaged = true;
#endif  
hr = __super::Initialize(WdfIoQueueDispatchParallel,
                         true,
                         powerManaged,
                         );

CMyQueue::Initialize 는 다음과 같이 IWDFDevice::CreateIoQueue 를 호출하여 큐를 만듭니다.

hr = m_FxDevice->CreateIoQueue(
                               callback,
                               Default,
                               DispatchType,
                               PowerManaged,
                               FALSE,
                               &fxQueue
                               );

이 코드 시퀀스는 요청을 병렬로 디스패치하는 기본 큐를 생성합니다. 드라이버가 PPO인 경우 큐는 전원 관리되며 드라이버가 PPO가 아닌 경우 큐는 전원 관리되지 않습니다.

UMDF PPO에서 USB 선택적 일시 중단 지원

선택적 일시 중단을 지원하려면 디바이스 스택의 PPO인 UMDF USB 드라이버는 다음을 수행해야 합니다.

앞에서 설명한 대로 일반적으로 드라이버 콜백 개체의 IDriverEntry::OnDeviceAdd 메서드에서 디바이스 스택에 대한 전원 정책 소유권을 클레임합니다.
프레임워크 디바이스 개체에서 IWDFDevice2::AssignS0IdleSettings 메서드를 호출하여 선택적 일시 중단을 사용하도록 설정합니다.

PPO에서 USB 선택적 일시 중단을 사용하도록 설정하려면

일반적으로 디바이스 콜백 개체의 OnPrepareHardware 메서드에서 IWDFDevice2::AssignS0IdleSettings를 호출합니다. 매개 변수를 다음과 같이 AssignS0IdleSettings로 설정합니다.
- IdleCaps 에서 IdleUsbSelectiveSuspend로.
- DxState 를 프레임워크가 유휴 디바이스를 전환하는 디바이스 절전 상태로 전환합니다. USB 선택적 일시 중단의 경우 프레임워크가 버스 드라이버가 지정한 값을 사용해야 했음을 나타내는 PowerDeviceMaximum을 지정합니다.
- IdleTimeout 은 프레임워크가 DxState로 전환하기 전에 디바이스가 유휴 상태여야 하는 시간(밀리초)입니다.
- 드라이버에서 사용자가 유휴 설정을 관리할 수 있는 경우 UserControlOfIdleSettings에서 IdleAllowUserControl로, 그렇지 않으면 IdleDoNotAllowUserControl로 이동합니다.
- 기본적으로 선택적 일시 중단을 사용하도록 설정하지만 사용자의 설정이 기본값을 재정의하도록 허용하려면 WdfUseDefault를 사용하도록 설정합니다.

다음 예제에서는 IdleWake_PPO 드라이버가 내부 CMyDevice::SetPowerManagement 메서드에서 이 메서드를 호출하는 방법을 보여줍니다.

hr = m_FxDevice->AssignS0IdleSettings( IdleUsbSelectiveSuspend,
                                PowerDeviceMaximum,
                                IDLE_TIMEOUT_IN_MSEC,
                                IdleAllowUserControl,
                                WdfUseDefault);

디바이스 하드웨어가 절전 모드 해제 신호를 생성할 수 있는 경우 UMDF 드라이버는 S1, S2 또는 S3에서 시스템 절전 모드 해제를 지원할 수도 있습니다. 자세한 내용은 UMDF 드라이버의 시스템 절전 모드 해제를 참조하세요.

PPO가 아닌 UMDF 드라이버에서 USB 선택적 일시 중단 지원

PPO가 아닌 UMDF 함수 드라이버는 기본 WinUSB.sys 드라이버의 기능을 사용하여 선택적 일시 중단을 지원할 수 있습니다. UMDF 드라이버는 디바이스와 드라이버가 선택적 일시 중단을 지원하며 INF 파일에서 또는 USB 대상 디바이스 개체에서 전원 정책을 설정하여 선택적 일시 중단을 사용하도록 설정해야 한다는 사실을 WinUSB에 알려야 합니다.

UMDF 함수 드라이버가 선택적 일시 중단을 사용하도록 설정하면 기본 WinUSB.sys 드라이버가 디바이스가 유휴 상태인지 확인합니다. WinUSB는 보류 중인 전송이 없거나 인터럽트 또는 대량 엔드포인트에서 유일하게 보류 중인 전송이 IN 전송인 경우 유휴 시간 제한 카운터를 시작합니다. 기본적으로 유휴 시간 제한은 5초이지만 UMDF 드라이버는 이 기본값을 변경할 수 있습니다.

WinUSB.sys 디바이스가 유휴 상태임을 확인하면 커널 모드 디바이스 스택 아래로 디바이스를 일시 중단하라는 요청을 보냅니다. 버스 드라이버가 하드웨어의 상태를 적절하게 변경합니다. 포트의 모든 디바이스 기능이 일시 중단된 경우 포트는 USB 선택적 일시 중단 상태가 됩니다.

디바이스가 일시 중단된 동안 I/O 요청이 WinUSB.sys 도착하면 WinUSB.sys 디바이스의 전원을 켜서 요청을 서비스해야 하는 경우 디바이스 작업을 다시 시작합니다. 시스템이 S0에 남아 있는 동안 UMDF 드라이버는 디바이스를 다시 시작하는 코드가 필요하지 않습니다. 디바이스 하드웨어가 절전 모드 해제 신호를 생성할 수 있는 경우 UMDF 드라이버는 S1, S2 또는 S3에서 시스템 절전 모드 해제를 지원할 수도 있습니다. 자세한 내용은 UMDF 드라이버의 시스템 절전 모드 해제를 참조하세요.

PPO가 아닌 UMDF 드라이버는 다음 두 단계를 수행하여 선택적 일시 중단을 지원할 수 있습니다.

디바이스 및 드라이버가 선택적 일시 중단을 지원하는지 WinUSB.sys 알립니다.
USB 선택적 일시 중단을 사용하도록 설정합니다.

또한 드라이버는 필요에 따라 다음을 수행할 수 있습니다.

디바이스에 대한 제한 시간 값을 설정합니다.
사용자가 선택적 일시 중단을 사용하거나 사용하지 않도록 설정할 수 있습니다.

PPO가 아닌 UMDF USB 함수 드라이버에서 USB 선택적 일시 중단을 구현하는 방법에 대한 예제는 WDK의 Fx2_Driver 샘플을 참조하세요. 이 샘플은 %WinDDK%\BuildNumber\Src\Usb\OsrUsbFx2\Umdf\Fx2_Driver\ IdleWake_Non-PPO에 있습니다.

선택적 일시 중단 지원에 대해 WinUSB에 알리려면

디바이스가 USB 선택적 일시 중단을 지원할 수 있음을 WinUSB.sys 알리려면 디바이스 INF가 DeviceIdleEnabled 값을 디바이스의 하드웨어 키에 추가하고 값을 1로 설정해야 합니다. 다음 예제에서는 Fx2_Driver 샘플이 WUDFOsrUsbFx2_IdleWakeNon-PPO.Inx 파일에서 이 값을 추가하고 설정하는 방법을 보여줍니다.

[OsrUsb_Device_AddReg]
...
HKR,,"DeviceIdleEnabled",0x00010001,1

USB 선택적 일시 중단을 사용하도록 설정하려면

UMDF USB 드라이버는 런타임 또는 INF에서 설치하는 동안 USB 선택적 일시 중단을 사용하도록 설정할 수 있습니다.

런타임에 지원을 사용하도록 설정하기 위해 함수 드라이버는 IWDFUsbTargetDevice::SetPowerPolicy 를 호출하고 PolicyType 매개 변수를 AUTO_SUSPEND, Value 매개 변수를 TRUE 또는 1로 설정합니다. 다음 예제에서는 Fx2_Driver 샘플이 DeviceNonPpo.cpp 파일에서 선택적 일시 중단을 사용하도록 설정하는 방법을 보여 줍니다.
```
BOOL AutoSuspend = TRUE;
hr = m_pIUsbTargetDevice->SetPowerPolicy( AUTO_SUSPEND,
                                          sizeof(BOOL),
                                         (PVOID) &AutoSuspend );
```
설치 중에 지원을 사용하도록 설정하기 위해 INF에는 디바이스의 하드웨어 키에 DefaultIdleState 값을 추가하고 값을 1로 설정하는 AddReg 지시문이 포함되어 있습니다. 예를 들면 다음과 같습니다.
```
HKR,,"DefaultIdleState",0x00010001,1
```

유휴 시간 제한 값을 설정하려면

기본적으로 WinUSB는 보류 중인 전송이 없거나 보류 중인 유일한 전송이 인터럽트 또는 대량 엔드포인트에서 IN 전송인 경우 5초 후에 디바이스를 일시 중단합니다. UMDF 드라이버는 INF 또는 런타임에 설치할 때 이 유휴 시간 제한 값을 변경할 수 있습니다.

설치 시 유휴 시간 제한을 설정하기 위해 INF에는 디바이스의 하드웨어 키에 DefaultIdleTimeout 값을 추가하고 값을 시간 제한 간격(밀리초)으로 설정하는 AddReg 지시문이 포함되어 있습니다. 다음 예제에서는 제한 시간을 7초로 설정합니다.
```
HKR,,"DefaultIdleTimeout",0x00010001,7000
```
런타임에 유휴 시간 초과를 설정하기 위해 드라이버는 PolicyType이 SUSPEND_DELAY 설정된 IWDFUsbTargetDevice::SetPowerPolicy 를 호출하고 값은 유휴 시간 제한 값(밀리초)으로 설정합니다. Device.cpp 파일의 다음 예제에서 Fx2_Driver 샘플은 제한 시간을 10초로 설정합니다.
```
HRESULT hr;
ULONG value;
value = 10 * 1000;
hr = m_pIUsbTargetDevice->SetPowerPolicy( SUSPEND_DELAY,
                                          sizeof(ULONG),
                                         (PVOID) &value );
```

USB 선택적 일시 중단의 사용자 제어를 제공하려면**

WinUSB 선택적 일시 중단 지원을 사용하는 UMDF USB 드라이버는 선택적으로 사용자가 선택적 일시 중단을 사용하거나 사용하지 않도록 설정할 수 있습니다. 이렇게 하려면 디바이스의 하드웨어 키에 UserSetDeviceIdleEnabled 값을 추가하고 값을 1로 설정하는 AddReg 지시문을 INF에 포함합니다. 다음은 AddReg 지시문에 사용할 문자열을 보여줍니다.

HKR,,"UserSetDeviceIdleEnabled",0x00010001,1

UserSetDeviceIdleEnabled가 설정된 경우 디바이스의 속성 대화 상자에는 사용자가 USB 선택적 일시 중단을 사용하거나 사용하지 않도록 설정할 수 있는 전원 관리 탭이 포함됩니다.

UMDF 드라이버의 시스템 절전 모드 해제

UMDF 드라이버에서 시스템 절전 모드 해제에 대한 지원은 선택적 일시 중단에 대한 지원과는 별개입니다. UMDF USB 드라이버는 시스템 절전 모드 해제 및 선택적 일시 중단, 시스템 절전 모드 해제 또는 선택적 일시 중단 또는 시스템 절전 모드 해제 또는 선택적 일시 중단을 모두 지원할 수 있습니다. 시스템 절전 모드 해제를 지원하는 디바이스는 절전 모드 해제 상태(S1, S2 또는 S3)에서 시스템을 절전 모드 해제할 수 있습니다.

UMDF USB PPO 드라이버는 프레임워크의 드라이버 개체에 대한 절전 모드 해제 정보를 제공하여 시스템 절전 모드 해제를 지원할 수 있습니다. 외부 이벤트가 시스템 절전 모드 해제를 트리거하면 프레임워크는 디바이스를 작업 상태로 반환합니다.

USB 비 PPO 드라이버는 WinUSB.sys 드라이버가 구현하는 시스템 절전 모드 해제 지원을 사용할 수 있습니다.

PPO인 UMDF USB 드라이버에서 시스템 절전 모드 해제를 지원하려면**

다음 매개 변수를 사용하여 프레임워크의 디바이스 개체에서 IWDFDevice2::AssignSxWakeSettings 메서드를 호출합니다.

DxState 는 시스템이 절전 모드 해제 가능한 Sx 상태로 전환할 때 디바이스가 전환되는 전원 상태입니다. USB 디바이스의 경우 버스 드라이버가 지정한 값을 사용하도록 PowerDeviceMaximum 을 지정합니다.
드라이버에서 사용자가 절전 모드 해제 설정을 관리하거나 WakeDoNotAllowUserControl에 대해 다른 방법을 사용할 수 있는 경우 UserControlOfWakeSettings에서 WakeAllowUserControl로 이동합니다.
기본적으로 절전 모드 해제를 사용하도록 설정하지만 사용자의 설정이 기본값을 재정의하도록 허용하려면 WdfUseDefault를 사용하도록 설정합니다.

다음 예제에서는 IdleWake_PPO 드라이버가 내부 CMyDevice::SetPowerManagement 메서드에서 이 메서드를 호출하는 방법을 보여 줍니다.

hr = m_FxDevice->AssignSxWakeSettings( PowerDeviceMaximum,
                                       WakeAllowUserControl,
                                       WdfUseDefault);

비 PPO 드라이버에서 WinUSB를 통해 시스템 절전 모드 해제를 사용하도록 설정하려면**

WinUSB를 통해 시스템 절전 모드 해제를 사용하도록 설정하기 위해 드라이버의 INF는 레지스트리 값 SystemWakeEnabled를 디바이스의 하드웨어 키에 추가하고 1로 설정합니다. IdleWake_Non-PPO 샘플은 다음과 같이 시스템 절전 모드 해제를 사용하도록 설정합니다.

[OsrUsb_Device_AddReg]
...
HKR,,"SystemWakeEnabled",0x00010001,1

이 값을 설정하면 드라이버가 시스템 절전 모드 해제를 사용하도록 설정하고 사용자가 디바이스의 시스템 절전 모드 해제 기능을 제어할 수 있습니다. 장치 관리자 디바이스의 전원 관리 설정 속성 페이지에는 사용자가 시스템 절전 모드 해제를 사용하거나 사용하지 않도록 설정할 수 있는 검사 상자가 포함되어 있습니다.

USB 드라이버의 선택적 일시 중단(WDF)

다음을 통해 공유

USB UMDF 드라이버의 선택적 일시 중단

중요 API

UMDF USB 드라이버의 전원 정책 소유권

UMDF USB 드라이버에서 전원 정책 소유권을 요청하려면

UMDF USB 드라이버의 I/O 큐

UMDF PPO에서 USB 선택적 일시 중단 지원

PPO에서 USB 선택적 일시 중단을 사용하도록 설정하려면

PPO가 아닌 UMDF 드라이버에서 USB 선택적 일시 중단 지원

선택적 일시 중단 지원에 대해 WinUSB에 알리려면

USB 선택적 일시 중단을 사용하도록 설정하려면

유휴 시간 제한 값을 설정하려면

USB 선택적 일시 중단의 사용자 제어를 제공하려면**

UMDF 드라이버의 시스템 절전 모드 해제

PPO인 UMDF USB 드라이버에서 시스템 절전 모드 해제를 지원하려면**

비 PPO 드라이버에서 WinUSB를 통해 시스템 절전 모드 해제를 사용하도록 설정하려면**

피드백

추가 리소스

다음을 통해 공유

USB UMDF 드라이버의 선택적 일시 중단

중요 API

UMDF USB 드라이버의 전원 정책 소유권

UMDF USB 드라이버에서 전원 정책 소유권을 요청하려면

UMDF USB 드라이버의 I/O 큐

UMDF PPO에서 USB 선택적 일시 중단 지원

PPO에서 USB 선택적 일시 중단을 사용하도록 설정하려면

PPO가 아닌 UMDF 드라이버에서 USB 선택적 일시 중단 지원

선택적 일시 중단 지원에 대해 WinUSB에 알리려면

USB 선택적 일시 중단을 사용하도록 설정하려면

유휴 시간 제한 값을 설정하려면

USB 선택적 일시 중단의 사용자 제어를 제공하려면**

UMDF 드라이버의 시스템 절전 모드 해제

PPO인 UMDF USB 드라이버에서 시스템 절전 모드 해제를 지원하려면**

비 PPO 드라이버에서 WinUSB를 통해 시스템 절전 모드 해제를 사용하도록 설정하려면**

관련 항목

피드백

추가 리소스