Bagikan melalui

Menggunakan Pencatat Peristiwa Kerangka Kerja

  • Artikel

WDF menyertakan pencatat jejak internal, kadang-kadang disebut In-flight Recorder (IFR) kerangka kerja. Pencatat WDF membuat log jejak yang berisi riwayat peristiwa terbaru untuk setiap driver WDF. Log jejak melacak kemajuan paket permintaan I/O (IRP) melalui kerangka kerja dan permintaan yang sesuai melalui driver. Setiap driver Kernel-Mode Driver Framework (KMDF) dan User-Mode Driver Framework (UMDF) memiliki log sendiri.

Pencatat WDF selalu diaktifkan. Untuk setiap log jejak, pencatat menyimpan rekaman peristiwa dalam buffer memori melingkar. Secara opsional, Anda dapat mengaktifkan verbositas, yang menyebabkan pencatat peristiwa merekam informasi tambahan yang dapat membantu Anda men-debug driver Anda, seperti entri ke dalam atau keluar dari jalur kode internal. Secara default, ukuran buffer adalah satu halaman memori dan verbositas dinonaktifkan. Anda dapat mengubah ukuran dan verbositas buffer dengan menyesuaikan nilai-nilai ini dalam aplikasi WdfVerifier. Perhatikan bahwa mengaktifkan verbositas mungkin menurunkan performa sistem.

Anda dapat menggunakan ekstensi debugger WDF untuk melihat dan menyimpan log WDF selama penelusuran kesalahan interaktif. Untuk melihat log WDF selama sesi penelusuran kesalahan:

  1. Muat simbol yang benar. Anda dapat menggunakan perintah debugger .symfix+ untuk menambahkan penyimpanan simbol publik Microsoft ke jalur simbol yang ada. Penyimpanan simbol publik mencakup simbol untuk biner WDF. Anda mungkin juga ingin memuat simbol untuk simbol driver Anda.

    Untuk informasi tambahan tentang cara mendapatkan simbol Jendela dan cara mengatur jalur simbol debugger, lihat dokumentasi yang disediakan dengan paket Windows Debugging .

  2. Muat pustaka ekstensiWdfkd.dll ke debugger Anda. Jika Anda menggunakan debugger kernel, Anda dapat melakukan ini dengan menggunakan perintah .load . Untuk memuat versi Wdfkd.dll yang benar, Anda perlu menentukan jalur yang sepenuhnya memenuhi syarat ke DLL. Misalnya, Anda akan menggunakan jalur berikut pada komputer host debugger berbasis x86:

    .load "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\winext\wdfkd.dll"

    Anda kemudian dapat mengonfirmasi bahwa ekstensi dimuat dengan menggunakan perintah !chain untuk menampilkan semua ekstensi yang dimuat.

    Untuk informasi selengkapnya tentang ekstensi debugger kerangka kerja, gunakan ekstensi !wdfhelp . Untuk informasi selengkapnya tentang debugger kernel, lihat dokumentasi yang disediakan dengan paket Debugging Windows .

  3. Jika driver Anda menggunakan kerangka kerja versi 1.11 atau yang lebih baru, dan Anda menggunakan debugger kernel dari Windows 8 atau yang lebih baru, Anda dapat melewati langkah ini.

    Jika driver Anda menggunakan versi kerangka kerja yang lebih lama dari 1.11, gunakan !wdftmffile atau !wdfsearchpath untuk menentukan file format pesan pelacakan khusus platform (.tmf), atau jalur ke file .tmf. File .tmf terletak di subdirektori khusus platform di WDK.

    Karena file .tmf spesifik versi, Anda harus menentukan file .tmf yang sesuai dengan versi pustaka runtime kerangka kerja yang saat ini berjalan. Misalnya, jika KMDF versi 1.9 berjalan pada komputer host:

    !wdftmffile c:\WinDDK\<version>\tools\tracing\x86\wdf01009.tmf

    Anda juga dapat mengatur jalur pencarian dengan mengatur variabel lingkungan TRACE_FORMAT_SEARCH_PATH. Perintah !wdftmffile lebih diutamakan daripada jalur pencarian yang diatur oleh variabel lingkungan.

    Untuk memverifikasi nomor versi kerangka kerja, Anda dapat menjalankan perintah ekstensi debugger !wdfldr dari debugger kernel.

  4. Gunakan ekstensi !wdflogdump untuk menampilkan rekaman pencatat peristiwa. Misalnya, cuplikan layar berikut dari jendela Perintah WinDbg menunjukkan contoh umum output dari !wdflogdump:

    Cuplikan layar output ekstensi !wdflogdump di jendela Perintah WinDbg.

Setiap baris dalam log kerangka kerja didahului oleh string yang disebut awalan pesan pelacakan. Pencatat jejak menambahkan awalan ini ke setiap pesan yang ditulis ke log. Secara default, awalan menyertakan sekumpulan elemen data standar, tetapi Anda dapat mengubah elemen default agar sesuai dengan kebutuhan khusus Anda. Anda dapat mengubah string awalan untuk driver WDF dengan mengatur variabel lingkungan TRACE_FORMAT_PREFIX atau dengan menggunakan perintah ekstensi debugger !wdfsettraceprefix .

Untuk mengatur variabel lingkungan, gunakan perintah yang mirip dengan yang berikut ini:

Set TRACE_FORMAT_PREFIX=%2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:

Perintah ini mengatur awalan pesan pelacakan ke yang berikut:

SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime

Anda juga dapat menggunakan perintah ekstensi !wdflogsave untuk menyimpan rekaman pencatat peristiwa dalam file log jejak peristiwa (.etl) yang dapat Anda lihat dengan menggunakan TraceView.

Anda terkadang dapat menggunakan ekstensi debugger !wdfcrashdump pada crash dump untuk menampilkan informasi log setelah pemeriksaan bug sistem. Informasi log tersedia di crash dump hanya jika kerangka kerja dapat menentukan bahwa driver Anda menyebabkan pemeriksaan bug atau jika Anda telah mengatur nilai registri ForceLogsInMiniDump untuk driver.

Jika debugger dilampirkan ketika pemeriksaan bug terjadi, Anda dapat menggunakan !wdfcrashdump untuk melihat informasi log segera, atau Anda dapat melihat informasi dengan memuat file cadangan memori. Karena keterbatasan ukuran file cadangan memori kecil, log untuk driver yang menyebabkan crash mungkin tidak muncul di cadangan.

Kerangka kerja dapat menentukan apakah driver tertentu menyebabkan kode pemeriksaan bug berikut:

Mulai dari UMDF versi 2, UMDF menyimpan log jejak UMDF (atau UMDF IFR) dalam memori non-halaman kernel. Kerangka kerja mengalokasikan satu instans IFR per host driver (Wudfhost).

Untuk informasi selengkapnya tentang perintah ekstensi debugger, lihat Ekstensi Debugger untuk Driver berbasis Kerangka Kerja.