初めての USB クライアント ドライバーの記述方法 (KMDF)

このトピックでは、Microsoft Visual Studio Professional 2019 で提供されている USB Kernel-Mode ドライバー テンプレートを使用して、単純なカーネル モード ドライバー フレームワーク (KMDF) ベースのクライアント ドライバーを作成します。 クライアント ドライバーをビルドしてインストールした後、デバイス マネージャーでクライアント ドライバーを表示し、デバッガーでドライバーの出力を表示します。

テンプレートによって生成されるソース コードの詳細については、「 USB クライアント ドライバーの KMDF テンプレート コードについて」を参照してください。

前提条件

カーネル モード ドライバーの開発、デバッグ、インストールには、次の 2 つのコンピューターが必要です。

  • Windows オペレーティング システムWindows 7 以降のバージョンを実行しているホスト コンピューター。 ホスト コンピューターは開発環境であり、ドライバーを記述してデバッグします。
  • Vista 以降のバージョンのWindows Windows実行しているターゲット コンピューター。 ターゲット コンピューターには、デバッグするカーネル モード ドライバーがあります。

開始する前に、次の要件を満たしていることを確認してください。

ソフトウェア要件

  • ホスト コンピューターは開発環境をホストし、2019 Visual Studio Professional。
  • ホスト コンピューターに、Windows 8用の最新のWindows ドライバー キット (WDK) があります。 キットには、KMDF ドライバーの開発、ビルド、デバッグに必要なヘッダー、ライブラリ、ツール、ドキュメント、デバッグ ツールが含まれています。 WDK の最新バージョンを取得するには、「Windows ドライバー キット (WDK) をダウンロードする」を参照してください。
  • ホスト コンピューターには、Windows用のデバッグ ツールの最新バージョンがあります。 WDK から最新バージョンを取得することも、Windows用のデバッグ ツールをダウンロードしてインストールすることもできます。
  • 対象のコンピューターが Vista 以降のバージョンのWindows Windows実行されています。
  • ホスト コンピューターとターゲット コンピューターは、カーネル デバッグ用に構成されています。 詳細については、「Visual Studioでのネットワーク接続の設定」を参照してください。

ハードウェア要件

クライアント ドライバーを記述する USB デバイスを取得します。 ほとんどの場合、USB デバイスとそのハードウェア仕様が提供されます。 この仕様では、デバイスの機能とサポートされているベンダー コマンドについて説明します。 仕様を使用して、USB ドライバーの機能と関連する設計上の決定を決定します。

USB ドライバーの開発を初めて使用する場合は、OSR USB FX2 学習キットを使用して、WDK に含まれる USB サンプルを調わせてください。 学習キットは OSR Online から入手できます。 これには、USB FX2 デバイスと、クライアント ドライバーを実装するために必要なすべてのハードウェア仕様が含まれています。

Microsoft USB テスト ツール (MUTT) デバイスを取得することもできます。 MUTT ハードウェアは 、JJG テクノロジから購入できます。 デバイスにファームウェアがインストールされていません。 ファームウェアをインストールするには、 この Web サイト から MUTT ソフトウェア パッケージをダウンロードし、MUTTUtil.exe実行します。 詳細については、パッケージに含まれているドキュメントを参照してください。

推奨される読み取り

Instructions

手順 1: Visual Studio Professional 2019 USB ドライバー テンプレートを使用して KMDF ドライバー コードを生成する

KMDF ドライバー コードの生成手順については、「 テンプレートに基づく KMDF ドライバーの作成」の手順を参照してください。

USB 固有のコードの場合は、Visual Studio Professional 2019 で次のオプションを選択します

  1. [新しいProject] ダイアログ ボックスの上部にある検索ボックスに、「USB」と入力します
  2. 中央のウィンドウで、 カーネル モード ドライバー、USB (KMDF) を選択します。
  3. [次へ] を選択します。
  4. プロジェクト名を入力し、保存場所を選択して、[ 作成] を選択します。

次のスクリーン ショットは、USB Kernel-Mode ドライバー テンプレートの [新しいProject] ダイアログ ボックスを示しています。

visual studio new project options.

visual studio new project options second screen.

このトピックでは、Visual Studio プロジェクトの名前が "MyUSBDriver_" であることを前提としています。 次のファイルが含まれます。

ファイル 説明
Public.h クライアント ドライバーと USB デバイスと通信するユーザー アプリケーションによって共有される一般的な宣言を提供します。
<Project name.inf> ターゲット コンピューターにクライアント ドライバーをインストールするために必要な情報が含まれています。
Trace.h トレース関数とマクロを宣言します。
Driver.h;Driver.c ドライバーエントリポイントとイベントコールバックルーチンを宣言および定義します。
Device.h;Device.c prepare-hardware イベントのイベント コールバック ルーチンを宣言して定義します。
Queue.h;Queue.c フレームワークのキュー オブジェクトによって発生するイベントのイベント コールバック ルーチンを宣言および定義します。

手順 2: INF ファイルを変更して、デバイスに関する情報を追加する

ドライバーをビルドする前に、デバイスに関する情報 (具体的にはハードウェア ID 文字列) を使用してテンプレート INF ファイルを変更する必要があります。

ソリューション エクスプローラーの [ドライバー ファイル] で、INF ファイルをダブルクリックします。

INF ファイルでは、製造元とプロバイダー名、デバイス セットアップ クラスなどの情報を指定できます。 指定する必要がある情報の 1 つは、デバイスのハードウェア識別子です。

ハードウェア ID 文字列を指定するには:

  1. USB デバイスをホスト コンピューターに接続し、デバイスWindows列挙できるようにします。

  2. デバイス マネージャーを開き、デバイスのプロパティを開きます。

  3. [ 詳細 ] タブで、[プロパティ] の下 の [ハードワード ID] を 選択します

    デバイスのハードウェア ID がリスト ボックスに表示されます。 ハードウェア ID 文字列を選択して長押し (または右クリック) し、コピーします。

  4. 次の行の USB\VID_vvvv& PID_pppp をハードウェア ID 文字列に置き換えます。

    [Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp

手順 3: USB クライアント ドライバー コードをビルドする

ドライバーをビルドするには

  1. Visual Studio Professional 2019 でドライバー プロジェクトまたはソリューションを開く
  2. ソリューション エクスプローラーでソリューションを長押し (または右クリック) し、Configuration Managerを選択します。
  3. Configuration Managerから、対象のビルドの種類に対応するアクティブ ソリューション構成 (Windows 8 デバッグWindows 8 リリースなど) とアクティブ ソリューション プラットフォーム (Win32 など) を選択します。
  4. [ビルド] メニューの [ソリューションのビルド] を選択します。

詳しくは、「ドライバーのビルド」をご覧ください。

手順 4: テストとデバッグ用にコンピューターを構成する

ドライバーをテストしてデバッグするには、ホスト コンピューターでデバッガーを実行し、ターゲット コンピューターでドライバーを実行します。 これまでは、ホスト コンピューターでVisual Studioを使用してドライバーをビルドしてきました。 次に、ターゲット コンピューターを構成する必要があります。 ターゲット コンピューターを構成するには、「 ドライバーの展開とテスト用にコンピューターをプロビジョニングする」の手順に従います。

手順 5: カーネル デバッグのトレースを有効にする

テンプレート コードには、関数呼び出しの追跡に役立つトレース メッセージ (TraceEvents) がいくつか含まれています。 ソース コード内のすべての関数には、ルーチンのエントリと終了をマークするトレース メッセージが含まれています。 エラーの場合、トレース メッセージにはエラー コードと意味のある文字列が含まれます。 ドライバー プロジェクトに対して WPP トレースが有効になっているため、ビルド プロセス中に作成された PDB シンボル ファイルには、トレース メッセージの書式設定手順が含まれています。 WPP トレース用にホスト コンピューターとターゲット コンピューターを構成した場合、ドライバーはトレース メッセージをファイルまたはデバッガーに送信できます。

WPP トレース用にホスト コンピューターを構成するには

  1. PDB シンボル ファイルからトレース メッセージの書式設定命令を抽出して、トレース メッセージ形式 (TMF) ファイルを作成します。

    Tracepdb.exeを使用して TMF ファイルを作成できます。 このツールは、WDK の<インストール フォルダー> Windows Kits\8.0\bin\<architecture> フォルダーにあります。 次のコマンドは、ドライバー プロジェクトの TMF ファイルを作成します。

    tracepdb -f [PDBFiles] -p [TMFDirectory]

    f オプションは、PDB シンボル ファイルの場所と名前を指定します。 p オプションは、Tracepdb によって作成される TMF ファイルの場所を指定します。 詳細については、「 Tracepdb コマンド」を参照してください。

    指定した場所に、3 つのファイル (プロジェクト内の .c ファイルごとに 1 つ) が表示されます。 GUID ファイル名が与えられます。

  2. デバッガーで、次のコマンドを入力します。

    1. .load Wmitrace

      Wmitrace.dll拡張機能を読み込みます。

    2. .chain

      デバッガー拡張機能が読み込まれたことを確認します。

    3. !wmitrace.searchpath +<TMF ファイルの場所>

      デバッガー拡張機能の検索パスに TMF ファイルの場所を追加します。

      次のような内容が出力されます。

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

WPP トレース用にターゲット コンピューターを構成するには

  1. ターゲット コンピューターに Tracelog ツールがあることを確認します。 このツールは、WDK の <install_folder> Windows Kits\8.0\Tools\<arch> フォルダーにあります。 詳細については、「 Tracelog コマンド構文」を参照してください。

  2. コマンド ウィンドウを開き、管理者として実行します。

  3. 次のコマンドを入力します。

    tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

    このコマンドは、MyTrace という名前のトレース セッションを開始します。

    guid 引数は、クライアント ドライバーであるトレース プロバイダーの GUID を指定します。 Visual Studio Professional 2019 プロジェクトで Trace.h から GUID を取得できます。 別のオプションとして、次のコマンドを入力し、.guid ファイルに GUID を指定できます。 ファイルには、ハイフン形式の GUID が含まれています。

    tracelog -start MyTrace -guid c:\drivers\Provider.guid -flag 0xFFFF -level 7-rt -kd

    トレース セッションを停止するには、次のコマンドを入力します。

    tracelog -stop MyTrace

手順 6: ターゲット コンピューターにドライバーを展開する

  1. ソリューション エクスプローラー ウィンドウで、プロジェクト名>Package を長押し (または右クリック)< し、[プロパティ] を選択します。
  2. 左側のウィンドウで、 Configuration Properties > Driver Install > Deployment に移動します。
  3. [展開を有効にする] をオンにし、[ドライバー ストアにインポート] をオンにします。
  4. [ リモート コンピューター名] には、ターゲット コンピューターの名前を指定します。
  5. [Install and Verify (インストールと確認)] を選びます。
  6. [OK] を選択します。
  7. [デバッグ] メニューの [デバッグ開始] をクリックするか、キーボードで F5 キーを押します。

メモ[ハードウェア ID ドライバーの更新] で、デバイスのハードウェア ID を指定しないでください。 ハードウェア ID は、ドライバーの情報 (INF) ファイルでのみ指定する必要があります。

Visual Studio Professional 2019 でターゲット システムにドライバーを展開する方法の詳細については、「テスト コンピューターへのドライバーの展開」を参照してください。

デバイス マネージャーを使用して、ターゲット コンピューターにドライバーを手動でインストールすることもできます。 コマンド プロンプトからドライバーをインストールする場合は、次のユーティリティを使用できます。

  • PnPUtil

    このツールにはWindowsが付属しています。 Windows\System32 にあります。 このユーティリティを使用して、ドライバーストアにドライバーを追加できます。

    C:\>pnputil /a m:\MyDriver_.inf
    Microsoft PnP Utility
    
    Processing inf : MyDriver_.inf
    Driver package added successfully.
    Published name : oem22.inf
    

    詳細については、 PnPUtil の例を参照してください。

  • DevCon Update

    このツールには WDK が付属しています。 これを使用して、ドライバーのインストールと更新を行うことができます。

    devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6
    

手順 7: デバイス マネージャーでドライバーを表示する

  1. 次のコマンドを入力して、デバイス マネージャーを開きます。

    devmgmt

  2. デバイス マネージャーに次のノードのノードが表示されていることを確認します。

    サンプル

    MyUSBDriver_Device

手順 8: デバッガーで出力を表示する

Visual Studio最初に[出力]ウィンドウに進行状況が表示されます。 次に、 デバッガーイミディエイト ウィンドウが開きます。 ホスト コンピューターのデバッガーにトレース メッセージが表示されることを確認します。 出力は次のようになります。ここで、"MyUSBDriver_" はドライバー モジュールの名前です。

[3]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverContextCleanup Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Exit
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Entry
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Exit

USB クライアント ドライバーの KMDF テンプレート コードについて
USB クライアント ドライバー開発の概要