Memvalidasi Driver Windows

Artikel
04/05/2024

Gunakan alat InfVerif, Driver Verifier Driver Isolation Checks, dan ApiValidator untuk menguji paket driver Anda untuk kepatuhan dengan persyaratan Driver Windows yang dijelaskan dalam Memulai Driver Windows.

InfVerif

InfVerif adalah alat yang memvalidasi sintaks INF dan memeriksa apakah INF sesuai dengan persyaratan dan batasan.

Gunakan InfVerif dengan /w untuk memverifikasi bahwa Driver Windows:

Memenuhi prinsip deklaratif (D) Prinsip Desain DCH
Mematuhi persyaratan isolasi paket driver untuk Memulai Driver Windows

Untuk detail selengkapnya, lihat Menjalankan InfVerif dari baris perintah.

InfVerif memvalidasi persyaratan Isolasi Driver dengan argumen '/w', seperti yang ditunjukkan di sini:

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

Jika InfVerif tidak melaporkan kesalahan saat memvalidasi dengan /w, INF memenuhi persyaratan Isolasi Paket Driver Driver Windows.

Menargetkan versi Windows saat ini dan yang lebih lama

Jika INF Anda berisi sintaksis yang diperkenalkan dalam versi Windows terbaru, seperti INF AddEventProvider Directive yang tersedia mulai Windows 10 versi 1809 dan Anda juga ingin menargetkan versi Windows sebelumnya, gunakan dekorasi INF untuk menandai entri INF khusus versi. Untuk kode sampel yang menunjukkan cara menggunakan dekorasi versi OS, lihat Menggabungkan Ekstensi Platform dengan Versi Sistem Operasi.

File INF yang menggunakan dekorasi versi OS mungkin gagal InfVerif karena persyaratan Isolasi Driver mungkin tidak didukung pada versi Windows sebelumnya. Untuk memvalidasi INF seperti itu, Anda dapat menentukan versi Windows minimum tempat pemeriksaan Isolasi Driver harus diterapkan, menggunakan argumen '/wbuild'. Misalnya, file INF yang menggunakan direktif AddEventProvider mungkin menggunakan yang berikut ini untuk hanya menerapkan pemeriksaan Isolasi Driver ke Windows 10 versi 1809 dan yang lebih baru:

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

Pemeriksaan Isolasi Driver Verifier Driver

Agar memenuhi syarat sebagai Driver Windows, paket driver harus memenuhi persyaratan Isolasi Paket Driver. Mulai Windows 11, Driver Verifier (DV) dapat memantau biner kernel untuk baca dan tulis registri yang tidak diizinkan untuk paket driver terisolasi.

Anda dapat melihat pelanggaran saat terjadi di debugger kernel, atau Anda dapat mengonfigurasi DV untuk menghentikan sistem dan menghasilkan cadangan memori dengan detail ketika pelanggaran terjadi. Anda dapat memulai pengembangan driver dengan metode pertama, lalu beralih ke yang kedua saat driver Anda mendekati penyelesaian.

Untuk melihat pelanggaran saat terjadi, pertama-tama sambungkan debugger kernel lalu gunakan perintah berikut. Setelah reboot mengaktifkan pengaturan DV, Anda dapat memantau pelanggaran dalam output debugger kernel.

Untuk mengaktifkan pemeriksaan isolasi driver pada satu driver:

verifier /rc 33 36 /driver myDriver.sys

Untuk memeriksa lebih dari satu driver, pisahkan setiap nama driver dengan spasi:

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

Untuk mengonfigurasi DV ke pemeriksaan bug saat pelanggaran terjadi, gunakan sintaks berikut:

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

Anda harus memulai ulang untuk mengaktifkan pengaturan verifikasi. Untuk melakukan ini dari baris perintah, tentukan:

shutdown /r /t 0

Berikut adalah beberapa contoh pesan kesalahan:

Contoh: ZwCreateKey menyediakan jalur absolut penuh:

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

Contoh: ZwCreateKey menyediakan jalur relatif terhadap handel yang bukan dari API yang disetujui:

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

Pertimbangkan untuk menjalankan pengujian Dasar-Dasar Perangkat dengan pemeriksaan isolasi driver DV yang diaktifkan pada driver Anda untuk membantu menangkap pelanggaran isolasi driver lebih awal.

Driver KMDF

Ketika driver KMDF menggunakan API WDF untuk mengakses registri, seperti WdfRegistryCreateKey, WdfRegistryOpenKey, atau WdfRegistryQueryValue, akses registri terjadi melalui wdf01000.sys alih-alih biner driver KMDF secara langsung. Untuk melihat pelanggaran yang disebabkan oleh biner driver KMDF Anda, harap aktifkan pemeriksaan isolasi driver pada wdf01000.sys selain biner driver KMDF Anda. Perhatikan bahwa ketika Anda melakukan ini, Anda akan melihat pelanggaran dari semua driver KMDF pada sistem yang menggunakan WDF untuk akses registri mereka.

ApiValidator

Alat ApiValidator memverifikasi bahwa API yang dipanggil biner Anda valid untuk Driver Windows. Alat ini mengembalikan kesalahan jika biner Anda memanggil API yang berada di luar kumpulan API yang valid untuk Driver Windows. Alat ini adalah bagian dari WDK untuk Windows 10.

ApiValidator memvalidasi bahwa driver mendukung LAPISAN API, salah satu persyaratan untuk Driver Windows. Untuk daftar lengkap persyaratan, lihat Memulai Driver Windows.

Menjalankan ApiValidator di Visual Studio

Jika properti Platform Target proyek driver Anda diatur ke Driver Windows, Visual Studio menjalankan ApiValidator secara otomatis sebagai langkah pasca-build.

Untuk melihat semua pesan yang ditampilkan oleh ApiValidator, navigasikan ke Tools-Options-Projects>> dan Solutions-Build> and Run, dan atur verbositas output build proyek MSBuild ke Terperinci. Saat membangun dari baris perintah, tambahkan sakelar /v:detail atau /v:diag ke perintah build Anda untuk meningkatkan verbositas.

Untuk sampel driver umdf2_fx2, kesalahan validasi API lihat ini:

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

Memperbaiki kesalahan validasi

Jika Anda mengalihkan proyek driver UMDF desktop warisan ke Driver Windows, verifikasi bahwa Anda menyertakan pustaka yang benar saat membangun biner Anda. Pilih dan tahan (atau klik kanan) proyek dan pilih properti. Navigasi ke Linker-Input>. Dependensi Tambahan harus berisi:
```
%AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
```
Untuk meninjau opsi linker lain untuk menargetkan SKU OneCore, lihat Membangun untuk OneCore.
Hapus atau ganti panggilan API yang tidak diizinkan satu per satu dan jalankan ulang alat sampai tidak ada kesalahan.
Dalam beberapa kasus, Anda dapat mengganti panggilan ini dengan DDI alternatif yang tercantum di halaman referensi untuk DDI khusus desktop. Anda mungkin harus membuat kode solusi jika tidak ada penggantian yang sesuai. Jika perlu, tulis Driver Windows baru mulai dari templat driver di WDK.

Jika Anda melihat kesalahan seperti berikut ini, silakan lihat panduan di Membangun untuk 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

Menjalankan ApiValidator dari Prompt Perintah

Anda juga dapat menjalankan Apivalidator.exe dari prompt perintah. Dalam penginstalan WDK Anda, navigasikan ke C:\Program Files (x86)\Windows Kits\10\bin<arch> dan C:\Program Files (x86)\Windows Kits\10\build\universalDDIs<arch>.

Catatan Penting:

ApiValidator memerlukan file berikut: ApiValidator.exe, Aitstatic.exe, Microsoft.Kits.Drivers.ApiValidator.dll, dan UniversalDDIs.xml.
UniversalDDIs.xml harus cocok dengan arsitektur biner yang sedang divalidasi, misalnya untuk driver x64 menggunakan UniversalDDI.xml x64
ApiValidator hanya menguji satu arsitektur pada satu waktu
Lihat Masalah ApiValidator yang diketahui di bawah ini untuk informasi tambahan

Gunakan sintaks berikut:

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

Misalnya, untuk memverifikasi API yang dipanggil oleh sampel Aktivitas di WDK, pertama-tama buat sampel di Visual Studio. Kemudian buka prompt perintah dan navigasikan ke direktori yang berisi alat, misalnya C:\Program Files (x86\Windows Kits\10\bin\x64. Masukkan perintah berikut:

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"

Perintah menghasilkan output berikut:

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

Pemecahan Masalah ApiValidator

Jika ApiValidator.exe menghasilkan kesalahan format yang salah seperti berikut ini:

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

Gunakan solusi ini:

Buka properti Proyek, navigasikan ke Umum, dan ganti nama Direktori Output menjadi yang berikut:
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
Bangun kembali solusinya.

Masalah ApiValidator yang Diketahui

ApiValidator tidak berjalan di Arm64 karena AitStatic tidak berfungsi di Arm64.
Biner Arm64 dapat diuji pada mesin x64 tetapi tidak pada mesin x86.
ApiValidator dapat berjalan pada x86 untuk menguji biner x86 dan biner Arm.
ApiValidator dapat berjalan pada x64 untuk menguji biner x86, x64, Arm, dan Arm64.

Bagikan melalui