Bagikan melalui

Inflight Trace Recorder (IFR) untuk pencatatan jejak

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.

Selanjutnya, di halaman properti Proyek, di bawah Configuration Properties->WPP Tracing->Function and Macro Options->Enable Inflight Trace Recorder, pilih Ya.

Terakhir, hanya untuk UMDF, ada satu langkah tambahan: di bawah Definisi WPP Tracing-Function> dan Macro Options-Preprocessor>, 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. Setel ke nilai satu untuk menambahkan keluaran rinci ke dalam log.

WppRecorder_UseTimeStamp: REG_DWORD (tersedia mulai WDK build 22557)

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

WppRecorder_PreciseTimeStamp: REG_DWORD (tersedia mulai 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 mengaktifkan 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 standar tunggal sudah memadai. 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:

Driver juga perlu menentukan makro lacak baru yang mengambil handle log sebagai parameter pertama. Misalnya, lihat Pengontrol Sampel Toaster.

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.

Nota

Fungsionalitas ini tersedia mulai 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.

  • Last updated on