Menggunakan Inflight Trace Recorder (IFR) di Driver KMDF dan UMDF 2
Mulai dari Windows 10, Anda dapat membangun driver KMDF atau UMDF sehingga mendapatkan informasi penelusuran kesalahan driver tambahan melalui pra-pemrosesan jejak perangkat lunak Windows. Fitur ini, yang disebut Inflight Trace Recorder (IFR), tersedia mulai dari KMDF versi 1.15 dan UMDF versi 2.15.
Inflight Trace Recorder adalah ekstensi pelacakan perangkat lunak WPP. Tidak seperti pelacakan WPP, Inflight Trace Recorder terus berfungsi tanpa konsumen pelacakan terlampir. Kerangka kerja menulis pesan ke buffer melingkar, dan driver Anda juga dapat menambahkan pesannya sendiri. Setiap driver memiliki log sendiri, sehingga beberapa perangkat yang terkait dengan driver berbagi satu log.
Jika Anda mengaktifkan IFR di biner driver Anda, IFR hadir dan berjalan selama masa pakai driver Anda. Anda tidak perlu memulai sesi pengumpulan jejak eksplisit.
Log disimpan dalam memori yang tidak dapat di-halaman, sehingga dapat dipulihkan setelah crash sistem. Selain itu, log Inflight Trace Recorder disertakan dalam file minidump kecuali ketika driver yang bertanggung jawab tidak ditentukan atau jika crash adalah batas waktu host.
Cara mengaktifkan Inflight Trace Recorder dan mengirim pesan dari driver Anda
Di Microsoft Visual Studio, lakukan langkah-langkah berikut:
Buka Halaman Properti untuk proyek driver Anda. Klik kanan proyek driver di Penjelajah Solusi dan pilih Properti. Di Halaman Properti untuk driver, pilih Properti Konfigurasi, lalu Pelacakan Wpp. Pada menu Umum , atur Jalankan Pelacakan WPP ke Ya.
Navigasi ke Opsi Properties-Wpp> Tracing-Function> dan Makro dan pilih Aktifkan Perekam WPP.
Pada menu yang sama, atur Pindai Data Konfigurasi ke file yang berisi informasi jejak Anda, misalnya Trace.h.
Di setiap file sumber yang memanggil makro WPP, tambahkan arahan #include yang mengidentifikasi file header pesan pelacakan (TMH). Nama file harus memiliki format <driver-source-file-name.tmh.>
Misalnya, jika driver Anda terdiri dari dua file sumber, yang disebut MyDriver1.c dan MyDriver2.c, maka MyDriver1.c harus berisi:
#include "MyDriver1.tmh"
dan MyDriver2.c harus berisi:
#include "MyDriver2.tmh"
Saat Anda membuat driver di Visual Studio, prapemrosem WPP menghasilkan . file tmh .
Tentukan makro WPP_CONTROL_GUIDS dalam file header. Makro ini mendefinisikan GUID dan melacak bendera untuk pesan pelacakan driver Anda.
Sampel driver Osrusbfx2 mendefinisikan GUID kontrol tunggal dan tujuh bendera pelacakan dalam file header Trace.h, seperti yang ditunjukkan dalam contoh berikut:
#define WPP_CONTROL_GUIDS \ WPP_DEFINE_CONTROL_GUID(OsrUsbFxTraceGuid, \ (d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \ WPP_DEFINE_BIT(DBG_INIT) /* bit 0 = 0x00000001 */ \ WPP_DEFINE_BIT(DBG_PNP) /* bit 1 = 0x00000002 */ \ WPP_DEFINE_BIT(DBG_POWER) /* bit 2 = 0x00000004 */ \ WPP_DEFINE_BIT(DBG_WMI) /* bit 3 = 0x00000008 */ \ WPP_DEFINE_BIT(DBG_CREATE_CLOSE) /* bit 4 = 0x00000010 */ \ WPP_DEFINE_BIT(DBG_IOCTL) /* bit 5 = 0x00000020 */ \ WPP_DEFINE_BIT(DBG_WRITE) /* bit 6 = 0x00000040 */ \ WPP_DEFINE_BIT(DBG_READ) /* bit 7 = 0x00000080 */ \ )Dalam contoh ini:
- OsrUsbFxTraceGuid adalah nama yang mudah diingat untuk GUID {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB}.
- Bendera pelacakan digunakan untuk membedakan antara pesan jejak yang dihasilkan karena driver menangani berbagai jenis permintaan I/O.
Driver Anda (KMDF dan UMDF 2) harus memanggil WPP_INIT_TRACING untuk driver Kernel-Mode dengan objek driver dan jalur registri, biasanya dari DriverEntry:
WPP_INIT_TRACING( DriverObject, RegistryPath );Untuk menonaktifkan pelacakan, driver KMDF dan UMDF 2 memanggil WPP_CLEANUP untuk Driver Kernel-Mode dari EvtCleanupCallback atau EvtDriverUnload:
WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));Makro WPP_CLEANUP mengambil parameter jenis PDRIVER_OBJECT, jadi jika DriverEntry driver Anda gagal, Anda dapat melewati panggilan WdfDriverWdmGetDriverObject dan sebaliknya memanggil WPP_CLEANUP dengan penunjuk ke objek driver WDM.
Karena driver UMDF menggunakan tanda tangan mode kernel makro ini untuk menginisialisasi dan membersihkan pelacakan, panggilan terlihat identik untuk KMDF dan UMDF.
Gunakan makro DoTraceMessage , atau versi makro yang dikustomisasi , di driver Anda untuk membuat pesan pelacakan.
Contoh berikut menunjukkan bagaimana driver Osrusbfx2 menggunakan fungsi TraceEvents dalam sebagian kode yang dikhususkan untuk menangani permintaan baca:
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) { TraceEvents(TRACE_LEVEL_ERROR, DBG_READ, "Transfer exceeds %d\n", TEST_BOARD_TRANSFER_BUFFER_SIZE); status = STATUS_INVALID_PARAMETER; }Panggilan ke TraceEvents menghasilkan pesan pelacakan jika pengontrol pelacakan memungkinkan tingkat TRACE_LEVEL_ERROR dan bendera pelacakan DBG_READ . Pesan mencakup nilai konstanta yang ditentukan driver TEST_BOARD_TRANSFER_BUFFER_SIZE.
Untuk mengubah ukuran buffer melingkar yang digunakan log driver, ubah nilai registri LogPages di lokasi registri berikut:
SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<YourDriver>\Parameters\Wdf
<HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\YourDriver>\Parameters\Wdf
Ini adalah nilai jenis REG_DWORD yang berisi ukuran buffer log yang dialokasikan, di halaman. Nilai yang valid adalah antara 0x1 dan 0x10.
Untuk driver KMDF
- Muat perintah RCDRKD dengan mengetikkan .load rcdrkd.dll di debugger.
- Gunakan ekstensi !wdfkd.wdfldr untuk menampilkan informasi tentang driver yang saat ini terikat secara dinamis ke Windows Driver Frameworks (WDF).
- Gunakan !rcdrkd.rcdrlogdump dan !rcdrkd.rcdrcrashdump untuk melihat pesan yang disediakan driver.
- Gunakan !wdfkd.wdflogdump atau !wdfkd.wdfcrashdump untuk melihat pesan yang disediakan kerangka kerja.
Penelusuran kesalahan langsung driver UMDF
Gunakan ekstensi !wdfkd.wdfldr untuk menampilkan informasi tentang driver yang saat ini terikat secara dinamis ke WDF. Temukan driver mode pengguna Anda. Masukkan proses host terkait.
Ketik !wdfkd.wdflogdump<YourDriverName.dll><Flag> , di mana <Bendera> adalah:
- 0x1 – Kerangka kerja gabungan dan log driver
- 0x2 – Log driver
- 0x3 – Log kerangka kerja
Jika tidak ada log driver untuk driver yang ditentukan, ekstensi hanya menampilkan log kerangka kerja.
Melihat log Inflight Trace Recorder setelah driver UMDF mengalami crash
Dari WinDbg, pilih File-Open> Crash Dump, dan tentukan file minidump yang ingin Anda debug.
Ketik !wdfkd.wdfcrashdump <YourDriverName.dll><ID proses opsi> host><driver, di mana <Opsi> adalah:
- 0x1 – Kerangka kerja gabungan dan log driver
- 0x2 – Log driver
- 0x3 – Log kerangka kerja
Jika Anda tidak menentukan driver, !wdfcrashdump menampilkan informasi untuk semua driver. Jika Anda tidak menentukan proses host, dan hanya ada satu, ekstensi menggunakan proses host tunggal. Jika Anda tidak menentukan proses host dan ada lebih dari satu, ekstensi mencantumkan proses host aktif.
Jika informasi log yang disimpan di minidump tidak cocok dengan nama yang dimasukkan, minidump tidak berisi log driver.
Jika Anda tidak memiliki debugger yang tersambung, Anda masih dapat mengakses driver dan log kerangka kerja. Untuk mempelajari caranya, lihat Video: Mengakses log IFR driver tanpa debugger.
Untuk informasi selengkapnya tentang menambahkan pesan pelacakan ke driver Anda, lihat Menambahkan Makro WPP ke Driver.
Artikel terkait
Cara Mengaktifkan Debugging Driver UMDF
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk