驗證 Windows 驅動程式

發行項
04/05/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 來停止系統，並在發生違規時產生具有詳細數據的記憶體轉儲。您可以使用第一種方法啟動驅動程序開發，然後在驅動程式接近完成時切換至第二個。

若要在發生違規時檢視違規，請先連接核心調試程式，然後使用下列命令。重新啟動啟用 DV 設定之後，您可以在核心調試程式輸出中監視違規。

若要在單一驅動程式上啟用驅動程式隔離檢查：

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 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 二進位檔。