Inflight Trace Recorder (IFR) untuk jejak pengelogan

Artikel
03/08/2023

Inflight Trace Recorder (IFR) adalah fitur pelacakan yang memungkinkan penyedia pelacakan, seperti driver mode kernel atau driver UMDF, untuk membuat serangkaian buffer melingkar dalam memori tempat pesan log terbaru dipertahankan. Pesan log dapat dilihat menggunakan debugger.

IFR dibangun di atas pelacakan perangkat lunak WPP. Manfaat utama IFR melalui WPP adalah diaktifkan secara otomatis dan Anda tidak perlu memulai sesi pelacakan terlebih dahulu.

Berlaku untuk:

OS minimum: Windows 8 untuk pengembang driver KMDF dan WDM
OS minimum: Windows 10 untuk pengembang driver UMDF (2.15)

Cara mengaktifkan Inflight Trace Recorder di Visual Studio

Pertama, ikuti langkah-langkah dalam Menambahkan Pelacakan Perangkat Lunak WPP ke Driver Windows.

Berikutnya, di halaman properti Proyek, di bawah Properti Konfigurasi-WPP> Tracing-Function> dan Opsi Makro-Aktifkan> Perekam Jejak Dalam Penerbangan, pilih Ya.

Terakhir, hanya untuk UMDF, ada satu langkah tambahan: di bawah Definisi Fungsi Pelacakan-Fungsi> WPP dan Opsi Makro-Praprosesor>, tambahkan WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Cara mengaktifkan Inflight Trace Recorder dari baris perintah

Jika Anda mengedit file .vcxproj secara manual, atur entri berikut:

Untuk driver KMDF atau WDM:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppKernelMode>true</WppKernelMode>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        ...
    </ClCompile>

Untuk driver UMDF:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        <WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
        ...
    </ClCompile>

Cara mengonfigurasi parameter Inflight Trace Recorder

Anda dapat mengonfigurasi IFR dengan mengatur entri registri opsional berikut di bawah kunci Parameter driver.

Gunakan entri registri berikut:

LogPages: REG_DWORD

Atur ke jumlah halaman untuk menyimpan log default. Defaultnya adalah satu.

VerboseOn: REG_DWORD

Pengaturan default nol menyebabkan IFR mencatat kesalahan, peringatan, dan peristiwa informasi. Atur ke satu untuk menambahkan output verbose ke log.

WppRecorder_UseTimeStamp: REG_DWORD (tersedia mulai dari WDK build 22557)

Driver mengatur entri ini ke satu untuk menambahkan tanda waktu ke entri log yang kemudian dapat dilihat menggunakan !rcdrkd.rcdrlogdump atau !wdfkd.wdflogdump.

WppRecorder_PreciseTimeStamp: REG_DWORD (tersedia mulai dari WDK build 22557)

Jika Anda ingin tanda waktu yang lebih tepat, selain WppRecorder_UseTimeStamp, tambahkan WppRecorder_PreciseTimeStamp menggunakan sintaks yang sama yang ditunjukkan di atas.

Contoh

Dalam contoh berikut, tambahkan baris antara komentar awal dan akhir untuk mengatur jumlah halaman log menjadi dua dan aktifkan tanda waktu.

Untuk driver mode kernel:

[IfrSample_Service_Inst] 
DisplayName    = %IfrSample.SvcDesc%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary  = %12%\IfrSample.sys
; =============== START
AddReg = IfrSample_Service_Inst.AddReg
 
[IfrSample_Service_Inst.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

[Strings]
REG_DWORD = 0x00010001

Untuk driver UMDF:

[IfrSampleUm_Install] 
UmdfLibraryVersion=$UMDFVERSION$
ServiceBinary=%13%\IfrSampleUm.dll
; =============== START
AddReg=IfrSampleUm_Install.AddReg
 
[IfrSampleUm_Install.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

Cara mengirim pesan pelacakan ke log default

Ikuti instruksi dalam Menambahkan Pelacakan Perangkat Lunak WPP ke Driver Windows. Contohnya:

Di DriverEntry, panggil WPP_INIT_TRACING(DriverObject, RegistryPath).
Di EvtDriverUnload, panggil WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

Sekarang driver bebas untuk memanggil fungsi pelacakan sesuai kebutuhan. Misalnya: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

Untuk informasi selengkapnya, lihat WPP_INIT_TRACING dan WPP_CLEANUP.

Cara mengirim pesan pelacakan ke log kustom

Ini hanya berlaku untuk driver mode kernel (KMDF atau WDM).

Untuk sebagian besar driver, log default tunggal cukup baik. Namun, dalam beberapa skenario, sangat membantu untuk memiliki buffer log terpisah untuk entitas yang berbeda.

Misalnya, saat menulis driver bus, Anda mungkin ingin setiap perangkat anak memiliki buffer sendiri. Kemudian Anda dapat menggunakan debugger untuk mencadangkan hanya log untuk perangkat anak tertentu.

Untuk menyiapkan log kustom, driver harus menyertakan <WppRecorder.h>. Kemudian panggil API berikut:

WppRecorderLogCreate untuk membuat lebih dari satu buffer log
WppRecorderLogDelete sebelum memanggil WPP_CLEANUP.
WppRecorderLogSetIdentifier untuk mengatur pengidentifikasi string untuk log perekam tertentu (opsional)
WppRecorderConfigure untuk menonaktifkan log default (opsional)

Driver juga perlu menentukan makro jejak baru yang mengambil handel log sebagai parameter pertama. Misalnya, lihat Driver Sampel Pemangsa.

Cara menambahkan informasi tanda waktu ke log kustom

Jika driver Anda memanggil WppRecorderLogCreate untuk membuat handel log tambahan, dimungkinkan untuk mengaktifkan tanda waktu untuk beberapa handel log tetapi tidak yang lain.

Untuk melakukan ini, Anda perlu menambahkan satu baris ke kode driver untuk setiap handel log yang harus menggunakan tanda waktu. Untuk contoh kode, lihat WppRecorderLogCreate.

Catatan

Fungsionalitas ini tersedia mulai dari WDK build 22557. Untuk informasi tentang menargetkan rilis tertentu, lihat Membangun Driver untuk Versi Windows yang Berbeda.

Cara melihat pesan pelacakan di debugger

Untuk driver KMDF dan UMDF, gunakan !wdfkd.wdflogdump seperti biasa. Ini akan mencetak log IFR kerangka kerja dan log IFR driver.

Untuk driver WDM, gunakan !rcdrkd.rcdrloglist dan !rcdrkd.rcdrlogdump.

Bagikan melalui