Memvalidasi Driver Windows

Gunakan alat InfVerif, Driver Verifier Driver Isolation Checks, dan ApiValidator untuk menguji paket driver Anda untuk kepatuhan dengan persyaratan Driver Windows yang dijelaskan dalam Mulai mengembangkan 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 dari Mulai mengembangkan 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 registri dan sistem file membaca dan menulis yang tidak diizinkan untuk paket driver terisolasi.

Anda dapat melihat pelanggaran saat terjadi dalam debugger kernel, Anda dapat meninjau pelanggaran seperti yang dilaporkan dalam log peristiwa Sistem, 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 dan kedua, lalu beralih ke yang kedua saat driver Anda mendekati penyelesaian.

Untuk mengaktifkan pemeriksaan isolasi driver sehingga akan dilaporkan melalui debugger kernel dan log peristiwa Sistem tetapi tidak memeriksa bug sistem:

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

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

verifier /onecheck /rc 33 36 /driver myDriver1.sys [myDriver2.sys ...]

Terlepas dari metode pemantauan mana yang Anda pilih, 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 seperti yang terlihat di debugger kernel:

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.

Catatan

DV tidak ingin membanjiri pengguna dengan deluge laporan pelanggaran yang sama, sehingga memiliki mekanisme pembatasan di mana dapat membatasi pelaporan setiap kesalahan unik. Dimulai dengan Windows 11 24H2, untuk memastikan Anda melihat serangkaian pelanggaran Isolasi Driver lengkap untuk setiap eksekusi pengujian atau serangkaian pengujian yang diberikan, Anda dapat meminta agar pembatasan agar pelanggaran Isolasi Driver diatur ulang menggunakan:

verifier /dif 33 /action 1

Jika Anda tidak melakukan ini sebelum menjalankan pengujian, maka Anda mungkin tidak melihat pelanggaran tertentu selama menjalankan pengujian Anda jika pelanggaran tersebut sudah terjadi sebelum pengujian dimulai.

Kepatuhan WHCP

Saat ini, program Windows Hardware Compatibility Program (WHCP) tidak mengamanatkan isolasi paket driver penuh. Namun, dimulai dengan Windows 11 24H2, program WHCP dimulai termasuk persyaratan terkait isolasi driver. Untuk mengaktifkan tingkat validasi isolasi paket driver yang sama seperti yang dilakukan Kit Lab Perangkat Keras (HLK) sebagai bagian dari memberlakukan persyaratan WHCP, Anda akan menggunakan sintaks berikut:

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

Saat menggunakan sintaks ini, semua pelanggaran isolasi driver masih akan dilaporkan, tetapi yang saat ini tidak diberlakukan untuk HLK akan dilaporkan sebagai peringatan alih-alih kesalahan. Yang terdaftar sebagai peringatan tidak akan menyebabkan kegagalan HLK dan tidak akan menyebabkan sistem memeriksa bug jika Anda mengaktifkan pemeriksaan isolasi driver dengan /onecheck untuk membuatnya menghasilkan pemeriksaan bug ketika pelanggaran terjadi.

Saat melihat peristiwa dengan debugger kernel, yang dianggap sebagai kesalahan akan diawali dengan DRIVER_ISOLATION_VIOLATION sementara yang merupakan peringatan akan diawali dengan DRIVER_ISOLATION_WARNING.

Saat melihat peristiwa di log peristiwa Sistem, peristiwa dengan ErrorLevel atribut 0 dianggap sebagai kesalahan dan peristiwa dengan nilai lain ErrorLevel tidak dianggap sebagai kesalahan. Silakan lihat bagian "Melihat pelanggaran di log peristiwa Sistem" di bawah ini untuk informasi lebih lanjut.

Menampilkan pelanggaran di log peristiwa Sistem

Pelanggaran pemverifikasi driver dilaporkan dalam log peristiwa Sistem dari penyedia Microsoft-Windows-Kernel-XDV dan dengan ID peristiwa '4'. Pada Windows 11 24H2 dan yang lebih baru, peristiwa akan berisi ErrorLevel nilai. Peristiwa dengan ErrorLevel nilai 0 dianggap sebagai kesalahan sesuai dengan mode isolasi driver aktif (kepatuhan isolasi driver penuh vs kepatuhan isolasi WHCP) ketika pelanggaran dihasilkan. Peristiwa dengan nilai lain ErrorLevel tidak dianggap sebagai kesalahan. Misalnya, peristiwa dengan atribut ini akan dianggap sebagai kesalahan:

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

Meskipun peristiwa dengan atribut ini tidak akan dianggap sebagai kesalahan:

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

Jika Anda menggunakan aplikasi Pemantau Peristiwa untuk melihat log peristiwa Sistem, Anda dapat memfilter tampilan log menggunakan menu di sisi kanan aplikasi dengan mengklik "Filter Log Saat Ini". Pada dialog yang muncul, jika Anda masuk ke tab XML dan mengedit kueri secara manual, Anda bisa menggunakan kueri ini untuk memfilter log peristiwa Sistem hanya untuk pelanggaran DV yang harus dianggap sebagai kesalahan:

<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>

Jika Anda ingin memfilter tampilan log peristiwa ke semua pelanggaran DV yang harus dianggap sebagai kesalahan setelah waktu tertentu (misalnya setelah waktu lulus pengujian dimulai), Anda dapat melakukan:

<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>

Atau jika Anda lebih suka file XML yang dapat Anda muat untuk dilihat, Anda dapat menggunakan wevtutil untuk menghasilkan XML tersebut berdasarkan kueri yang sama:

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

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 Mulai mengembangkan 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.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2024-08-14