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.

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

EnhancedVerifierOptions

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

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

비트 값:

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

• 호출된 동일한 IRQL에서 를 반환합니다. 값이 다른 경우 오류 코드가 0xE WDF_VIOLATION 버그 검사가 발생합니다.

• 반환하기 전에 은 입력하는 모든 중요한 지역을 종료합니다. 콜백 함수가 입력한 중요한 지역 내에서 반환되는 경우 오류 코드가 0xF WDF_VIOLATION 버그 검사가 발생합니다.

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) 프레임워크는 커널 모드 디버거로 한 번의 침입을 시도합니다. 예를 들면 다음과 같습니다.

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이 아닌 값으로 설정됩니다.