Nilai Registri untuk Penelusuran Kesalahan Driver WDF

Artikel ini menjelaskan nilai registri yang dapat diatur oleh driver WDF. Ini berlaku untuk driver KMDF dan driver UMDF yang dimulai dengan UMDF versi 2.

Kecuali ditentukan lain dalam bagian di bawah ini, nilai registri berikut terletak di bawah subkuntang Parameters\Wdf driver.

• Untuk driver KMDF, subkunjen ini terletak di , di HKEY_LOCAL_MACHINE\System\CurrentControlSet\Servicesbawah nama layanan driver.
• Untuk driver UMDF, subkunjen ini terletak di , di HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Servicesbawah nama layanan driver.

Subkuntang untuk driver selalu menggunakan nama layanan driver, bahkan jika nama file biner driver berbeda dari nama layanan.

DbgBreakOnError

REG_DWORD

Jika diatur ke nilai bukan nol, kerangka kerja memecah ke debugger saat driver memanggil WdfVerifierDbgBreakPoint. (Jika nilai VerifierOn diatur, kerangka kerja akan masuk ke debugger meskipun nilai DbgBreakOnError tidak ada.) Lihat contoh kode di bagian VerifierOn .

DbgPrintOn

REG_DWORD

• Untuk driver KMDF, atur nilai ini di HKLM\SYSTEM\CurrentControlSet\Control\Wdf\Kmdf\Diagnostics bawah kunci registri.
• Untuk driver UMDF, tetapkan nilai ini di HKLM\System\CurrentControlSet\Control\Wdf\Umdf\Diagnostics bawah kunci registri.

Driver mungkin perlu membuat subkunci Diagnostik opsional.

Jika diatur ke nilai bukan nol, loader kerangka kerja mengirimkan berbagai pesan ke debugger kernel saat memuat driver dan mengikatnya ke versi pustaka kerangka kerja, atau saat sedang membongkar driver.

DbgWaitForSignalTimeoutInSec

REG_DWORD, kerangka kerja versi 1.11 dan yang lebih baru

Mulai Windows 8, ketika VerifierOn dan DbgBreakOnError diatur ke nilai bukan nol, driver dapat mengubah periode batas waktu default untuk masuk ke debugger dengan mengatur DbgWaitForSignalTimeoutInSec.

DebugModeBinaries

REG_MULTI_SZ, khusus UMDF

Nilai registri ini terletak di HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

Nilai ini menentukan nama biner driver yang akan dimuat dalam mode debug. Untuk mengaktifkan mode debug untuk biner driver X.DLL, Y.DLL dan Z.DLL, misalnya, nilai ini akan diatur ke X.DLL\0Y.DLL\0Z.DLL\0\0.

DebugModeFlags

REG_DWORD, khusus UMDF

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\DebugMode.

Nilai	Deskripsi
0x01	Aktifkan mode debug. Pengaturan ini menonaktifkan fungsi hidupkan ulang otomatis yang dijelaskan dalam Menggunakan Kumpulan Perangkat di Driver UMDF.
0x02	Nonaktifkan pengumpulan perangkat. Untuk informasi selengkapnya tentang pengumpulan perangkat, lihat Menggunakan Kumpulan Perangkat di Driver UMDF.
0x04	Nonaktifkan batas waktu.

Saat Anda menggunakan opsi F5 di Microsoft Visual Studio, ketiga bendera diatur untuk driver yang disebarkan.

EnhancedVerifierOptions

REG_DWORD, kerangka kerja versi 1.9 dan yang lebih baru

Nilai ini berisi bitmap. Setiap bit mewakili opsi pemverifikasi tambahan yang dapat diaktifkan pengguna dengan mengatur bit.

Nilai bit:

0x1: Jika diatur, pemverifikasi memeriksa apakah setiap fungsi panggilan balik peristiwa driver melakukan hal berikut:

• Mengembalikan pada IRQL yang sama tempat IRQL dipanggil. Jika nilainya berbeda, pemeriksaan bug WDF_VIOLATION terjadi dengan kode kesalahan 0xE.

• Sebelum kembali, keluar dari semua wilayah penting yang dimasukkannya. Jika fungsi panggilan balik kembali dalam wilayah penting yang dimasukkannya, pemeriksaan bug WDF_VIOLATION terjadi dengan kode kesalahan 0xF.

0x10000: Jika diatur, dan jika driver telah mengaktifkan kemajuan penerusan yang dijamin untuk antrean I/O, kerangka kerja mensimulasikan situasi memori rendah untuk setiap permintaan I/O antrean.

0x20000: Jika diatur, dan jika driver telah mengaktifkan kemajuan penerusan yang dijamin untuk antrean I/O, kerangka kerja mensimulasikan situasi memori rendah untuk beberapa permintaan I/O yang dipilih secara acak.

ForceLogsInMiniDump

REG_DWORD

Atur ke nilai bukan nol untuk menyebabkan kerangka kerja menyertakan informasi dari pencatat peristiwanya dalam file crash dump.

HostFailKdDebugBreak

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF.

Jika nilai ini bukan nol dan debugger kernel terhubung ke komputer, reflektor masuk ke debugger kernel sebelum mengakhiri proses host. HostFailKdDebugBreak dinonaktifkan secara default di Windows 7 dan sistem operasi yang lebih lama. Mulai Windows 8, HostFailKdDebugBreak diaktifkan secara default.

Reflektor juga masuk ke debugger kernel jika ada penghentian proses host yang tidak terduga (misalnya oleh komponen non-UMDF atau karena pengecualian yang tidak tertangani). Jika ada beberapa tumpukan perangkat yang dikumpulkan dalam proses host yang sedang dihentikan, reflektor masuk ke debugger beberapa kali, sekali untuk setiap tumpukan perangkat yang dimuat dalam proses host.

HostProcessDbgBreakOnDriverLoad (khusus driver)

REG_DWORD, khusus UMDF, berfungsi dengan driver UMDF 1.x/2.x yang berjalan pada komputer target dengan UMDF versi 2.31 atau yang lebih baru

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<service name>\Parameters\Wdf.

Nilai ini hanya memengaruhi driver UMDF yang ditentukan.

Berisi nilai penundaan dalam hitungan detik. Menyebabkan WUDFHost mencoba menyambungkan ke debugger selama jumlah detik yang ditentukan setelah driver dimuat.

Selama periode penundaan yang ditentukan, proses host mencari debugger mode pengguna sekali sedetik dan berhenti jika terhubung. Jika debugger mode pengguna tidak dilampirkan dalam periode ini dan bit tinggi di diatur (0x80000000), kerangka kerja melakukan satu upaya untuk masuk ke debugger mode kernel. Lihat bagian tentang HostProcessDbgBreakOnStart di atas misalnya.

Agar perubahan pada nilai registri UMDF berlaku, Anda harus me-reboot komputer.

HostProcessDbgBreakOnDriverLoad (global)

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. Anda dapat mengaturnya dengan menggunakan alat Pemverifikasi WDF (WdfVerifier.exe) di WDK. Nilai ini mempengaruhi semua driver UMDF pada sistem.

Contains a delay value in seconds. Menyebabkan WUDFHost menunda jumlah detik yang ditentukan setelah driver dimuat. Perilaku untuk HostProcessDbgBreakOnDriverLoad sama dengan yang dijelaskan untuk HostProcessDbgBreakOnStart.

Menentukan HostProcessDbgBreakOnStart atau HostProcessDbgBreakOnDriverLoad menyebabkan kerangka kerja menonaktifkan batas waktu UMDF lainnya (misalnya, operasi Plug and Play). Ini berarti bahwa jika driver Anda menyebabkan batas waktu yang berlebihan, menggunakan nilai-nilai ini dapat mengakibatkan driver Anda menyebabkan crash fatal pada target.

HostProcessDbgBreakOnStart

REG_DWORD, UMDF-only

This registry value is located in HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\{193a1820-d9ac-4997-8c55-be817523f6aa}. You can set it by using the WDF Verifier tool (WdfVerifier.exe) in the WDK. This value affects all UMDF drivers on the system.

Contains a delay value in seconds. During the specified delay period, the host process looks for the user-mode debugger once a second and breaks in if one is connected. Jika debugger mode pengguna tidak dilampirkan dalam periode ini dan bit tinggi di HostProcessDbgBreakOnStart diatur (0x80000000), kerangka kerja melakukan satu upaya untuk masuk ke debugger mode kernel. Contohnya:

Nilai	Hasil
0x00000004	Kerangka kerja mencoba menyambungkan ke debugger mode pengguna sekali detik selama 4 detik. Kerangka kerja tidak pernah mencoba menyambungkan ke debugger mode kernel.
0x80000000	Kerangka kerja melakukan satu upaya untuk terhubung ke debugger mode pengguna. Jika debugger mode pengguna tidak terpasang, kerangka kerja mencoba menyambungkan ke debugger mode kernel.
0x80000004	Kerangka kerja mencoba menyambungkan ke debugger mode pengguna sekali detik selama 4 detik. Jika debugger mode pengguna tidak terpasang dalam waktu 4 detik, kerangka kerja mencoba menyambungkan ke debugger mode kernel.

Anda juga dapat mengatur nilai registri ini dengan menggunakan alat Pemverifikasi WDF (WdfVerifier.exe) yang disertakan dalam WDK.

LogPages

REG_DWORD

Atur ke jumlah halaman memori yang ditetapkan kerangka kerja ke pencatat peristiwanya. Jika nilai tidak terdefinisi, kerangka kerja menggunakan nilai default satu halaman. Nilai maksimum yang dapat Anda tetapkan adalah 16 untuk komputer yang memiliki halaman memori berukuran 4 kilobyte (prosesor x86 dan amd64) dan 8 untuk komputer yang memiliki halaman memori berukuran 8 kilobyte (prosesor ia64). (Sistem operasi mungkin tidak menulis konten log ke file crash dump jika sejumlah besar halaman ditentukan.) Gunakan direktif AddService dan direktif AddReg untuk mengatur nilai ini dalam file INF Anda, sebagai berikut:

[xxx.NT.Services]
AddService = yyy, 2, zzz.AddService

[zzz.AddService]
DisplayName   = %aaa\bbb%
ServiceType   = 1
StartType     = 3
ErrorControl  = 1
ServiceBinary = %12%\ddd.SYS
AddReg         = eee.AddReg

[eee.AddReg]
HKR, Parameters\Wdf, LogPages,   0x00010001, 3 ; KMDF IFR size

ObjectLeakDetectionLimit

Dalam beberapa kasus, objek kerangka kerja salah diindukkan dan tidak dihapus setelah digunakan. Anda dapat menggunakan ObjectLeakDetectionLimit dan ObjectsForLeakDetection untuk menentukan jumlah maksimum objek dan apa yang harus terjadi ketika ambang batas ini terlampaui.

REG_DWORD

Menentukan jumlah maksimum objek dari jenis yang dijelaskan dalam kunci ObjectsForLeakDetection . Untuk mengontrol apakah melebihi ambang batas ini harus menyebabkan kerusakan debug atau bugcheck, atur kunci DbgBreakOnError . Batas diskalakan dengan jumlah perangkat yang diinstal, jadi jika driver membuat tiga objek WDFDEVICE, batasnya adalah tiga kali nilai yang ditentukan dalam ObjectLeakDetectionLimit.

ObjectsForLeakDetection

REG_MULTI_SZ

Gunakan dengan ObjectLeakDetectionLimit. Mencantumkan setiap nama jenis untuk diverifikasi. Misalnya, Anda dapat menentukan WDFDMATRANSACTION WDFDEVICE. Untuk menentukan semua jenis handel, gunakan * sebagai string. Jika kunci ObjectsForLeakDetection tidak ditentukan, defaultnya adalah memantau WDFREQUEST, WDFWORKITEM, WDFKEY, WDFSTRING, WDFOBJECT, dan WDFDEVICE.

Jika Anda menentukan WDFREQUEST, pemverifikasi hanya menghitung objek WDFREQUEST yang dibuat driver. Fitur ini saat ini tidak mendukung pelacakan tipe objek WDFMEMORY.

TrackHandles

REG_MULTI_SZ

Jika diatur ke daftar satu atau beberapa nama jenis handel objek kerangka kerja, dan jika VerifierOn diatur, kerangka kerja melacak referensi ke semua handel objek yang cocok dengan jenis handel yang ditentukan. Misalnya, jika daftar jenis handel terdiri dari string "WDFREQUEST WDFQUEUE", kerangka kerja melacak referensi ke semua objek permintaan dan objek antrean. Jika daftar berisi tanda bintang ("*"), kerangka kerja melacak semua handel objek.

VerboseOn

REG_DWORD

Jika diatur ke nilai bukan nol, pencatat peristiwa kerangka kerja merekam informasi tambahan yang dapat membantu Anda men-debug driver Anda, seperti entri ke dalam atau keluar dari jalur kode internal. Anda harus menetapkan nilai ini hanya saat Anda mengembangkan driver Anda. Lihat contoh kode di VerifierOn.

VerifierAllocateFailCount

REG_DWORD

Jika diatur ke nilai n, dan jika VerifierOn diatur, kerangka kerja gagal setiap upaya untuk mengalokasikan memori untuk objek driver setelah alokasi ke-n . Kegagalan ini membantu Anda menguji penanganan kondisi memori rendah driver Anda. Misalnya, jika Anda mengatur VerifierAllocateFailCount ke 2, setiap alokasi memori setelah alokasi kedua akan gagal. Nilai default untuk VerifierAllocateFailCount adalah 0xffffffff. Setelah mengatur VerifierAllocateFailCount, Anda dapat menonaktifkannya dengan mengaturnya ke (DWORD) -1 atau menghapus nilai sama sekali.

Perhatikan bahwa pemverifikasi menghitung alokasi yang diminta driver Anda dan alokasi yang diminta kerangka kerja atas nama driver Anda. Perhatikan juga bahwa jumlah alokasi yang mungkin terjadi untuk driver Anda dapat berubah dari satu rilis kerangka kerja ke kerangka kerja berikutnya.

VerifierOn

REG_DWORD

Atur ke nilai bukan nol untuk mengaktifkan Pemverifikasi KMDF, yang secara ekstensif memvalidasi status driver dan parameter fungsi. Anda harus mengatur VerifierOn dan DbgBreakOnError saat Anda mengembangkan driver Anda. Gunakan direktif AddService dan direktif AddReg untuk mengatur nilai-nilai ini di bagian Layanan dari file INF, misalnya:

[xxx_Inst.NT.Services]
AddService = xxx,%SPSVCINST_ASSOCSERVICE%,xxx_Service_Inst

[xxx_Service_Inst]
ServiceType   = %SERVICE_KERNEL_DRIVER%
StartType     = %SERVICE_BOOT_START%
ErrorControl  = %SERVICE_ERROR_NORMAL%
LoadOrderGroup = "Base"
ServiceBinary = %12%\xxx.sys
AddReg         = KMDFVerifierAddReg

[KMDFVerifierAddReg]
HKR, Parameters\Wdf,VerifierOn,0x00010001,1
HKR, Parameters\Wdf,VerboseOn,0x00010001,1
HKR, Parameters\Wdf,DbgBreakOnError,0x00010001,1

VerifyDownLevel

REG_DWORD, kerangka kerja versi 1.9 dan yang lebih baru

Jika diatur ke nilai bukan nol, dan jika driver dibangun dengan versi kerangka kerja yang lebih lama dari versi saat ini, pemverifikasi kerangka kerja menyertakan pengujian yang ditambahkan setelah driver dibuat. Jika nilai ini tidak ada atau diatur ke nol, pemverifikasi kerangka kerja hanya menyertakan pengujian yang ada saat driver dibangun.

Misalnya, jika driver Anda dibangun dengan versi 1.7 dari kerangka kerja, dan jika versi 1.9 kerangka kerja diinstal di komputer, mengatur VerifyDownLevel ke nonzero menyebabkan pemverifikasi menyertakan pengujian yang ditambahkan ke versi 1.9 dari pemverifikasi saat driver Anda berjalan.

VerifyOn

REG_DWORD

Atur ke nilai bukan nol untuk mengaktifkan makro WDFVERIFY yang ditentukan dalam Wdfassert.h, atau atur ke nol untuk menonaktifkan makro. Jika nilai VerifierOn diatur, VerifyOn secara implisit diatur ke bukan nol.