初めての USB クライアント ドライバーの記述方法 (KMDF)
この記事では、Microsoft Visual Studio で提供されている USB カーネル モード ドライバー テンプレートを使用して、シンプルなカーネル モード ドライバー フレームワーク (KMDF) ベースのクライアント ドライバーを作成します。 クライアント ドライバーを作成してインストールした後、デバイス マネージャーでクライアント ドライバーを表示し、デバッガーでドライバーの出力を確認します。
テンプレートによって生成されるソース コードの詳細については、「USB クライアント ドライバーの KMDF テンプレート コードについて」を参照してください。
前提条件
カーネル モード ドライバーの開発、デバッグ、インストールには、次の 2 つのコンピューターが必要です。
- Windows 7 以降のバージョンの Windows オペレーティング システムを実行しているホスト コンピューター。 ホスト コンピューターは開発環境であり、ドライバーを記述してデバッグします。
- Windows Vista 以降のバージョンの Windows を実行しているターゲット コンピューター。 ターゲット コンピューターに、デバッグが必要なカーネル モード ドライバーがあります。
始める前に、次の要件を満たしていることを確認します。
ソフトウェア要件
- ホスト コンピューターに開発環境がホストされており、Visual Studio がある。
- ホスト コンピューターに最新の Windows Driver Kit (WDK) がある。 このキットには、KMDF ドライバーの開発、ビルド、デバッグに必要なヘッダー、ライブラリ、ツール、ドキュメント、デバッグ ツールが含まれています。 最新バージョンの WDK を入手するには、「Windows Driver Kit (WDK) のダウンロード」をご覧ください。
- ホスト コンピューターに、Windows 用のデバッグ ツールの最新バージョンがある。 WDK から最新バージョンを取得することも、Windows 用デバッグ ツールをダウンロードしてインストールすることもできます。
- ターゲット コンピューターで Windows Vista 以降のバージョンの Windows が実行されている。
- ホスト コンピューターとターゲット コンピューターがカーネル デバッグ用に構成されている。 詳しくは、「Visual Studio でのネットワーク接続の設定」をご覧ください。
ハードウェア要件
クライアント ドライバーを作成する USB デバイスを取得します。 ほとんどの場合、USB デバイスとそのハードウェア仕様が提供されています。 この仕様では、デバイスの機能とサポートされているベンダー コマンドについて説明します。 この仕様を使用して、USB ドライバーの機能を確定し、関連する設計上の意思決定を行います。
USB ドライバーの開発を初めて使用する場合は、OSR USB FX2 学習キットを使用して、WDK に含まれる USB サンプルを調査します。 学習キットは OSR Online から入手できます。 USB FX2 デバイスと、クライアント ドライバーを実装するために必要なすべてのハードウェア仕様が含まれています。
マイクロソフト USB テスト ツール (MUTT) デバイスを入手することもできます。 MUTT ハードウェアは JJG Technologies から購入できます。 デバイスにはファームウェアがインストールされていません。 ファームウェアをインストールするには、この Web サイトから MUTT ソフトウェア パッケージをダウンロードし、MUTTUtil.exe を実行します。 詳細については、パッケージに含まれているドキュメントを参照してください。
推奨資料
- すべてのドライバー開発者のための概念
- デバイス ノードとデバイス スタック
- Windows 上のドライバーの概要
- カーネル モード ドライバー フレームワーク
- Windows Driver Foundation を使用したドライバーの開発、Penny Orwick および Guy Smith で作成。 詳細については、「WDF を使用したドライバーの開発」を参照してください。
手順 1: Visual Studio USB ドライバー テンプレートを使用して KMDF ドライバー コードを生成する
KMDF ドライバー コードの生成手順については、「テンプレートに基づく KMDF ドライバーの記述」の手順をご覧ください。
USB 固有のコードの場合は、Visual Studio で次のオプションを選択します
- [新しいプロジェクト] ダイアログ ボックスの上部にある検索ボックスに、もう一度「USB」と入力します。
- 中央のウィンドウで、[カーネル モード ドライバー、USB (KMDF)] を選択します。
- [次へ] を選択します。
- プロジェクト名を入力し、保存場所を選択して、[作成] を選択します。
次のスクリーンショットは、USB カーネル モード ドライバー テンプレートの [新しいプロジェクト] ダイアログ ボックスを示しています。
この記事では、Visual Studio プロジェクトの名前が "MyUSBDriver_" であることを前提としています。 次のファイルが含まれます。
| ファイル | 説明 |
|---|---|
| Public.h | クライアント ドライバーと USB デバイスと通信するユーザー アプリケーションによって共有される一般的な宣言を提供します。 |
| <Project name>.inf | ターゲット コンピューターにクライアント ドライバーをインストールするために必要な情報が含まれています。 |
| Trace.h | トレース関数とマクロを宣言します。 |
| Driver.h; Driver.c | ドライバーのエントリ ポイントとイベント コールバック ルーチンを宣言して定義します。 |
| Device.h; Device.c | ハードウェア準備イベントのイベント コールバック ルーチンを宣言して定義します。 |
| Queue.h; Queue.c | フレームワークのキュー オブジェクトによって発生するイベントのイベント コールバック ルーチンを宣言および定義します。 |
手順 2: INF ファイルを変更して、デバイスに関する情報を追加する
ドライバーをビルドする前に、デバイスに関する情報 (具体的にはハードウェア ID 文字列) を使用してテンプレート INF ファイルを変更する必要があります。
ソリューション エクスプローラーの [ドライバー ファイル] で、INF ファイルをダブルクリックします。
INF ファイルでは、製造元とプロバイダー名、デバイス セットアップ クラスなどの情報を指定できます。 指定する必要がある情報の 1 つは、デバイスのハードウェア識別子です。
ハードウェア ID 文字列を指定するには、次のようにします。
USB デバイスをホスト コンピューターに接続し、Windows がデバイスを列挙できるようにします。
デバイス マネージャーを開き、デバイスのプロパティを開きます。
[詳細] タブで、[プロパティ] の下の [ハードウェア ID] を選択します。
デバイスのハードウェア ID がリスト ボックスに表示されます。 ハードウェア ID 文字列を選択して長押し (または右クリック) し、コピーします。
次の行の USB\VID_vvvv&PID_pppp をハードウェア ID 文字列に置き換えます。
[Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp
手順 3: USB クライアント ドライバー コードをビルドする
ドライバーをビルドするには:
- Visual Studio でドライバー プロジェクトまたはソリューションを開きます。
- ソリューション エクスプローラーでソリューションを選択して長押し (または右クリック) し、[構成マネージャー] を選択します。
- [構成マネージャー] から、関心のあるビルドの種類に対応する [アクティブ ソリューション構成] (たとえば、[デバッグ] または [リリース]) と [アクティブ ソリューション プラットフォーム] (たとえば、[Win32]) を選択します。
- [ビルド] メニューの [ソリューションのビルド] を選択します。
詳しくは、「ドライバーのビルド」をご覧ください。
手順 4: テストとデバッグ用にコンピューターを構成する
ドライバーをテストおよびデバッグするには、ホスト コンピューターでデバッガーを実行し、ターゲット コンピューターでドライバーを実行します。 ここまでは、ホスト コンピューター上で Visual Studio を使用してドライバーをビルドしてきました。 次に、ターゲット コンピューターを構成する必要があります。 ターゲット コンピューターを構成するには、「ドライバーのデプロイとテスト用にコンピューターをプロビジョニングする」の手順に従います。
手順 5: カーネル デバッグのトレースを有効にする
テンプレート コードには、関数呼び出しのトレースに役立つトレース メッセージ (TraceEvents) がいくつか含まれています。 ソース コード内のすべての関数には、ルーチンの開始と終了をマークするトレース メッセージが含まれています。 エラーの場合、トレース メッセージにはエラー コードと意味のある文字列が含まれます。 ドライバー プロジェクトでは WPP トレースが有効になっているため、ビルド プロセス中に作成される PDB シンボル ファイルには、トレース メッセージのフォーマット指示が含まれています。 WPP トレース用にホスト コンピューターとターゲット コンピューターを構成すると、ドライバーはトレース メッセージをファイルまたはデバッガーに送信できます。
WPP トレース用にホスト コンピューターを構成するには、次のようにします。
トレース メッセージ フォーマット命令を PDB シンボル ファイルから抽出して、トレース メッセージ フォーマット (TMF) ファイルを作成します。
Tracepdb.exe を使用して TMF ファイルを作成できます。 このツールは、WDK の<install folder>Windows Kits\10.0\bin\<architecture> フォルダーにあります。 次のコマンドは、ドライバー プロジェクトの TMF ファイルを作成します。
tracepdb -f <PDBFiles> -p <TMFDirectory>
-f オプションは、PDB シンボル ファイルの場所と名前を指定します。 -p オプションは、Tracepdb によって作成される TMF ファイルの場所を指定します。 詳しくは、「Tracepdb コマンド」を参照してください。
指定した場所に、3 つのファイル (プロジェクト内の .c ファイルごとに 1 つ) が表示されます。 GUID ファイル名が与えられます。
デバッガーで、次のコマンドを入力します。
.load Wmitrace
Wmitrace.dll 拡張機能を読み込みます。
.chain
デバッガー拡張機能が読み込まれたことを確認します。
!wmitrace.searchpath +<TMF ファイルの場所>
デバッガー拡張機能の検索パスに TMF ファイルの場所を追加します。
次のような内容が出力されます。
Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'
WPP トレース用にターゲット コンピューターを構成するには、次のようにします。
ターゲット コンピューターに Tracelog ツールがあることを確認します。 このツールは、WDK の <install_folder>Windows Kits\8.0\Tools\<arch> フォルダーにあります。 詳細については、「Tracelog コマンド構文」を参照してください。
[コマンド ウィンドウ] を管理者として開きます。
次のコマンドを入力します。
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: ターゲット コンピューターにドライバーをデプロイする
- ソリューション エクスプローラー ウィンドウで、*<プロジェクト名>*Package を長押し (または右クリック) して、[プロパティ] を選択します。
- 左側のウィンドウで、[構成プロパティ > ドライバーのインストール > デプロイ] に移動します。
- [展開を有効にする] をオンにし、[ドライバー ストアにインポートする] をオンにします。
- [リモート コンピューター名] には、ターゲット コンピューターの名前を指定します。
- [インストールと検証] を選択します。
- OK を選択します。
- [デバッグ] メニューの [デバッグの開始] を選択するか、キーボードの F5 キーを押します。
Note
[ハードウェア ID ドライバーの更新] で、デバイスのハードウェア ID を指定しないでください。 ハードウェア ID は、ドライバーの情報 (INF) ファイルでのみ指定する必要があります。
Visual Studio でターゲット システムにドライバーを展開する方法について詳しくは、「テスト コンピューターへのドライバーの展開」をご覧ください。
デバイス マネージャーを使用して、ターゲット コンピューターにドライバーを手動でインストールすることもできます。 コマンド プロンプトからドライバーをインストールする場合、次のユーティリティを使用できます。
-
このツールは 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 の例」を参照してください。
-
このツールは WDK に付属しています。 これを使用して、ドライバーのインストールと更新を行うことができます。
devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6
手順 7: デバイス マネージャーでドライバーを表示する
次のコマンドを入力して、[デバイス マネージャー] を開きます。
devmgmtデバイス マネージャーに次のノードが表示されていることを確認します。
サンプル
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