Share via

WDF 드라이버 디버깅을 위한 레지스트리 값

  • 아티클

이 문서에서는 WDF 드라이버가 설정할 수 있는 레지스트리 값에 대해 설명합니다. UMDF 버전 2부터 KMDF 드라이버 및 UMDF 드라이버에 적용됩니다.

아래 섹션에서 달리 지정하지 않는 한 다음 레지스트리 값은 드라이버의 Parameters\Wdf 하위 키 아래에 있습니다.

  • KMDF 드라이버의 경우 이 하위 키는 드라이버의 서비스 이름 아래에 있는 에 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services있습니다.
  • UMDF 드라이버의 경우 이 하위 키는 드라이버의 서비스 이름 아래에 있는 에 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services있습니다.

드라이버의 하위 키는 드라이버 이진 파일 이름이 서비스 이름과 다른 경우에도 항상 드라이버의 서비스 이름을 사용합니다.

DbgBreakOnError

REG_DWORD

0이 아닌 값으로 설정하면 드라이버가 WdfVerifierDbgBreakPoint를 호출할 때 프레임워크가 디버거로 중단됩니다. VerifierOn 값이 설정되면 DbgBreakOnError 값이 없더라도 프레임워크가 디버거로 중단됩니다. VerifierOn 섹션의 코드 예제를 참조하세요.

DbgPrintOn

REG_DWORD

  • KMDF 드라이버의 경우 레지스트리 키 아래에 HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\Diagnostics 이 값을 설정합니다.
  • UMDF 드라이버의 경우 레지스트리 키 아래에 HKLM\System\CurrentControlSet\Control\Wdf\Umdf\Diagnostics 이 값을 설정합니다.

드라이버는 선택적 진단 하위 키를 만들어야 할 수 있습니다.

0이 아닌 값으로 설정된 경우 프레임워크의 로더는 드라이버를 로드하고 프레임워크 라이브러리 버전에 바인딩하는 동안 또는 드라이버를 언로드하는 동안 커널 디버거에 다양한 메시지를 보냅니다.

DbgWaitForSignalTimeoutInSec

REG_DWORD, 프레임워크 버전 1.11 이상

Windows 8 시작해서 VerifierOn 및 DbgBreakOnError가 0이 아닌 값으로 설정된 경우 드라이버는 DbgWaitForSignalTimeoutInSec을 설정하여 디버거에 침입하기 위한 기본 제한 시간을 변경할 수 있습니다.

DebugModeBinaries

REG_MULTI_SZ, UMDF 전용

이 레지스트리 값은 에 있습니다 HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

이 값은 디버그 모드에서 로드할 드라이버 이진 파일의 이름을 지정합니다. 드라이버 이진 파일 X.DLL, Y.DLL 및 Z.DLL 디버그 모드를 사용하도록 설정하려면 이 값이 로 X.DLL\0Y.DLL\0Z.DLL\0\0설정됩니다.

DebugModeFlags

REG_DWORD, UMDF 전용

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

값 Description
0x01 디버그 모드를 사용하도록 설정합니다. 이 설정은 UMDF 드라이버에서 디바이스 풀링 사용에 설명된 자동 다시 시작 기능을 해제합니다.
0x02 디바이스 풀링을 사용하지 않도록 설정합니다. 디바이스 풀링에 대한 자세한 내용은 UMDF 드라이버에서 디바이스 풀링 사용을 참조하세요.
0x04 시간 제한을 사용하지 않도록 설정합니다.

Microsoft Visual Studio에서 F5 옵션을 사용하면 배포된 드라이버에 대해 세 가지 플래그가 모두 설정됩니다.

EnhancedVerifierOptions

REG_DWORD, 프레임워크 버전 1.9 이상

이 값에는 비트맵이 포함됩니다. 각 비트는 사용자가 비트를 설정하여 사용하도록 설정할 수 있는 추가 검증 도구 옵션을 나타냅니다.

비트 값:

0x1: 설정된 경우 검증 도구는 각 드라이버의 이벤트 콜백 함수가 다음을 수행하는지 여부를 확인합니다.

0x10000: 설정된 경우 드라이버가 I/O 큐에 대해 보장된 진행률을 사용하도록 설정한 경우 프레임워크는 각 큐의 I/O 요청에 대한 메모리 부족 상황을 시뮬레이션합니다.

0x20000: 설정된 경우 드라이버가 I/O 큐에 대해 보장된 진행률을 사용하도록 설정한 경우 프레임워크는 임의로 선택된 일부 I/O 요청에 대해 메모리 부족 상황을 시뮬레이션합니다.

ForceLogsInMiniDump

REG_DWORD

프레임워크가 크래시 덤프 파일에 이벤트 로거의 정보를 포함하도록 하려면 0이 아닌 값으로 설정합니다.

HostFailKdDebugBreak

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF.

이 값이 0이 아니고 커널 디버거가 컴퓨터에 연결된 경우 리플렉터가 커널 디버거에 침입한 후 호스트 프로세스를 종료합니다. HostFailKdDebugBreak 는 Windows 7 및 이전 운영 체제에서 기본적으로 사용하지 않도록 설정됩니다. Windows 8 시작해서 HostFailKdDebugBreak는 기본적으로 사용하도록 설정됩니다.

호스트 프로세스가 예기치 않게 종료되는 경우(예: UMDF가 아닌 구성 요소 또는 처리되지 않은 예외로 인해) 리플렉터도 커널 디버거로 나뉩니다. 종료되는 호스트 프로세스에 풀된 여러 디바이스 스택이 있는 경우 리플렉터가 호스트 프로세스에 로드된 각 디바이스 스택에 대해 한 번씩 디버거에 여러 번 침입합니다.

HostProcessDbgBreakOnDriverLoad(드라이버별)

UMDF 전용인 REG_DWORD UMDF 버전 2.31 이상이 있는 대상 컴퓨터에서 실행되는 UMDF 1.x/2.x 드라이버에서 작동합니다.

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf.

이 값은 지정된 UMDF 드라이버에만 영향을 줍니다.

지연 값(초)을 포함합니다. WUDFHost가 드라이버가 로드된 후 지정된 시간(초)동안 디버거에 연결하려고 합니다.

지정된 지연 기간 동안 호스트 프로세스는 1초에 한 번 사용자 모드 디버거를 찾고 연결된 경우 중단됩니다. 이 기간 내에 사용자 모드 디버거가 연결되지 않고 의 상위 비트가 설정된 경우(0x80000000) 프레임워크는 커널 모드 디버거로 한 번의 침입을 시도합니다. 예제는 위의 HostProcessDbgBreakOnStart 섹션을 참조하세요.

UMDF 레지스트리 값을 변경하여 적용하려면 컴퓨터를 다시 부팅해야 합니다.

HostProcessDbgBreakOnDriverLoad(전역)

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. WDK에서 WDF 검증 도구(WdfVerifier.exe)를 사용하여 설정할 수 있습니다. 이 값은 시스템의 모든 UMDF 드라이버에 영향을 줍니다.

Contains a delay value in seconds. WUDFHost가 드라이버가 로드된 후 지정된 시간(초)을 지연하도록 합니다. HostProcessDbgBreakOnDriverLoad에 대한 동작은 HostProcessDbgBreakOnStart에 설명된 것과 동일하지 않습니다.

HostProcessDbgBreakOnStart 또는 HostProcessDbgBreakOnDriverLoad를 지정하면 프레임워크가 다른 UMDF 시간 제한(예: 플러그 앤 플레이 작업)을 사용하지 않도록 설정합니다. 즉, 드라이버에서 과도한 시간 제한을 발생시키는 경우 이러한 값을 사용하면 드라이버가 대상에 치명적인 충돌을 일으킬 수 있습니다.

HostProcessDbgBreakOnStart

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. You can set it by using the WDF Verifier tool (WdfVerifier.exe) in the WDK. This value affects all UMDF drivers on the system.

Contains a delay value in seconds. During the specified delay period, the host process looks for the user-mode debugger once a second and breaks in if one is connected. 이 기간 내에 사용자 모드 디버거가 연결되지 않고 HostProcessDbgBreakOnStart 의 상위 비트가 설정된 경우(0x80000000) 프레임워크는 커널 모드 디버거로 한 번의 침입을 시도합니다. 예를 들면 다음과 같습니다.

값 결과
0x00000004 프레임워크는 4초 동안 한 번 사용자 모드 디버거에 연결하려고 시도합니다. 프레임워크는 커널 모드 디버거에 연결을 시도하지 않습니다.
0x80000000 프레임워크는 사용자 모드 디버거에 연결하기 위해 한 번의 시도를 합니다. 사용자 모드 디버거가 연결되지 않은 경우 프레임워크는 커널 모드 디버거에 연결을 시도합니다.
0x80000004 프레임워크는 4초 동안 한 번 사용자 모드 디버거에 연결하려고 시도합니다. 사용자 모드 디버거가 4초 내에 연결되지 않은 경우 프레임워크는 커널 모드 디버거에 연결을 시도합니다.

WDK에 포함된 WDF 검증 도구 (WdfVerifier.exe)를 사용하여 이 레지스트리 값을 설정할 수도 있습니다.

LogPages

REG_DWORD

프레임워크가 이벤트 로거에 할당하는 메모리 페이지 수로 설정합니다. 값이 정의되지 않은 경우 프레임워크는 한 페이지의 기본값을 사용합니다. 설정할 수 있는 최대값은 4킬로바이트 크기의 메모리 페이지(x86 및 amd64 프로세서)가 있는 컴퓨터의 경우 16개, 8킬로바이트 크기의 메모리 페이지(ia64 프로세서)가 있는 컴퓨터의 경우 8입니다. (많은 수의 페이지가 지정된 경우 운영 체제에서 크래시 덤프 파일에 로그 내용을 쓰지 않을 수 있습니다.) 다음과 같이 AddService 지시문 및 AddReg 지시문을 사용하여 INF 파일에서 이 값을 설정합니다.

[xxx.NT.Services]
AddService = yyy, 2, zzz.AddService

[zzz.AddService]
DisplayName   = %aaa\bbb%
ServiceType   = 1
StartType     = 3
ErrorControl  = 1
ServiceBinary = %12%\ddd.SYS
AddReg         = eee.AddReg

[eee.AddReg]
HKR, Parameters\Wdf, LogPages,   0x00010001, 3 ; KMDF IFR size

ObjectLeakDetectionLimit

경우에 따라 프레임워크 개체가 잘못 부모가 되며 사용 후 삭제되지 않습니다. ObjectLeakDetectionLimit 및 ObjectsForLeakDetection을 사용하여 최대 개체 수와 이 임계값을 초과할 때 발생할 작업을 지정할 수 있습니다.

REG_DWORD

ObjectsForLeakDetection 키에 설명된 형식의 최대 개체 수를 지정합니다. 이 임계값을 초과하여 디버그 중단 또는 버그 검사를 발생시킬지 여부를 제어하려면 DbgBreakOnError 키를 설정합니다. 제한은 설치된 디바이스 수에 따라 크기가 조정되므로 드라이버가 세 개의 WDFDEVICE 개체를 만드는 경우 한도는 ObjectLeakDetectionLimit에 지정된 값의 3배입니다.

ObjectsForLeakDetection

REG_MULTI_SZ

ObjectLeakDetectionLimit와 함께 사용합니다. 확인할 각 형식 이름을 나열합니다. 예를 들어 WDFDMATRANSACTION WDFDEVICE를 지정할 수 있습니다. 모든 핸들 형식을 지정하려면 를 문자열로 사용합니다 * . ObjectsForLeakDetection 키를 지정하지 않으면 기본값은 WDFREQUEST, WDFWORKITEM, WDFKEY, WDFSTRING, WDFOBJECT 및 WDFDEVICE를 모니터링하는 것입니다.

WDFREQUEST를 지정하는 경우 검증 도구는 드라이버가 만드는 WDFREQUEST 개체만 계산합니다. 이 기능은 현재 WDFMEMORY 개체 형식 추적을 지원하지 않습니다.

TrackHandles

REG_MULTI_SZ

프레임워크 개체 핸들의 하나 이상의 형식 이름 목록으로 설정하고 VerifierOn 이 설정된 경우 프레임워크는 지정된 핸들 형식과 일치하는 모든 개체 핸들에 대한 참조를 추적합니다. 예를 들어 핸들 형식 목록이 "WDFREQUEST WDFQUEUE" 문자열로 구성된 경우 프레임워크는 모든 요청 개체 및 큐 개체에 대한 참조를 추적합니다. 목록에 별표("*")가 포함된 경우 프레임워크는 모든 개체 핸들을 추적합니다.

VerboseOn

REG_DWORD

0이 아닌 값으로 설정된 경우 프레임워크의 이벤트 로거는 내부 코드 경로로 들어오거나 나가는 항목과 같이 드라이버를 디버그하는 데 도움이 되는 추가 정보를 기록합니다. 드라이버를 개발하는 동안에만 이 값을 설정해야 합니다. VerifierOn의 코드 예제를 참조하세요.

VerifierAllocateFailCount

REG_DWORD

값 n으로 설정하고 VerifierOn이 설정된 경우 프레임워크는 n번째 할당 후 드라이버의 개체에 대한 메모리를 할당하려고 할 때마다 실패합니다. 이 오류는 드라이버의 메모리 부족 조건 처리를 테스트하는 데 도움이 됩니다. 예를 들어 VerifierAllocateFailCount 를 2로 설정하면 두 번째 할당 후의 모든 메모리 할당이 실패합니다. VerifierAllocateFailCount의 기본값은 0xffffffff. VerifierAllocateFailCount를 설정한 후 (DWORD) -1로 설정하거나 값을 모두 제거하여 해제할 수 있습니다.

검증 도구는 드라이버가 요청하는 할당과 프레임워크가 드라이버를 대신하여 요청하는 할당을 모두 계산합니다. 또한 드라이버에 대해 발생할 수 있는 할당 수는 프레임워크의 한 릴리스에서 다음 릴리스로 변경될 수 있습니다.

VerifierOn

REG_DWORD

KMDF 검증 도구를 사용하도록 설정하려면 0이 아닌 값으로 설정하여 드라이버의 상태 및 함수 매개 변수의 유효성을 광범위하게 검사합니다. 드라이버를 개발할 때 VerifierOn 및 DbgBreakOnError 를 설정해야 합니다. 다음과 같이 AddService 지시문 및 AddReg 지시문을 사용하여 INF 파일의 Services 섹션에서 이러한 값을 설정합니다.

[xxx_Inst.NT.Services]
AddService = xxx,%SPSVCINST_ASSOCSERVICE%,xxx_Service_Inst

[xxx_Service_Inst]
ServiceType   = %SERVICE_KERNEL_DRIVER%
StartType     = %SERVICE_BOOT_START%
ErrorControl  = %SERVICE_ERROR_NORMAL%
LoadOrderGroup = "Base"
ServiceBinary = %12%\xxx.sys
AddReg         = KMDFVerifierAddReg

[KMDFVerifierAddReg]
HKR, Parameters\Wdf,VerifierOn,0x00010001,1
HKR, Parameters\Wdf,VerboseOn,0x00010001,1
HKR, Parameters\Wdf,DbgBreakOnError,0x00010001,1

VerifyDownLevel

REG_DWORD, 프레임워크 버전 1.9 이상

0이 아닌 값으로 설정하고 드라이버가 현재 버전보다 오래된 프레임워크 버전으로 빌드된 경우 프레임워크의 검증 도구에는 드라이버가 빌드된 후 추가된 테스트가 포함됩니다. 이 값이 없거나 0으로 설정된 경우 프레임워크의 검증 도구에는 드라이버가 빌드될 때 존재했던 테스트만 포함됩니다.

예를 들어 드라이버가 프레임워크 버전 1.7로 빌드되고 프레임워크 버전 1.9가 컴퓨터에 설치된 경우 VerifyDownLevel 을 0이 아닌 값으로 설정하면 드라이버가 실행될 때 검증 도구 버전 1.9에 추가된 테스트가 검증 도구에 포함됩니다.

VerifyOn

REG_DWORD

Wdfassert.h에 정의된 WDFVERIFY 매크로를 사용하도록 설정하거나 0으로 설정하여 매크로를 사용하지 않도록 설정하려면 0이 아닌 값으로 설정합니다. VerifierOn 값이 설정되면 VerifyOn은 암시적으로 0이 아닌 값으로 설정됩니다.