Windows ドライバーの検証

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

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

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

ドライバーの分離チェックを有効にして、カーネル デバッガーとシステム イベント ログを介して報告されるようにしますが、システムのバグチェックは行いません。

verifier /rc 33 36 /driver myDriver.sys [myDriver2.sys ...]

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

verifier /onecheck /rc 33 36 /driver myDriver1.sys [myDriver2.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 ドライバー分離チェックを有効にして デバイスの基礎テスト を実行することを検討してください。

WHCP コンプライアンス

現時点では、Windows ハードウェア互換性プログラム (WHCP) プログラムでは、ドライバー パッケージの完全な分離は必須ではありません。 ただし、Windows 11 24H2 以降では、WHCP プログラムはドライバーの分離に関連する要件を含め始めます。 Hardware Lab Kit (HLK) が WHCP 要件を実施する一環として行っているものと同じレベルのドライバー パッケージ分離検証を有効にするには、次の構文を使用します。

Verifier /dif 33 /33 whcp /driver myDriver.sys [myDriver2.sys ...]

この構文を使用する場合、すべてのドライバー分離違反は引き続き報告されますが、HLK に対して現在適用されていない違反は、エラーではなく警告として報告されます。 警告として表示されているものは HLK エラーを引き起こしません。また、/onecheck でドライバー分離チェックを有効にして、違反が発生したときにバグチェックを生成しても、システムはバグチェックを行いません。

カーネル デバッガーを使用してイベントを表示する場合、エラーと見なされるイベントの前に DRIVER_ISOLATION_VIOLATION が付けられますが、警告のプレフィックスには DRIVER_ISOLATION_WARNING が付きます。

システム イベント ログでイベントを表示する場合、ErrorLevel 属性が 0 のイベントはエラーと見なされ、別の ErrorLevel 値を持つイベントはエラーとは見なされません。 詳細については、以下の「システム イベント ログでの違反の表示」セクションを参照してください。

システム イベント ログでの違反の表示

ドライバー検証ツール違反は、プロバイダー Microsoft-Windows-Kernel-XDV からシステム イベント ログに報告され、イベント ID は、4 です。 Windows 11 24H2 以降では、イベントには ErrorLevel 値が含まれます。 ErrorLevel値が 0 のイベントは、違反が生成されたときに、アクティブなドライバー分離モード (完全なドライバー分離コンプライアンスと WHCP 分離コンプライアンス) に従ってエラーと見なされます。 他の ErrorLevel 値を持つイベントは、エラーとは見なされません。 たとえば、次の属性を持つイベントはエラーと見なされます。

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should not use absolute paths. Detected opening of unisolated registry key \Registry\Machine\System\CurrentControlSet\Services\ExampleDriver\Parameters
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0x0

これらの属性を持つイベントは、エラーとはみなされません。

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should only use key handles returned from WDF or WDM APIs. Detected querying of value under unisolated registry key \REGISTRY\MACHINE\SYSTEM\ControlSet001\Control
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0xf4240

イベント ビューアー アプリケーションを使用してシステム イベント ログを表示する場合は、アプリケーションの右側にあるメニューで [現在のログのフィルター] をクリックしてログのビューをフィルター処理できます。 ポップアップ表示されるダイアログで、[XML] タブに移動してクエリを手動で編集すると、このクエリを使用してシステム イベント ログをフィルター処理し、エラーと見なす DV 違反のみを表示できます。

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

イベント ログのビューをフィルター処理して、特定の時間 (テスト成功が開始された時刻の後など) にエラーと見なされるすべての DV 違反にフィルターを適用する場合は、次の操作を実行できます。

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime&gt;='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

または、読み込んで表示できる XML ファイルが必要な場合は、wevtutil を使用して、同じクエリに基づいてこのような XML を生成できます。

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime>='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

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

検証エラーの修正

1. レガシ デスクトップ UMDF ドライバー プロジェクトを　Windows ドライバーに切り替えた場合は、バイナリをビルドするときに、適切なライブラリが含まれていることを確認します。 プロジェクトを長押し (または右クリック) し、[プロパティ] を選びます。 リンカー>入力に移動します。 追加の依存関係 には以下が含まれている必要があり:

   %AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
   

   OneCore SKUsをターゲットにするための他のリンカー オプションを確認するには、 OneCore用の建築 を参照。

2. 許可されない API の呼び出しを一度に 1 つずつ削除または置換し、エラーがなくなるまでツールを再実行します。

3. 場合によっては、これらの呼び出しを、デスクトップ専用 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

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

1. プロジェクトのプロパティを開き、 全般に移動し、 アウトプットディレクトリ の名前を次のように変更します。

   $(SolutionDir)$(Platform)\$(ConfigurationName)\
   

2. ソリューションをリビルドします。

ApiValidator に関する既知の問題

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