Windows ドライバーの検証

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

InfVerif、Driver Verifier Driver Isolation Checks、および ApiValidator ツールを使用して、ウィンドウドライバーの概要で説明されているウィンドウドライバーの要件にドライバーパッケージが準拠しているかどうかをテストします。

InfVerif

InfVerif は、INF 構文を検証し、INF が要件と制限に準拠していることを確認するツールです。

/w とInfVerifを使用して、Windowsドライバーが次のことを確認します。

DCH 設計原則 の宣言型 (D) 原則を満たしているか
「Windows ドライバーの概要」のドライバーパッケージの分離要件に準拠しているか

詳細については、「コマンドラインからの InfVerif の実行」を参照してください。

InfVerif は、次に示すように、"/w" 引数を使用してドライバー分離の要件を検証します。

infverif.exe /w <INF file> [<INF file>]

/wでの検証時にInfVerifがエラーを報告しない場合、INF はWindowsドライバーのドライバーパッケージ分離要件を満たしています。

Windows の現在のバージョンと以前のバージョンをターゲットとする

WINDOWS 10 バージョン 1809 以降で使用できる INF AddEventProvider ディレクティブなど、最新バージョンの Windows で導入された構文が INF に含まれている場合、 INF 装飾を使用してバージョン固有の INF エントリをマークします。 OSバージョンの装飾の使用方法を示すサンプルコードについては、「プラットフォーム拡張機能とオペレーティングシステムのバージョンの組み合わせ」を参照してください。

以前のバージョンの Windows ではドライバーの分離要件がサポートされていない可能性があるため、OS バージョンの装飾を使用する INF ファイルが InfVerif で失敗する可能性があります。このような INF を検証するには、"/wbuild" 引数を使用して、ドライバー分離チェックを適用する必要がある Windows の最小バージョンを指定できます。たとえば、AddEventProvider ディレクティブを使用する INF ファイルでは、Windows 10 バージョン 1809 以降にドライバー分離チェックのみを適用するために次を使用できます。

infverif.exe /w /wbuild NTAMD64.10.0.0.17763 <INF file> [<INF file>]

ドライバーの検証ツールのドライバーの分離チェック

ウィンドウドライバーとしての資格を得るには、ドライバーパッケージがドライバーパッケージ分離要件を満たしている必要があります。 Windows 11 以降、ドライバー検証機 (DV) は、分離されたドライバーパッケージでは許可されていないレジストリの読み取りおよび書き込みについてカーネルバイナリを監視できるようになりました。

お客様は、カーネルデバッガーで発生した違反をすぐに確認するか、または DV を構成して、違反が発生したときにシステムを停止し、詳細情報を含むメモリダンプを生成するようにすることができます。まずは最初の方法でドライバーの開発を開始し、ドライバーの完成に近づいたら 2 番目に切り替えることができます。

発生した違反をすぐに確認するには、まずカーネルデバッガーに接続してから、次のコマンドを使用します。再起動によって DV 設定が有効になったら、カーネルデバッガーの出力で違反を監視できます。

1 つのドライバーに対してドライバーの分離チェックを有効にするには:

verifier /rc 33 36 /driver myDriver.sys

複数のドライバーをチェックするには、各ドライバー名をスペースで区切ります。

verifier /rc 33 36 /driver myDriver1.sys myDriver2.sys

違反が発生したときにバグチェックするように DV を構成するには、次の構文を使用します。

verifier /onecheck /rc 33 36 /driver myDriver1.sys

検証設定を有効にするには、再起動する必要があります。コマンドラインからこれを行うには、次のように指定します。

shutdown /r /t 0

次に、エラーメッセージの例をいくつか示します。

例: ZwCreateKey は完全な絶対パスを提供します。

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should not use absolute paths. Detected creation of unisolated registry key \Registry\Machine\SYSTEM

例: ZwCreateKey は、承認されたAPIからのものではないハンドルに対する相対パスを提供します。

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should only use key handles returned from WDF or WDM APIs. Detected creation of unisolated registry key \REGISTRY\MACHINE\SYSTEM\SomeKeyThatShouldNotExist

ドライバー分離違反を早期に発見できるように、ドライバーで DV ドライバー分離チェックを有効にしてデバイスの基礎テストを実行することを検討してください。

KMDF ドライバー

KMDFドライバーが WDF APIs (WdfRegistryCreateKey、WdfRegistryOpenKey、またはWdfRegistryQueryValue など) を使用してレジストリにアクセスする場合、レジストリアクセスは、KMDF ドライバーバイナリではなく、wdf01000.sys を介して行われます。 KMDFドライバーバイナリによって引き起こされた違反を表示するには、KMDFドライバーバイナリに加えて、wdf01000.sys のドライバー分離チェックを有効にしてください。これを行うと、レジストリアクセスにWDFを使用しているシステム上のすべての KMDFドライバーからの違反が表示されることに注意してください。

ApiValidator

ApiValidator ツールを使うと、バイナリから呼び出される API が、Windows ドライバーにとって有効であるかどうかを確認できます。 Windows ドライバーにとって有効な API セットの外部にある API をバイナリが呼び出すと、エラーが返されます。このツールは、WDK for Windows 10 の一部です。

ApiValidator では、 API レイヤー化 (Windows ドライバーの要件の 1 つ) がドライバーでサポートされているかを検証します。要件の完全な一覧については、「Windows ドライバーの概要」を参照してください。

Visual Studio での ApiValidator の実行

ドライバープロジェクトの [ターゲットプラットフォーム] プロパティが [Windows ドライバー] に設定されていれば、Visual Studio はビルド後の手順として自動的に ApiValidator を実行します。

ApiValidator で表示されたメッセージをすべて確認するには、 [ツール] ->[オプション] ->[プロジェクトおよびソリューション] ->[ビルド/実行] の順に移動して、 [MSBuild プロジェクトビルドの出力の詳細] を [詳細] に設定します。コマンドラインからビルドする場合、ビルドコマンドにスイッチ /v:detailed または /v:diag を追加して詳細度を高めます。

umdf2_fx2 ドライバーサンプルに対して API の検証を実行すると、次のようなエラーが表示されます。

Warning  1   warning : API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 2   warning : API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 3   warning : API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 4   warning : API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 5   warning : API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.  C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 6   warning : API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 7   warning : API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 8   warning : API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 9   warning : API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Error   10  error MSB3721: The command ""C:\Program Files (x86)\Windows Kits\10\bin\x64\ApiValidator.exe" -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug\\" -SupportedApiXmlFiles:"C:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x86\UniversalDDIs.xml" -ApiExtractorExePath:"C:\Program Files (x86)\Windows Kits\10\bin\x64"" exited with code -1.    C:\Program Files (x86)\Windows Kits\10\build\WindowsDriver.common.targets   1531    5   osrusbfx2um

検証エラーの修正

レガシデスクトップ UMDF ドライバープロジェクトを　Windows ドライバーに切り替えた場合は、バイナリをビルドするときに、適切なライブラリが含まれていることを確認します。プロジェクトを長押し (または右クリック) し、[プロパティ] を選びます。 リンカー>入力に移動します。 追加の依存関係 には以下が含まれている必要があり:
```
%AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
```
OneCore SKUsをターゲットにするための他のリンカーオプションを確認するには、 OneCore用の建築を参照。
許可されない API の呼び出しを一度に 1 つずつ削除または置換し、エラーがなくなるまでツールを再実行します。
場合によっては、これらの呼び出しを、デスクトップ専用 DDI のリファレンスページにリストされている代替 DDI に置き換えることができます。適切な代替手段がない場合は、回避策をコーディングする必要がある場合があります。必要に応じて、WDK のドライバーテンプレートから新しい Windows ドライバーを作成してください。

次のようなエラーが発生する場合は、「OneCore をターゲットとしたビルド」のガイダンスを参照してください。

ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSEnumerateSessionsW' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSFreeMemory' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: NOT all binaries are Universal

コマンドプロンプトから ApiValidatorを実行する

コマンドプロンプトから Apivalidator.exe を実行することもできます。 WDK インストールで、 C:\Program Files (x86)\Windows Kits\10\bin<arch> と C:\Program Files (x86)\Windows Kits\10\build\universalDDIs<arch> に移動します。

重要な注意:

ApiValidatorには次のファイルが必要です。ApiValidator.exe、Aitstatic.exe、Microsoft.Kits.Drivers.ApiValidator.dll、および UniversalDDI.xml。
UniversalDDIs.xml は、検証されるバイナリアーキテクチャと一致する必要があります。たとえば、x64 ドライバーの場合は x64 UniversalDDI.xml を使用します。
ApiValidator でテストされるのは、一度に 1 つのアーキテクチャのみになります。
その他の情報については、以下の ApiValidator に関する既知の問題を参照してください。

次の構文を使用します。

Apivalidator.exe -DriverPackagePath: <driver folder path> -SupportedApiXmlFiles: (path to XML files containing supported APIs for Windows drivers)

たとえば、WDKのアクティビティサンプルによって呼び出される API を確認するには、まずビジュアルスタジオでサンプルをビルドします。次に、コマンドプロンプトを開き、ツールが存在するディレクトリ (例: C:\Program Files (x86\Windows Kits\10\bin\x64) に移動します。次のコマンドを入力します。

apivalidator.exe -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2\_fx2\Debug" -SupportedApiXmlFiles:"c:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x64\UniversalDDIs.xml"

コマンドでは次の出力が生成されます。

ApiValidator.exe: Warning: API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API.

ApiValidator.exe Driver located at C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug is NOT a Universal Driver

ApiValidator のトラブルシューティング

ApiValidator.exe が次のような不正な形式のエラーを出力する場合:

Error      1              error : AitStatic output file has incorrect format or analysis run on incorrect file types.     C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe            osrusbfx2um

この回避策を使用してください。

プロジェクトのプロパティを開き、全般に移動し、 アウトプットディレクトリ の名前を次のように変更します。
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
ソリューションをリビルドします。

ApiValidator に関する既知の問題

Arm64 では AitStatic が動作しないため、ApiValidator は Arm64 では実行されません。
Arm64 のバイナリは x64 マシンではテストできますが、x86 マシンではできません。
ApiValidator を x86 上で実行して、x86 のバイナリと Arm のバイナリをテストできます。
ApiValidator を x64 上で実行して、x86、x64、Arm、Arm64 のバイナリをテストできます。