WDF ドライバーをデバッグするためのレジストリ値

  • [アーティクル]

この記事では、WDF ドライバーが設定できるレジストリ値について説明します。 これは KMDF ドライバーと UMDF バージョン 2 以降の UMDF ドライバーに適用されます。

以下の各セクションで特に指定がない限り、次のレジストリ値は、ドライバーの Parameters\Wdf サブキーの下にあります。

  • KMDF ドライバーの場合、このサブキーはドライバーのサービス名の下の HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services にあります。
  • UMDF ドライバーの場合、このサブキーはドライバーのサービス名の下の HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services にあります。

ドライバーのサブキーは、ドライバー バイナリのファイル名がサービス名と異なる場合でも、常にドライバーのサービス名を使用します。

DbgBreakOnError

REG_DWORD

ゼロ以外の値に設定すると、ドライバーが WdfVerifierDbgBreakPoint を呼び出す場合にフレームワークがデバッガーを中断します。 (VerifierOn 値が設定されている場合、DbgBreakOnError 値が存在しない場合でも、フレームワークはデバッガーを中断します)。VerifierOn セクションのコード例を参照してください。

DbgPrintOn

REG_DWORD

  • KMDF ドライバーの場合、HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\Diagnostics レジストリキーの下にこの値を設定します。
  • UMDF ドライバーの場合、HKLM\System\CurrentControlSet\Control\Wdf\Umdf\Diagnostics レジストリキーの下にこの値を設定します。

ドライバーは、オプションの Diagnostics サブキーを作成する必要がある場合もあります。

ゼロ以外の値に設定すると、フレームワークのローダーは、ドライバーをロードしてフレームワーク ライブラリのバージョンにバインドしている間、またはドライバーをアンロードしている間に、カーネル デバッガーにさまざまなメッセージを送信します。

DbgWaitForSignalTimeoutInSec

REG_DWORD、フレームワークバージョン 1.11 以降

Windows 8 では、VerifierOn と DbgBreakOnError がゼロ以外の値に設定されている場合、ドライバーは 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 のみ

このレジストリ値は HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode にあります。

Value 説明
0x01 デバッグモードを有効にします。 この設定により、UMDF ドライバーでのデバイス プーリングの使用 で説明されている自動再起動機能をオフになります。
0x02 デバイス プーリングを無効にします。 デバイス プーリングの詳細については、「UMDF ドライバーでのデバイス プーリングの使用」を参照してください。
0x04 タイムアウトを無効にします。

Microsoft Visual Studio で F5 オプションを使用すると、デプロイされたドライバーに 3 つのフラグのすべてが設定されます。

EnhancedVerifierOptions

EG_DWORD、フレームワーク バージョン 1.9 以降

この値にはビットマップが含まれます。 各ビットは、ユーザーがビットを設定することで有効にできる、追加の検証オプションを示しています。

ビット値:

0x1: 設定されている場合、ベリファイアーは、ドライバーの各イベント コールバック関数が次のことを行うかどうかをチェックします:

  • 呼び出されたときと同じ IRQL で返します。 値が異なる場合、WDF_VIOLATION バグ チェックがエラーコード 0xE で発生します。

  • 戻る前に、入ったすべての クリティカル領域 から出ます。 コールバック関数がクリティカル領域に入って戻ってきた場合、WDF_VIOLATION バグ チェックが発生し、エラーコード 0xF が表示されます。

0x10000: 設定されており、ドライバーが I/O キューの 保証付フォワード プログレス を有効にしている場合、フレームワークはキューの各 I/O リクエストに対してメモリ不足の状況をシミュレートします。

0x20000: 設定されており、ドライバーが I/O キューの保証付フォワードプログレスを有効にしている場合、フレームワークはランダムに選択されたいくつかの I/O 要求に対してメモリ不足の状況をシミュレートします。

ForceLogsInMiniDump

REG_DWORD

ゼロ以外の値に設定すると、フレームワークはイベント ロガーからの情報をクラッシュ ダンプ ファイルに含めます。

HostFailKdDebugBreak

REG_DWORD、UMDF のみ

このレジストリ値は HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF にあります。

この値がゼロ以外で、カーネル デバッガーがマシンに接続されている場合、リフレクターはホスト プロセスを停止する前にカーネル デバッガーを中断します。 既定では、HostFailKdDebugBreak は、Windows 7 以前の OS では無効になっています。 Windows 8 から、HostFailKdDebugBreak が既定で有効になりました。

ホスト プロセスが予期せず終了した場合 (たとえば、UMDF 以外のコンポーネントや未処理の例外などによる) も、リフレクターはカーネル デバッガーを中断します。 停止しようとしているホスト プロセスに複数のデバイス スタックがプールされている場合、リフレクターは、ホスト プロセスにロードされたデバイス スタックごとに 1 回ずつ、デバッガーを複数回中断します。

HostProcessDbgBreakOnDriverLoad (ドライバー固有)

REG_DWORD、UMDF のみ、UMDF バージョン 2.31 以降のターゲット コンピューター上で実行されている任意の UMDF 1.x/2.x ドライバーで動作

このレジストリ値は HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf にあります。

この値は指定された UMDF ドライバーにのみ影響します。

秒単位の遅延値が含まれます。 ドライバーがロードされた後、指定された秒数の間は WUDFHost がデバッガーへの接続を試行します。

指定された遅延期間中、ホスト プロセスは 1 秒に 1 回ユーザー モード デバッガーを検索し、接続されている場合は中断します。 この期間内にユーザー モード デバッガーが接続されず、上位ビット (0x80000000) が設定されている場合、フレームワークはカーネル モード デバッガーの中断を 1 回試行します。 例については、上記の HostProcessDbgBreakOnStart のセクションを参照してください。

UMDF レジストリ値の変更を有効にするには、コンピューターを再起動する必要があります。

HostProcessDbgBreakOnDriverLoad (グローバル)

REG_DWORD、UMDF のみ

このレジストリ値は HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa} にあります。 これは、WDK の WDF ベリファイアー ツール (WdfVerifier.exe) を使用して設定できます。 この値は、システム上のすべての UMDF ドライバーに影響します。

秒単位の遅延値が含まれます。 ドライバーがロードされた後、WUDFHost が指定された秒数だけ遅延します。 HostProcessDbgBreakOnDriverLoad の動作は、HostProcessDbgBreakOnStart の動作と同じです。

HostProcessDbgBreakOnStart または HostProcessDbgBreakOnDriverLoad を指定すると、フレームワークは他の UMDF タイムアウト (たとえば、プラグ アンド プレイ操作) を無効にします。 これは、ドライバーが過剰なタイムアウトを引き起こす場合にこれらの値を使用すると、ドライバーがターゲット上で致命的なクラッシュを引き起こす可能性があることを意味します。

HostProcessDbgBreakOnStart

REG_DWORD、UMDF のみ

このレジストリ値は HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa} にあります。 これは、WDK の WDF ベリファイアー ツール (WdfVerifier.exe) を使用して設定できます。 この値は、システム上のすべての UMDF ドライバーに影響します。

秒単位の遅延値が含まれます。 指定された遅延期間中、ホスト プロセスは 1 秒に 1 回ユーザー モード デバッガーを検索し、接続されている場合は中断します。 この期間内にユーザー モード デバッガーがアタッチされず、HostProcessDbgBreakOnStart の上位ビット (0x80000000) が設定されると、フレームワークはカーネルモード デバッガーの中断を 1 回試行します。 次に例を示します。

Value 結果
0x00000004 フレームワークは、1 秒に 1 回、4 秒間、ユーザーモード デバッガーへの接続を試行します。 フレームワークはカーネル モード デバッガーへの接続を試行しません。
0x80000000 フレームワークは、ユーザー モード デバッガーへの接続を 1 回試行します。 ユーザーモード デバッガーが接続されていない場合、フレームワークはカーネルモード デバッガーへの接続を試行します。
0x80000004 フレームワークは、1 秒に 1 回、4 秒間、ユーザーモード デバッガーへの接続を試行します。 ユーザーモード デバッガーが 4 秒以内に接続されない場合、フレームワークはカーネルモード デバッガーへの接続を試行します。

このレジストリ値は、WDK に含まれている WDF Verifier tool (WdfVerifier.exe) を使用して設定することもできます。

LogPages

REG_DWORD

フレームワークがイベント ロガーに割り当てるメモリ ページの数を設定します。 値が未定義の場合、フレームワークは既定値の 1 ページを使用します。 設定できる最大値は、4 キロバイト サイズのメモリ ページを備えたコンピューター (x86 および amd64 プロセッサー) の場合は 16、8 キロバイト サイズのメモリ ページを備えたコンピューター (ia64 プロセッサ) の場合は 8 です。 (多数のページが指定されている場合、オペレーティング システムはログの内容をクラッシュ ダンプ ファイルに書き込まない可能性があります。) この値を設定するには、AddService directive と AddReg directive を使用します。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 キーを設定します。 この制限はインストールされているデバイスの数に応じて変化するため、ドライバーが 3 つの WDFDEVICE オブジェクトを作成する場合、制限は ObjectLeakDetectionLimit で指定された値の 3 倍になります。

ObjectsForLeakDetection

REG_MULTI_SZ

ObjectLeakDetectionLimit と組み合わせて使用します。 検証する各タイプ名をリストアップします。 たとえば、WDFDMATRANSACTION WDFDEVICE を指定できます。 ハンドルの型をすべて指定するには、文字列として * を使用します。 ObjectsForLeakDetection キーが指定されていない場合、既定では WDFREQUEST、WDFWORKITEM、WDFKEY、WDFSTRING、WDFOBJECT、および WDFDEVICE を監視します。

WDFREQUEST を指定した場合、検索ツールでは、ドライバーによって作成される WDFREQUEST オブジェクトの数だけが数えられます。 この機能は現在のところ、WDFMEMORY オブジェクトを追跡できます。

TrackHandles

REG_MULTI_SZ

フレームワーク オブジェクト ハンドルの 1 つ以上の型名のリストに設定され、VerifierOn が設定されている場合、フレームワークは、指定されたハンドル型に一致するすべてのオブジェクト ハンドルへの参照を追跡します。 たとえば、ハンドル タイプ リストが「WDFREQUEST WDFQUEUE」文字列で構成されている場合、フレームワークはすべてのリクエスト オブジェクトとキュー オブジェクトへの参照を追跡します。 リストにアスタリスク (「*」) が含まれている場合、フレームワークはすべてのオブジェクト ハンドルを追跡します。

VerboseOn

REG_DWORD

ゼロ以外の値に設定すると、フレームワークの event logger は、内部コード パスへのエントリや内部コード パスからの終了など、ドライバーのデバッグに役立つ追加情報を記録します。 この値を設定するのは、ドライバーを開発している間だけにしてください。 VerifierOn のコード例を参照してください。

VerifierAllocateFailCount

REG_DWORD

値 n が設定され、VerifierOn が設定されている場合、フレームワークは、nth 回目の割り当て以降、ドライバーのオブジェクトにメモリを割り当てる試みはすべて失敗します。 この失敗は、ドライバがメモリ不足の状況に対応できるかどうかをテストするのに役立ちます。 たとえば、VerifierAllocateFailCount を 2 に設定すると、2 回目の割り当て以降のメモリ割り当てはすべて失敗します。 VerifierAllocateFailCount の既定値は 0xffffff です。 VerifierAllocateFailCount を設定した後、(DWORD) -1 に設定するか、値を完全に削除することでオフにできます。

ベリファイアーは、ドライバーが要求した割り当てと、ドライバーに代わってフレームワークが要求した割り当ての両方をカウントすることに注意してください。 また、ドライバーに対して発生する可能性のある割り当ての数は、フレームワークのリリースごとに変わる可能性があることも注意してください。

VerifierOn

REG_DWORD

ドライバーの状態と関数パラメーターを広範囲に検証する KMDF Verifier を有効にするには、ゼロ以外の値を設定します。 ドライバーを開発するときは、VerifierOn と DbgBreakOnError を設定する必要があります。 AddService directive と AddReg directive を使用して、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

EG_DWORD、フレームワーク バージョン 1.9 以降

ゼロ以外の値に設定された場合、そしてドライバが現在のバージョンより古いバージョンのフレームワークでビルドされた場合、フレームワークのベリファイアーは、ドライバがビルドされた後に追加されたテストを含みます。 この値が存在しないか、ゼロに設定されている場合、フレームワークのベリファイアーには、ドライバーのビルド時に存在したテストのみが含まれます。

たとえば、ドライバーがフレームワークのバージョン 1.7 でビルドされ、フレームワークのバージョン 1.9 がコンピューターにインストールされている場合、VerifyDownLevel をゼロ以外に設定すると、ドライバーの実行時に、ベリファイアーのバージョン 1.9 に追加されたテストがベリファイアーに含まれるようになります。

VerifyOn

REG_DWORD

Wdfassert.h で定義されている WDFVERIFY マクロを有効にするにはゼロ以外の値を設定し、マクロを無効にするにはゼロを設定します。 VerifierOn 値が設定されている場合、VerifyOn は暗黙的にゼロ以外に設定されます。