UMDF ドライバーのデバッグを有効にする方法How to Enable Debugging of a UMDF Driver

次の構成を使用して、ユーザー モード ドライバー フレームワーク (UMDF) ドライバーをデバッグすることができます。You can use the following configurations to debug a User-Mode Driver Framework (UMDF) driver. すべての構成には、2 つのマシン、ホストとターゲットが含まれます。All configurations involve two machines, a host and a target. ホスト コンピューターでは、ドライバーのビルドをインストールして、ターゲット コンピューターでドライバーをテストするには、Microsoft Visual Studio と Windows Driver Kit (WDK) を実行するとします。You run Microsoft Visual Studio and the Windows Driver Kit (WDK) to build the driver on the host computer, and then install and test your driver on the target machine.

  • (「展開」) をコピーする Visual Studio を使用してターゲットを開始するには、ホストで Visual Studio 内でのデバッグ セッションをユーザー モード ドライバー。Use Visual Studio to copy ("deploy") the driver to the target and start a user-mode debugging session within Visual Studio on the host.
  • 手動でドライバーをターゲットにコピーします。Manually copy the driver to the target. ターゲットでユーザー モードのデバッグを実行します。Perform user-mode debugging on the target. このシナリオでは、適用する手動でターゲットで実行されているドライバーのホスト プロセスのインスタンスにします。In this scenario, you attach manually to an instance of the driver host process running on the target.
  • ターゲットにドライバーを手動でコピーし、ホストからカーネル モードのデバッグを実行します。Manually copy the driver to the target and then perform kernel-mode debugging from the host.

一緒に使用する後者の 2 つの構成、ターゲット上のユーザー モード デバッガーとカーネル モード デバッガーの両方をホストで実行されています。You can use the latter two configurations together, running both a user-mode debugger on the target and a kernel-mode debugger on the host.

ベスト プラクティスBest Practices

すべての UMDF ドライバーのカーネル デバッガーをアタッチでのテストを実行することをお勧めします。We recommend doing all UMDF driver testing with a kernel debugger attached.

推奨の設定を以下にします。The following are recommended settings. これらを手動で設定したり、使用して、 WDF Verifier コントロール アプリケーション(WDFVerifier.exe) ツールで、WDK を表示またはこれらの設定を変更します。You can set these manually, or use the WDF Verifier Control Application (WDFVerifier.exe) tool in the WDK to view or change these settings.

  • WUDFHost.exe で Application Verifier を有効にします。Enable Application Verifier on WUDFHost.exe:

    AppVerif –enable Heaps Exceptions Handles Locks Memory TLS Leak –for WudfHost.exe
    

    例外が発生した場合 Application Verifier はデバッガーに診断メッセージを送信しで中断されます。If exceptions occur, Application Verifier sends diagnostic messages to the debugger and breaks in.

  • 有効にするDriver Verifierします。Enable Driver Verifier. 開く、コマンド プロンプトウィンドウ (管理者として実行)。Open a Command Prompt window (Run as administrator). ドライバー検証ツール マネージャーを開くことの検証方法を入力します。Type verifier to open the Driver Verifier Manager.

  • カーネル モードのデバッグ セッションを使用している場合は、設定HostFailKdDebugBreakリフレクターが、ドライバーのホスト プロセスを終了する前にカーネル モード デバッガーを中断できるようにします。If you are using a kernel-mode debugging session, set HostFailKdDebugBreak so that the reflector breaks into the kernel-mode debugger before terminating the driver host process. この設定は、UMDF バージョン 1.11 以降を既定で有効です。This setting is enabled by default starting in UMDF version 1.11.

  • 設定してプールを無効にUmdfHostProcessSharingProcessSharingDisabledします。Disable pooling by setting UmdfHostProcessSharing to ProcessSharingDisabled. については、次を参照してください。 INF ファイルで WDF ディレクティブを指定するします。For info, see Specifying WDF Directives in INF Files.

  • 既定では、UMDF デバイスが失敗したときに、フレームワークの設定は最大 5 回再起動を試行します。By default, when a UMDF device fails, the framework attempts to restart it up to five times. 自動再起動をオフに設定してDebugModeFlags 0x01 にします。You can turn off automatic restart by setting DebugModeFlags to 0x01. 詳細については、次を参照してください。デバッグ WDF のドライバーのレジストリ値します。For more info, see Registry Values for Debugging WDF Drivers.

  • お使いのコンピューターを再起動します。Reboot your computer.

F5 キーを押して Visual Studio を使用して自動的にアタッチする (ユーザー モードのデバッグ)Using Visual Studio with F5 to attach automatically (user-mode debugging)

WDK で Visual Studio を使用して、テスト コンピューター上のドライバーをデバッグすることができます、最初を設定してテスト マシンを構成します。Before you can use Visual Studio with the WDK to debug a driver on a test computer, you must first set up and configure your test machine. これを行う方法については、次を参照してください。テスト コンピューターにドライバーを展開するします。For information on how to do this, see Deploying a Driver to a Test Computer.

テスト用コンピューターを構成した後、ホスト コンピューターで Visual Studio を使用して、ドライバーにブレークポイントを設定します。After you have configured your test computer, use Visual Studio on the host computer to set breakpoints in your driver. F5 キーを押すと、Visual Studio は、ドライバーをビルド、対象のコンピューターに展開しますされ、ユーザー モードのデバッグ セッションを開始します。When you press F5, Visual Studio builds the driver, deploys it to the target computer, and starts a user-mode debugging session.

この手法を使用して、UMDF ドライバーを展開するときに、Visual Studio がオンUMDF デバッグ モードドライバー。When you deploy a UMDF driver using this technique, Visual Studio turns on UMDF debug mode for that driver. 既定では、デバッグ モードはことを意味します。By default, debug mode means that:

  • ドライバーは、独自の専用のホスト プロセスで起動します。The driver starts in its own dedicated host process. デバイスのプールは無効になります。Device pooling is turned off.
  • ドライバー クラッシュ後にデバイスが自動的に再起動しないと、エラー報告を無効にします。Devices are not automatically restarted after a driver crash, and error reporting is disabled.
  • フレームワークで説明されているタイムアウトは強制されませんUMDF でホスト プロセスのタイムアウトします。The framework does not enforce the timeouts described in Host Process Timeouts in UMDF.
  • UMDF ホスト プロセスまたはフレームワーク verifier は、無効な操作を検出する場合、UMDF はユーザー モード デバッガーを中断します。If the UMDF host process or the framework verifier detects an invalid operation, UMDF breaks into the user-mode debugger.

デバッグ モードを使用して、ドライバーのインストールには、再起動が必要です。 場合でも、UMDF ドライバーをデバッグすることができます。You can use debug mode to debug a UMDF driver even if driver installation requires a reboot. 生体認証、スマート カード、または入力例で、ユーザーがログオンする前に開始するユーザー モード ドライバーをデバッグすることもできます。You can also debug user-mode drivers that start before the user logs in, for example biometrics, smartcard, or input.

WinDbg を使用して手動でアタッチする (ユーザー モードのデバッグ)Using WinDbg to attach manually (user-mode debugging)

ターゲット コンピューターでは、ドライバーをホストする WUDFHost のインスタンスに WinDbg を手動でアタッチできます。On the target machine, you can manually attach WinDbg to the instance of WUDFHost that hosts the driver. アタッチすると、デバッガーを中断して、ドライバーでブレークポイントを設定することができます。When you attach, you break into the debugger and you can set breakpoints in your driver.

ドライバーの初期化の直後に発生するため WUDFHost を読み込む、初期化コードをデバッグする時間を手動でアタッチすることはできません。Because driver initialization occurs shortly after WUDFHost loads, it is not feasible to attach manually in time to debug initialization code. 代わりに、ホスト プロセスがいくつかのホストの初期化またはドライバーの読み込み時に秒の待機にレジストリ値を設定することができます。Instead, you can set a registry value to cause the host process to wait some number of seconds at host initialization or driver load time. この遅延は、WinDbg を WUDFHost プロセスの適切なインスタンスにアタッチする時間を示します。This delay gives you time to attach WinDbg to the correct instance of the WUDFHost process.

次の手順に従います。Follow these steps:

  1. ターゲット コンピューターのレジストリに次のように設定します。 HostProcessDbgBreakOnStartまたはHostProcessDbgBreakOnDriverLoad秒と再起動のいくつかの数。In the registry on the target computer, set HostProcessDbgBreakOnStart or HostProcessDbgBreakOnDriverLoad to some number of seconds and reboot.
  2. 対象のコンピューターに管理者として、WinDbg を開きます。On the target computer, open WinDbg as Administrator.
  3. ファイル] メニューの [選択プロセスにアタッチします。On the File menu, choose Attach to Process. 選択実行可能ファイルによってWUDFHost.exe (できない可能性がありますいずれか) という名前のすべてのプロセスを見つけます。Select By Executable, and locate all processes that are named WUDFHost.exe (there might not be any). WUDFHost.exe という名前のプロセスがある場合は、今後の参照用のプロセス id を書き留めます。If there are any processes named WUDFHost.exe, write down their process identifiers for future reference.
  4. デバイス マネージャーでは、ドライバーを有効にします。In Device Manager, enable the driver.
  5. 手順 2 を繰り返し、WUDFHost.exe の新しいインスタンスを検索します。Repeat step 2 and locate a new instance of WUDFHost.exe. WUDFHost.exe の新しいインスタンスが表示されない場合はクリックしてキャンセル、選択プロセスにアタッチもう一度です。If you don't see a new instance of WUDFHost.exe, click Cancel, and choose Attach to Process again. WUDFHost.exe の新しいインスタンスを検索するときに選択し、をクリックしてOKします。When you find the new instance of WUDFHost.exe, select it, and click OK.

場合デバイス プールはセット内に使用して、 HostProcessDbgBreakOnDriverLoadレジストリ値、その他のドライバーの読み込み中にデバッガーを中断表示可能性があります。If device pooling is in use and you set the HostProcessDbgBreakOnDriverLoad registry value, you may see debugger breaks due to other drivers loading. UMDF デバッグ モードを使用してデバイスのプールを無効にすることができます。You can turn off device pooling by using UMDF debug mode.

デバッグ モードを使用する、Visual Studio で f5 キーを押してオプションを使用するか設定、 DebugModeFlagsDebugModeBinariesレジストリの値。To use debug mode, either use the F5 option in Visual Studio, or set the DebugModeFlags and DebugModeBinaries values in the registry.

UMDF レジストリ値の詳細については、次を参照してください。デバッグの WDF ドライバー (KMDF および UMDF) のレジストリ値します。For detailed information about UMDF registry values, see Registry Values for Debugging WDF Drivers (KMDF and UMDF).

WinDbg を使用して (カーネル モードのデバッグ) ホスト コンピューターからリモートでデバッグするにはUsing WinDbg to remotely debug from a host machine (kernel-mode debugging)

リモート ホストからカーネル モードのデバッグ セッションを確立し、ドライバーをホストしている Wudfhost のインスタンスに現在のプロセスを設定します。From a remote host, establish a kernel-mode debugging session and then set current process to the instance of Wudfhost that is hosting your driver. リモート カーネル デバッガーからデバッグする場合は設定できますHostProcessDbgBreakOnDriverStartまたはHostProcessDbgBreakOnDriverLoad 0x80000000 のタイムアウトを指定しないが、カーネルに分割するにはデバッガー。If you are debugging from a remote kernel debugger, you can set HostProcessDbgBreakOnDriverStart or HostProcessDbgBreakOnDriverLoad to 0x80000000 to specify no timeout, but break into the kernel debugger.

UMDF 1.11 以降では、カーネル デバッガーを分割する前に、reflector は自動的に切り替わりますプロセスのコンテキストのホスト プロセス。In UMDF 1.11 or later, before breaking into the kernel debugger, the reflector automatically switches the process context to that of the host process. 最初に発行することがなく UMDF デバッガー拡張機能のコマンドをすぐに使用する結果として、 .process プロセスのコンテキストを変更するコマンド。As a result, you can use UMDF debugger extension commands immediately, without first issuing the .process command to change the process context.

これらの手順に従います。Use these steps:

  1. プールを無効にします。Disable pooling. オンにするDebugModeFlags一覧で、ドライバーとDebugModeBinariesturn on DebugModeFlags and list your driver in DebugModeBinaries

  2. ドライバーは、UMDF 1.11 以降を使用している場合HostFailKdDebugBreak既定で有効です。If your driver uses UMDF 1.11 or later, HostFailKdDebugBreak is enabled by default. この手順をスキップします。Skip this step.

    ドライバーは、UMDF 1.9 またはそれ以前を使用している場合は、設定HostFailKdDebugBreakを 1 にします。If your driver uses UMDF 1.9 or earlier, set HostFailKdDebugBreak to 1.

  3. タイムアウトに関連する問題をデバッグする場合は、オフにするHostProcessDbgBreakOnDriverStartHostProcessDbgBreakOnDriverLoadします。If you are debugging problems related to timeouts, turn off HostProcessDbgBreakOnDriverStart and HostProcessDbgBreakOnDriverLoad. (とHostProcessDbgBreakOnDriverStartまたはHostProcessDbgBreakOnDriverLoad 0 以外の場合は、フレームワーク、reflector は、ユーザー モード中にホストを終了しないように、タイムアウトを無効にします。デバッガーがアタッチされているホスト プロセスにします。)これら 2 つの値を使用する代わりに、ドライバーの初期化コードをデバッグする必要がある場合、ドライバーの読み込み前に、WinDbg で次のコマンドの発行を再試行してください: sxe ld: MyDriver.dll (モジュールの読み込み時に中断)(When HostProcessDbgBreakOnDriverStart or HostProcessDbgBreakOnDriverLoad is non-zero, the framework disables timeouts so that the reflector does not terminate the host while a user-mode debugger is attached to the host process.) If you need to debug driver initialization code, instead of using these two values, try issuing the following command in WinDbg before your driver loads: sxe ld:MyDriver.dll (break on module load)

  4. レジストリの変更を加えた場合に再起動します。Reboot if you made any registry changes.

  5. 上記で作成した、選択に応じてドライバーをロードまたはアンロード、ターゲットの場合、リモートのカーネル デバッガーを中断します。Depending on the selections you made above, your remote kernel debugger should break in when the driver loads or unloads on the target.