驗證 Windows 驅動程式

發行項
08/14/2024

使用 InfVerif、驅動程式驗證器驅動程式隔離檢查和 ApiValidator 工具來測試驅動程式套件，以符合開始使用 Windows 驅動程式中所述的 Windows 驅動程式需求。

InfVerif

InfVerif 是一種工具，可驗證 INF 語法，並檢查 INF 是否符合需求和限制。

使用 InfVerif 搭配 /w 來確認 Windows 驅動程式：

符合 DCH 設計原則的宣告式（D） 原則
符合開始使用 Windows 驅動程式的驅動程式套件隔離需求

如需詳細資訊，請參閱從命令行執行 InfVerif。

InfVerif 會使用 '/w' 自變數來驗證驅動程序隔離需求，如下所示：

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

如果 InfVerif 在使用 /w 進行驗證時沒有報告任何錯誤，INF 就會符合 Windows 驅動程式的驅動程式套件隔離需求。

以目前和舊版 Windows 為目標

如果您的 INF 包含最新版 Windows 中引進的語法，例如從 Windows 10 版本 1809 開始提供的 INF AddEventProvider 指示詞，而且您也想要以舊版 Windows 為目標，請使用 INF 裝飾來標記版本特定的 INF 專案。如需示範如何使用 OS 版本裝飾的範例程式代碼，請參閱結合平臺延伸模組與作業系統版本。

使用 OS 版本裝飾的 INF 檔案可能會失敗 InfVerif，因為舊版 Windows 可能不支援驅動程式隔離需求。若要驗證這類 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 來停止系統，並在發生違規時產生具有詳細數據的記憶體轉儲。您可以使用第一個和第二種方法來啟動驅動程式開發，然後在驅動程式接近完成時切換到第二個。

若要啟用驅動程式隔離檢查，以便透過內核調試程式和系統事件記錄檔回報驅動程式隔離檢查，但不會檢查系統：

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 驅動程式隔離檢查，以協助提早攔截驅動程式隔離違規。

注意

DV 不想淹沒相同違規報告的使用者，因此其具有節流機制，其可能會對報告每個唯一錯誤進行節流。從 Windows 11 24H2 開始，若要確定您看到任何給定回合測試或一系列測試的完整驅動程式隔離違規，您可以要求使用下列專案來重設驅動程式隔離違規的節流：

verifier /dif 33 /action 1

如果您在執行測試之前未這麼做，則在測試執行期間，如果測試啟動之前已經發生這些違規，則可能不會看到某些違規。

WHCP 合規性

目前， Windows 硬體相容性計劃（WHCP）程式不會強制完全驅動程式套件隔離。不過，從 Windows 11 24H2 開始，WHCP 程式會開始包括驅動程式隔離相關需求。若要啟用與硬體實驗室套件（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 的系統事件記錄檔中會報告驅動程式驗證程序違規，且事件標識碼為『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 API 來存取登錄時，例如 WdfRegistryCreateKey、WdfRegistryOpenKey 或 WdfRegistryQueryValue，登錄存取會透過 wdf01000.sys 進行，而不是直接透過 KMDF 驅動程式二進位檔進行。若要檢視 KMDF 驅動程式二進位檔所造成的違規，除了 KMDF 驅動程式二進位檔之外，還要對wdf01000.sys啟用驅動程式隔離檢查。請注意，當您這樣做時，您會看到系統上所有使用 WDF 進行登錄存取的 KMDF 驅動程序違規。

ApiValidator

ApiValidator 工具會驗證您的二進位檔呼叫的 API 是否適用於 Windows 驅動程式。如果您的二進位檔呼叫的 API 不在 Windows 驅動程式的有效 API 集合之外，此工具會傳回錯誤。此工具是適用於 Windows 10 的 WDK 的一部分。

ApiValidator 會驗證驅動程式是否支援 API 分層，這是 Windows 驅動程式的其中一個需求。如需完整的需求清單，請參閱開始使用 Windows 驅動程式。

在 Visual Studio 中執行 ApiValidator

如果驅動程式專案的目標平臺屬性設定為 Windows Driver，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 驅動程式，請確認您在建置二進位檔時包含正確的連結庫。選取並按住專案（或以滑鼠右鍵按兩下），然後選擇 [屬性]。流覽至Linker-Input>。其他 相依性 應包含：
```
%AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
```
若要檢閱以 OneCore SKU 為目標的其他連結器選項，請參閱建置 OneCore。
拿掉或取代一次不允許的 API 呼叫，並重新執行工具，直到沒有錯誤為止。
在某些情況下，您可以將這些呼叫取代為僅限桌面 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\universalDIS<arch>。

重要事項：

ApiValidator 需要下列檔案:ApiValidator.exe、Aitstatic.exe、Microsoft.Kits.Drivers.ApiValidator.dll 和 UniversalDDIs.xml。
UniversalDDIs.xml必須符合正在驗證的二進位架構，例如 x64 驅動程式使用 x64 UniversalDDI.xml
ApiValidator 一次只會測試一個架構
如需其他資訊，請參閱下面的已知 ApiValidator 問題

使用下列語法：

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

例如，若要驗證 WDK 中活動範例所呼叫的 API，請先在 Visual Studio 中建置範例。然後開啟命令提示字元並瀏覽至包含工具的目錄，例如 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 問題

ApiValidator 不會在 Arm64 上執行，因為 AitStatic 無法在 Arm64 上運作。
Arm64 二進位檔可以在 x64 計算機上進行測試，但無法在 x86 計算機上進行測試。
ApiValidator 可以在 x86 上執行，以測試 x86 二進位檔和 Arm 二進位檔。
ApiValidator 可以在 x64 上執行，以測試 x86、x64、Arm 和 Arm64 二進位檔。

共用方式為