Hello World Windows ドライバーの作成 (KMDF)

[アーティクル]
04/12/2024

この記事では、カーネルモードドライバーフレームワーク (KMDF) を使用して小さなユニバーサル Windows ドライバーを作成し、別のコンピューターにそのドライバーを展開してインストールする方法について説明します。

続行する前に、「Windows Driver Kit (WDK) のダウンロード」に記載されているインストール手順を完了します。

Windows 用デバッグツールは、WDK をインストールするときに組み込まれます。

ドライバーの作成とビルド

Microsoft Visual Studio を開く。 [ファイル] メニューで [新規] > [プロジェクト] を選択します。
[新しいプロジェクトの作成] ダイアログボックスの左側のドロップダウンで [C++] を選択し、中央のドロップダウンで [Windows] を選択し、右側のドロップダウンで [ドライバー] を選択します。
プロジェクトの種類の一覧から [Kernel Mode Driver, Empty (KMDF)]$カーネルモードドライバー, 空 (KMDF)$ を選択します。 [次へ] を選択します。
[新しいプロジェクトの構成] ダイアログボックスで、[プロジェクト名] フィールドに「KmdfHelloWorld」と入力します。

Note

新しい KMDF ドライバーか UMDF ドライバーを作成する場合、32 文字以下のドライバー名を選ぶ必要があります。この長さの制限は wdfglobals.h で定義されています。
[場所] フィールドに、新しいプロジェクトを作成するディレクトリを入力します。
[ソリューションとプロジェクトを同じディレクトリに配置する] をオンにし、[作成] を選択します。

Visual Studio により、1 つのプロジェクトと 1 つのソリューションが作成されます。これらはソリューションエクスプローラー ウィンドウで確認できます。 ([ソリューションエクスプローラー] ウィンドウが表示されない場合は、[表示] メニューの [ソリューションエクスプローラー] を選択します)。このソリューションには、KmdfHelloWorld という名前のドライバープロジェクトがあります。
[ソリューションエクスプローラー] ウィンドウで、[KmdfHelloWorld] ソリューションを長押し (または右クリック) し、[構成マネージャー] を選びます。ドライバープロジェクトに対する構成とプラットフォームを選びます。たとえば、Debug と x64 を選びます。
[ソリューションエクスプローラー] ウィンドウで、もう一度 [KmdfHelloWorld] プロジェクトを長押し (または右クリック) し、[追加] を選択して、[新しい項目] を選択します。
[新しい項目の追加] ダイアログボックスで、[C++ ファイル] を選択します。 [名前] に「Driver.c」と入力します。

Note

ファイル名拡張子は、.cpp ではなく .c です。

[追加] を選択します。次に示すように、Driver.c ファイルが [ソースファイル] の下に追加されます。

初めてのドライバーコードを記述する

空の Hello World プロジェクトを作成し、Driver.c ソースファイルを追加したら、2 つの基本的なイベントコールバック関数を実装して、ドライバーの実行に必要な最も基本的なコードを記述します。

Driver.c で、最初にこれらのヘッダーを含めます。
```
#include <ntddk.h>
#include <wdf.h>
```
ヒント

Ntddk.h を追加できない場合は、[構成] -> [C/C++] -> [全般] -> [追加のインクルードディレクトリ] の順に開いて C:\Program Files (x86)\Windows Kits\10\Include\<build#>\km を追加し、<build#> を WDK インストール内の適切なディレクトリに置き換えます。

Ntddk.h には、すべてのドライバーの主要な Windows カーネル定義が含まれています。一方、Wdf.h には、Windows ドライバーフレームワーク (WDF) に基づくドライバーの定義が含まれています。

次に、使用する 2 つのコールバックの宣言を指定します。

DRIVER_INITIALIZE DriverEntry;
EVT_WDF_DRIVER_DEVICE_ADD KmdfHelloWorldEvtDeviceAdd;

次のコードを使用して DriverEntry を記述します。
```
NTSTATUS 
DriverEntry(
    _In_ PDRIVER_OBJECT     DriverObject, 
    _In_ PUNICODE_STRING    RegistryPath
)
{
    // NTSTATUS variable to record success or failure
    NTSTATUS status = STATUS_SUCCESS;

    // Allocate the driver configuration object
    WDF_DRIVER_CONFIG config;

    // Print "Hello World" for DriverEntry
    KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "KmdfHelloWorld: DriverEntry\n" ));

    // Initialize the driver configuration object to register the
    // entry point for the EvtDeviceAdd callback, KmdfHelloWorldEvtDeviceAdd
    WDF_DRIVER_CONFIG_INIT(&config, 
                           KmdfHelloWorldEvtDeviceAdd
                           );

    // Finally, create the driver object
    status = WdfDriverCreate(DriverObject, 
                             RegistryPath, 
                             WDF_NO_OBJECT_ATTRIBUTES, 
                             &config, 
                             WDF_NO_HANDLE
                             );
    return status;
}
```
DriverEntry はすべてのドライバーのエントリポイントで、多くのユーザーモードアプリケーションに使用される Main() と同様です。 DriverEntry の役割は、ドライバー全体の構造とリソースを初期化することです。この例では、DriverEntry に対して "Hello World" を出力し、EvtDeviceAdd コールバックのエントリポイントを登録するためのドライバーオブジェクトを構成し、ドライバーオブジェクトを作成した後、制御を返しています。

ドライバーオブジェクトは、デバイスオブジェクト、I/O キュー、タイマー、スピンロックなど、ドライバーで作成する可能性のある他のすべてのフレームワークオブジェクトの親オブジェクトとして機能します。フレームワークオブジェクトの詳細については、「フレームワークオブジェクトの概要」を参照してください。

ヒント

DriverEntry については、コード分析とデバッグに役立てるために "DriverEntry" という名前を維持することを強くお勧めします。
次に、次のコードを使用して、KmdfHelloWorldEvtDeviceAdd を記述します。
```
NTSTATUS 
KmdfHelloWorldEvtDeviceAdd(
    _In_    WDFDRIVER       Driver, 
    _Inout_ PWDFDEVICE_INIT DeviceInit
)
{
    // We're not using the driver object,
    // so we need to mark it as unreferenced
    UNREFERENCED_PARAMETER(Driver);

    NTSTATUS status;

    // Allocate the device object
    WDFDEVICE hDevice;    

    // Print "Hello World"
    KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "KmdfHelloWorld: KmdfHelloWorldEvtDeviceAdd\n" ));

    // Create the device object
    status = WdfDeviceCreate(&DeviceInit, 
                             WDF_NO_OBJECT_ATTRIBUTES,
                             &hDevice
                             );
    return status;
}
```
EvtDeviceAdd は、デバイスが到着したことが検出されたときに、システムによって呼び出されます。その役割は、デバイスの構造とリソースを初期化することです。この例では、EvtDeviceAdd に対して単に "Hello World" メッセージを出力し、デバイスオブジェクトを作成した後、制御を返しています。作成する他のドライバーでは、ハードウェアの I/O キューを作成したり、デバイス固有の情報用にデバイスコンテキストの記憶域スペースを設定したり、デバイスを準備するために必要な他のタスクを実行したりします。

ヒント

デバイスの追加コールバックについては、プレフィックスとしてドライバー名を含む名前が付けられている点に注目してください (KmdfHelloWorldEvtDeviceAdd)。一般に、他のドライバーの関数と区別するために、この方法でドライバーの関数に名前を付けることをお勧めします。 DriverEntry に限り、正確にこのとおりの名前を付ける必要があります。

完全な Driver.c は、このようになります。

#include <ntddk.h>
#include <wdf.h>
DRIVER_INITIALIZE DriverEntry;
EVT_WDF_DRIVER_DEVICE_ADD KmdfHelloWorldEvtDeviceAdd;

NTSTATUS 
DriverEntry(
    _In_ PDRIVER_OBJECT     DriverObject, 
    _In_ PUNICODE_STRING    RegistryPath
)
{
    // NTSTATUS variable to record success or failure
    NTSTATUS status = STATUS_SUCCESS;

    // Allocate the driver configuration object
    WDF_DRIVER_CONFIG config;

    // Print "Hello World" for DriverEntry
    KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "KmdfHelloWorld: DriverEntry\n" ));

    // Initialize the driver configuration object to register the
    // entry point for the EvtDeviceAdd callback, KmdfHelloWorldEvtDeviceAdd
    WDF_DRIVER_CONFIG_INIT(&config, 
                           KmdfHelloWorldEvtDeviceAdd
                           );

    // Finally, create the driver object
    status = WdfDriverCreate(DriverObject, 
                             RegistryPath, 
                             WDF_NO_OBJECT_ATTRIBUTES, 
                             &config, 
                             WDF_NO_HANDLE
                             );
    return status;
}

NTSTATUS 
KmdfHelloWorldEvtDeviceAdd(
    _In_    WDFDRIVER       Driver, 
    _Inout_ PWDFDEVICE_INIT DeviceInit
)
{
    // We're not using the driver object,
    // so we need to mark it as unreferenced
    UNREFERENCED_PARAMETER(Driver);

    NTSTATUS status;

    // Allocate the device object
    WDFDEVICE hDevice;    

    // Print "Hello World"
    KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "KmdfHelloWorld: KmdfHelloWorldEvtDeviceAdd\n" ));

    // Create the device object
    status = WdfDeviceCreate(&DeviceInit, 
                             WDF_NO_OBJECT_ATTRIBUTES,
                             &hDevice
                             );
    return status;
}

Driver.c を保存します。

この例は、ドライバーの基本的な概念を示しています。これらは、初期化されると、システムが何かを必要とするときに呼び出されるのを待つ "コールバックのコレクション" です。システム呼び出しには、新しいデバイス到着イベント、ユーザーモードアプリケーションからの I/O 要求、システム電源シャットダウンイベント、別のドライバーからの要求、またはユーザーが予期せずデバイスを取り外したときの突然の削除イベントなどが考えられます。さいわいにも、"Hello World" を表示するにはドライバーとデバイスの作成について心配するだけで済みました。

次に、ドライバーをビルドします。

ドライバーをビルドする

[ソリューションエクスプローラー] ウィンドウで、[ソリューション 'KmdfHelloWorld' (1 プロジェクト)] を長押し (または右クリック) し、[構成マネージャー] を選びます。ドライバープロジェクトに対する構成とプラットフォームを選びます。この作業では、Debug と x64 を選びます。
[ソリューションエクスプローラー] ウィンドウで、[KmdfHelloWorld] を長押し (または右クリック) し、[プロパティ] を選びます。 [Wpp Tracing] (Wpp トレース) > [All Options] (すべてのオプション) で、[Run Wpp tracing] (Wpp トレースの実行) を [いいえ] に設定します。 [Apply](適用) 、 [OK] の順に選択します。
ドライバーをビルドするには、[ビルド] メニューの [ソリューションのビルド] を選びます。 Visual Studio により、[出力] ウィンドウにビルドの進行状況が表示されます。 ([出力] ウィンドウが表示されない場合は、[表示] メニューの [出力] を選択します)。ソリューションが正常にビルドされたことを確認したら、Visual Studio を閉じます。
ビルドされたドライバーを確認するには、エクスプローラーで KmdfHelloWorld フォルダーに移動し、さらに x64\Debug\KmdfHelloWorld に移動します。フォルダーには次のものが含まれます。
- KmdfHelloWorld.sys -- カーネルモードドライバーファイル
- KmdfHelloWorld.inf -- ドライバーのインストール時に Windows が使用する情報ファイル
- KmdfHelloWorld.cat -- ドライバーのテスト署名を検証するときにインストーラーで使われるカタログファイル

ヒント

ドライバーのビルド時に DriverVer set to a date in the future が表示された場合、ドライバープロジェクトの設定を Inf2Cat が /uselocaltime を設定するように変更します。このためには、[構成プロパティ] -> [Inf2Cat] -> [全般] -> [Use Local Time]$現地時刻の使用$ を使用します。これで、Stampinf と Inf2Cat の両方で現地時刻が使用されます。

ドライバーを展開する

ドライバーをテストしてデバッグする場合、通常はデバッガーとドライバーを別個のコンピューターで実行します。デバッガーを実行するコンピューターはホストコンピューターと呼ばれ、ドライバーを実行するコンピューターはターゲットコンピューターと呼ばれます。ターゲットコンピューターはテストコンピューターとも呼ばれます。

ここまでは、Visual Studio を使用してホストコンピューター上でドライバーをビルドしました。次に、ターゲットコンピューターを構成する必要があります。

「ドライバーの展開およびテストのためのコンピューターのプロビジョニング (WDK 10)」の手順に従ってください。

ヒント

ネットワークケーブルを使用してターゲットコンピューターを自動的にプロビジョニングする手順に従う場合は、ポートとキーをメモしておきます。これらはデバッグ手順の後半で使用します。この例では、ポートとして 50000 を使用し、キーとして 1.2.3.4 を使用します。

実際のドライバーのデバッグシナリオでは、KDNET によって生成されたキーを使用することをお勧めします。 KDNET を使用してランダムキーを生成する方法の詳細については、「ドライバーのデバッグ - ステップバイステップラボ (Sysvad カーネルモード)」のトピックを参照してください。
ホストコンピューターで、Visual Studio でソリューションを開きます。 KmdfHelloWorld フォルダー内のソリューションファイル (KmdfHelloWorld.sln) をダブルクリックできます。
[ソリューションエクスプローラー] ウィンドウで、[KmdfHelloWorld] プロジェクトを選択して長押し (または右クリック) し、[プロパティ] をクリックします。
次に示すように、[KmdfHelloWorld のプロパティページ] ウィンドウで、[構成プロパティ] > [Driver Install] (ドライバーのインストール) > [Deployment] (展開) の順に移動します。
[デプロイ前に以前のドライバーバージョンを削除する] にチェックを入れます。
[Target Device Name] (ターゲットデバイス名) で、テストとデバッグ用に構成したコンピューターの名前を選択します。この演習では、MyTestComputer という名前のコンピューターを使用します。
[Hardware ID Driver Update] (ハードウェア ID のドライバーの更新) を選択し、ドライバーのハードウェア ID を入力します。この例では、ハードウェア ID は Root\KmdfHelloWorld です。 [OK] を選択します。

Note

この演習のハードウェア ID は実際のハードウェアを識別するものではありません。これは、ルートノードの子としてデバイスツリー内の場所が与えられる架空のデバイスを識別します。実際のハードウェアの場合は、[Hardware ID Driver Update] (ハードウェア ID のドライバーの更新) を選択しないでください。代わりに、[インストールと検証] を選択します。ハードウェア ID は、ドライバーの情報 (INF) ファイルで確認できます。 [ソリューションエクスプローラー] ウィンドウで、[KmdfHelloWorld] > [Driver Files] (ドライバーファイル) の順に移動し、KmdfHelloWorld.inf をダブルクリックします。ハードウェア ID は [Standard.NT$ARCH$] の下に記載されています。
```
[Standard.NT$ARCH$]
%KmdfHelloWorld.DeviceDesc%=KmdfHelloWorld_Device, Root\KmdfHelloWorld
```
[ビルド] メニューの [ソリューションの配置] を選択します。 Visual Studio により、ドライバーのインストールと実行に必要なファイルがターゲットコンピューターに自動的にコピーされます。デプロイには 1、2 分かかる場合があります。

ドライバーを展開すると、ドライバーファイルがテストコンピューターの %Systemdrive%\drivertest\drivers フォルダーにコピーされます。展開中に問題が発生した場合は、ファイルがテストコンピューターにコピーされているかどうかを確認できます。 .inf、.cat、test cert、.sys など、必要なファイルがすべて %systemdrive%\drivertest\drivers フォルダーに存在することを確認します。

ドライバーの展開の詳細については、「テストコンピューターへのドライバーの展開」を参照してください。

ドライバーをインストールする

Hello World ドライバーをターゲットコンピューターに展開したら、ドライバーをインストールします。事前に Visual Studio で自動オプションを使用してターゲットコンピューターをプロビジョニングしている場合、Visual Studio により、プロビジョニングプロセスの一環としてテスト署名済みドライバーを実行するようにターゲットコンピューターが設定されます。ここでは、DevCon ツールを使用してドライバーをインストールするだけです。

ホストコンピューターで、WDK インストールの [ツール] フォルダーに移動し、DevCon ツールを見つけます。たとえば、次のフォルダー内を探します。

C:\Program Files (x86)\Windows Kits\10\Tools\x64\devcon.exe

DevCon ツールをリモートコンピューターにコピーします。
ターゲットコンピューターで、ドライバーファイルが含まれているフォルダーに移動し、DevCon ツールを実行してドライバーをインストールします。
1. ドライバーのインストールに使用する devcon ツールの一般的な構文を次に示します。
  
  devcon install <INF ファイル><ハードウェア ID>
  
  このドライバーのインストールに必要な INF ファイルは KmdfHelloWorld.inf です。この INF ファイルには、ドライバーのバイナリ (KmdfHelloWorld.sys) をインストールするためのハードウェア ID が含まれています。 INF ファイルにあるハードウェア ID が Root\KmdfHelloWorld であることを思い出してください。
2. 管理者として [コマンドプロンプト] ウィンドウを開きます。ビルドされたドライバーの .sys ファイルを含むフォルダーに移動し、次のコマンドを入力します。
  
  devcon install kmdfhelloworld.inf root\kmdfhelloworld
  
  devcon が認識されないというエラーメッセージが表示される場合は、devcon ツールへのパスを追加してみてください。たとえば、対象のコンピューター上の C:\Tools という名前のフォルダーにコピーする場合は、次のコマンドを使ってみてください。
  
  c:\tools\devcon install kmdfhelloworld.inf root\kmdfhelloworld
  
  テストドライバーが署名されていないドライバーであることを示すダイアログボックスが表示されます。 [かまわず続行] を選択して続行します。

ドライバーをデバッグする

ターゲットコンピューターに KmdfHelloWorld ドライバーをインストールしたら、ホストコンピューターからリモートでデバッガーをアタッチします。

ホストコンピューターで、管理者として [コマンドプロンプト] ウィンドウを開きます。 WinDbg.exe ディレクトリに移動します。 Windows キットのインストールの一部としてインストールされた Windows Driver Kit (WDK) に含まれる WinDbg.exe の x64 バージョンを使用します。 WinDbg.exe の既定のパスを次に示します。

C:\Program Files (x86)\Windows Kits\10\Debuggers\x64
次のコマンドを使用して、WinDbg を起動し、ターゲットコンピューター上のカーネルデバッグセッションに接続します。ポートとキーの値は、ターゲットコンピューターをプロビジョニングするために使用した値と同じである必要があります。ここでは、ポートとして 50000、キーとして 1.2.3.4 を使用します。これらは展開の手順で使用した値です。 k フラグは、これがカーネルデバッグセッションであることを示します。

WinDbg -k net:port=50000,key=1.2.3.4
[デバッグ] メニューの [Break] (中断) を選択します。ホストコンピューター上のデバッガーが、ターゲットコンピューターに割り込みます。 デバッガーのコマンド ウィンドウに、カーネルのデバッグコマンドプロンプト kd> が表示されます。
この時点で、kd> プロンプトに対してコマンドを入力して、デバッガーの操作を試すことができます。たとえば、これらのコマンドを試すことができます。
ターゲットコンピューターをもう一度実行するには、[デバッグ] メニューの [Go] を選択するか、g キーを押してから Enter キーを押します。
デバッグセッションを停止するには、[デバッグ] メニューの [デバッガーのデタッチ] を選択します。

重要

デバッガーを終了する前に、必ず [Go] コマンドを使用してターゲットコンピューターをもう一度実行してください。ターゲットコンピューターはまだデバッガーとやり取りをしている状態であるため、この操作を行わないと、ターゲットコンピューターはマウスとキーボードの入力に対して応答を停止したままになります。

ドライバーのデバッグプロセスの詳細なチュートリアルについては、「ユニバーサルドライバーのデバッグ - ステップバイステップラボ (エコーカーネルモード)」を参照してください。

リモートデバッグの詳細については、「WinDbg を使用したリモートデバッグ」を参照してください。

Windows 用デバッグツール

ユニバーサルドライバーのデバッグ - ステップバイステップラボ (Echo カーネルモード)

初めてのドライバーの作成

Hello World Windows ドライバーの作成 (KMDF)

ドライバーの作成とビルド

初めてのドライバーコードを記述する

ドライバーをビルドする

ドライバーを展開する

ドライバーをインストールする

ドライバーをデバッグする

フィードバック

フィードバック

その他のリソース

Hello World Windows ドライバーの作成 (KMDF)

ドライバーの作成とビルド

初めてのドライバー コードを記述する

ドライバーをビルドする

ドライバーを展開する

ドライバーをインストールする

ドライバーをデバッグする

関連記事

フィードバック

フィードバック

その他のリソース

初めてのドライバーコードを記述する