Bagikan melalui

Menambahkan pelacakan perangkat lunak WPP ke driver Windows

Untuk menggunakan pelacakan perangkat lunak WPP di penyedia pelacakan, seperti driver mode kernel atau aplikasi mode pengguna, Anda perlu menambahkan kode (atau instrumen) file sumber driver dan memodifikasi proyek driver. Bagian ini akan menjelaskan langkah-langkah tersebut.

Nota

Cara term mudah untuk menambahkan pelacakan WPP ke driver Anda adalah dengan menggunakan salah satu templat driver KMDF atau UMDF di Visual Studio. Jika Anda menggunakan templat, banyak kode yang perlu Anda tambahkan sudah disiapkan untuk Anda. Di Visual Studio, pilih File > Proyek > Baru, lalu pilih proyek WDF Driver Windows (mode pengguna atau mode kernel). Makro WPP didefinisikan dalam file header Trace.h yang disertakan sebagai bagian dari proyek. Jika Anda menggunakan salah satu templat, Anda dapat langsung ke Langkah 5.

Langkah 1: Tentukan GUID kontrol dan bendera pelacakan

Setiap penyedia pelacakan (seperti driver, atau aplikasi mode pengguna) harus ditentukan secara unik. Anda melakukan ini dengan menambahkan makro WPP_CONTROL_GUIDS yang menentukan GUID kontrol, pengidentifikasi, dan bendera pelacakan. Ini dilakukan agar Anda dapat mengidentifikasi dan mengontrol kapan dan apa yang ingin Anda lacak. Meskipun setiap driver biasanya memiliki GUID kontrol terpisah, driver dapat memiliki beberapa GUID kontrol, atau beberapa driver dapat berbagi satu GUID kontrol.

Untuk kenyamanan, makro WPP_CONTROL_GUIDS biasanya didefinisikan dalam file header umum. File header harus disertakan (#include) dalam file sumber apapun yang ingin Anda instrumentasi untuk pelacakan.

Untuk menambahkan makro WPP_CONTROL_GUIDS ke driver Anda:

  1. Tambahkan file header C++ baru ke proyek Visual Studio yang dapat Anda gunakan untuk menentukan makro pelacakan WPP. Misalnya, pilih dan tahan (atau klik kanan) driver di Penjelajah Solusi, dan pilih Tambahkan > Item Baru. Simpan file (sebagai Trace.h, misalnya).

  2. Tambahkan makro WPP_CONTROL_GUIDS untuk menentukan nama yang mudah diingat untuk penyedia pelacakan, tentukan GUID kontrol, dan untuk menentukan bendera pelacakan yang dapat Anda gunakan untuk memenuhi syarat pesan pelacakan tertentu.

    Makro WPP_CONTROL_GUIDS memiliki sintaks berikut:

    Sintaks untuk WPP_CONTROL_GUIDS

    #define WPP_CONTROL_GUIDS \
    WPP_DEFINE_CONTROL_GUID(GUIDFriendlyName, (ControlGUID),  \
        WPP_DEFINE_BIT(NameOfTraceFlag1)  \
        WPP_DEFINE_BIT(NameOfTraceFlag2)  \
        .............................   \
        .............................   \
        WPP_DEFINE_BIT(NameOfTraceFlag31) \
        )

    Misalnya, kode di bawah ini menggunakan myDriverTraceGuid sebagai GUIDFriendlyName. Perhatikan bahwa ControlGUID memiliki format yang sedikit berbeda dari bentuk standar GUID heksadesimal 32 digit. ControlGUID memiliki lima kolom, tetapi dipisahkan oleh koma dan dikurung oleh tanda kurung, alih-alih tanda hubung dan kurung kurawal biasa. Misalnya, Anda menentukan ((84bdb2e9,829e,41b3,b891,02f454bc2bd7) bukan {84bdb2e9-829e-41b3-b891-02f454bc2bd7}.

    Contoh pernyataan WPP_CONTROL_GUIDS

    #define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(                                           \
        myDriverTraceGuid, (84bdb2e9,829e,41b3,b891,02f454bc2bd7), \
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        )

    Nota

    Anda dapat menyalin cuplikan kode ini ke dalam file header. Pastikan untuk mengubah GUID kontrol dan nama yang mudah dibaca. Anda dapat menggunakan GUIDgen.exe untuk menghasilkan GUID kontrol. Guidgen.exe disertakan dengan Visual Studio (Alat> BuatGUID ). Anda juga dapat menggunakan alat Uuidgen.exe, yang tersedia dari jendela prompt Perintah Visual Studio (ketik uuidgen.exe /? untuk informasi selengkapnya).

  3. Tentukan Bendera Jejak untuk penyedia pelacakan Anda.

    Elemen WPP_DEFINE_BIT makro WPP_CONTROL_GUIDS menentukan bendera pelacakan untuk penyedia pelacakan. Biasanya, bendera mewakili tingkat pelaporan yang semakin terperinci, tetapi Anda dapat menggunakan bendera seperti apa pun yang Anda suka sebagai kondisi untuk menghasilkan pesan pelacakan. Dalam contoh WPP_CONTROL_GUIDS, WPP_DEFINE_BIT menentukan empat bendera jejak (MYDRIVER_ALL_INFO, TRACE_DRIVER, TRACE_DEVICE, dan TRACE_QUEUE).

    Anda dapat menentukan hingga 31 bendera pelacakan. WPP menetapkan nilai bit ke elemen dalam urutan muncul, misalnya, bit 0 (0x1), bit 1 (0x2), bit 2 (0x4), bit 3 (0x8) dan sebagainya. Anda menggunakan bendera pelacakan saat menambahkan fungsi pesan pelacakan ke kode sumber Anda (dijelaskan dalam Langkah 5: Instrumen kode driver untuk menghasilkan pesan pelacakan pada titik yang sesuai).

    Nota

    Menggunakan bendera pelacakan, Anda dapat mengontrol kapan harus melacak komponen tertentu (misalnya, permintaan I/O tertentu, atau aktivitas objek perangkat atau driver). Anda menambahkan bendera pelacakan ke pernyataan pesan pelacakan Anda (misalnya, DoTraceMessage (TRACE_DRIVER, "Hello World!\n"). Saat Anda membuat sesi pelacakan dengan pengontrol pelacakan, seperti Tracelog, Anda menentukan opsi -flag untuk digunakan bagi penyedia pelacakan dalam sesi tersebut, dalam hal ini, benderanya adalah bit 1 (0x1), yang sesuai dengan bendera TRACE_DRIVER. Saat Anda memulai sesi pelacakan, semua pesan jejak pelacakan yang menentukan bendera pelacakan tersebut dicatatkan ke log.

Langkah 2: Pilih fungsi pesan pelacakan mana yang ingin Anda gunakan dan tentukan makro WPP untuk fungsi tersebut

Seperti fungsi print debug, fungsi pesan pelacakan adalah fungsi (atau makro) yang Anda tambahkan ke dalam kode Anda untuk menulis pesan pelacakan.

Memilih fungsi pesan pelacakan

  • Fungsi pesan jejak default adalah makro DoTraceMessage. Jika Anda menggunakan fungsi default, Anda dapat mengontrol kapan untuk membuat pesan dengan menggunakan nilai Bendera Jejak untuk penyedia Anda. Nilai Bendera Pelacakan adalah bendera yang Anda tentukan saat membuat GUID kontrol di Langkah 1. Jika Anda menggunakan DoTraceMessage, makro WPP default sudah ditentukan untuk Anda (WPP_LEVEL_ENABLED dan WPP_LEVEL_LOGGER), sehingga Anda dapat melewati sisa langkah ini dan masuk ke Langkah 5.

  • Jika Anda menggunakan salah satu templat KMDF atau UMDF, fungsi TraceEvents dan makro WPP yang diperlukan sudah ditentukan untuk mengaktifkan fungsi tersebut, sehingga Anda dapat melompat ke Langkah 5.

  • Jika Anda membuat fungsi pesan jejak Anda sendiri, atau mengonversi fungsi cetak debug yang ada, lanjutkan dengan langkah lainnya.

Membuat atau menyesuaikan fungsi pesan pelacakan

  1. Jika Anda menggunakan fungsi pesan pelacakan kustom, atau ingin mengonversi fungsi cetak debug (misalnya, KdPrint) untuk menghasilkan pesan pelacakan, Anda perlu menentukan makro WPP yang mengidentifikasi dan mengaktifkan fungsi pesan pelacakan di penyedia pelacakan Anda. Letakkan makro ini di file header Trace.h yang Anda tambahkan ke proyek Anda.

  2. Tentukan makro WPP untuk mengaktifkan fungsi pelacakan.

    Setiap fungsi pesan pelacakan yang Anda gunakan harus memiliki sepasang makro yang sesuai. Makro ini mengidentifikasi penyedia pelacakan dan menentukan kondisi yang menghasilkan pesan. Anda biasanya menentukan sepasang makro, WPP_<kondisi>_LOGGER dan WPP_<kondisi>_ENABLED dalam istilah makro WPP_LEVEL_ENABLED dan WPP_LEVEL_LOGGER default.

Istilah Deskripsi
WPP_KONDISI_LOGGER Digunakan untuk menemukan sesi pelacakan yang terkait dengan penyedia dan mengembalikan handel ke sesi.
WPP_KONDISI_ENABLED Digunakan untuk menentukan apakah pengelogan diaktifkan dengan kondisi yang ditentukan.

Untuk makro WPP yang Anda tentukan, CONDITIONS mewakili kondisi yang didukung oleh fungsi pesan lacak, sesuai dengan urutan kemunculannya dalam daftar parameter fungsi, dipisahkan oleh underscore. Misalnya, fungsi pesan pelacakan bawaan, DoTraceMessage, hanya mendukung Bendera Penjejak sebagai kondisi, jadi hanya ada satu parameter dalam nama makro (WPP_LEVEL_ENABLED).

Nota

Sayangnya, nama makro default (WPP_LEVEL_ENABLED dan WPP_LEVEL_LOGGER) tampaknya menunjukkan parameter Tingkat Jejak , tetapi mereka benar-benar merujuk ke Bendera Pelacakan.

Jika Anda menggunakan fungsi pesan jejak kustom, Anda dapat menetapkan pengaturan tambahan, seperti Tingkat Pelacakan . Tingkat Pelacakan didefinisikan dalam file Evntrace.h, dan tingkat jejak menyediakan cara yang nyaman untuk mengklasifikasikan pesan jejak sebagai pesan kesalahan, peringatan, dan informasi.

Misalnya, Anda dapat menambahkan cuplikan kode berikut ke file header yang Anda tambahkan ke proyek Anda. Kode berikut mendefinisikan makro WPP kustom untuk fungsi pesan pelacakan yang mendukung parameter Tingkat Pelacakan dan Lacak Bendera sebagai kondisi untuk menghasilkan pesan pelacakan. Makro WPP_LEVEL_FLAGS_ENABLED mengembalikan TRUE jika pencatatan diaktifkan untuk nilai FLAGS yang ditentukan dan nilai LEVEL yang diaktifkan lebih besar dari atau sama dengan argumen level yang digunakan dalam fungsi pemanggilan pesan jejak.

#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \
           WPP_LEVEL_LOGGER(flags)

#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \
           (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl)

Selanjutnya, Anda perlu menentukan fungsi pelacakan kustom di blok konfigurasi WPP (begin_wpp konfigurasi dan end_wpp) Misalnya, jika Anda menggunakan templat untuk proyek Driver UMDF atau KMDF di Visual Studio, templat menentukan makro WPP untuk fungsi pesan pelacakan kustom yang disebut TraceEvents. Fungsi makro TraceEvents menggunakan Tingkat Jejak dan Bendera Pelacakan sebagai kondisi untuk menghasilkan pesan. Jika Anda telah menentukan makro WPP_LEVEL_FLAGS_ENABLED di file header Trace.h, Anda dapat menambahkan definisi makro berikut.

//
// This comment block is scanned by the trace preprocessor to define the 
// TraceEvents function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// end_wpp
//

Anda juga dapat mengonversi pernyataan cetak debug yang ada menjadi pernyataan pesan dengan menambahkan deklarasi serupa FUNC di blok konfigurasi WPP. Misalnya, contoh berikut menambahkan kode untuk mengonversi pernyataanKdPrintyang ada. Deklarasi FUNC juga secara global mendefinisikan KdPrint untuk menggunakan level jejak dan bendera yang ditentukan {LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}. Alih-alih mengirim output ke debugger, pernyataan cetak debug dikirim ke log jejak.

//
// This comment block is scanned by the trace preprocessor to define the
// TraceEvents function and conversion for KdPrint. Note the double parentheses for the KdPrint message, for compatibility with the KdPrint function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// FUNC KdPrint{LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}((MSG, ...));
// end_wpp
//

Nota

Jika Anda ingin mengonversi KdPrintEx ke fungsi pesan pelacakan, Anda perlu mengambil beberapa langkah tambahan. Dibandingkan dengan KdPrint, fungsi KdPrintEx mengambil dua argumen tambahan. Untuk mengonversi fungsi KdPrintEx, Anda perlu menentukan WPP_DEFINE_BIT untuk ComponentID, dan mendefinisikan makro kustom kondisi WPP_<>_LOGGER dan WPP_<>_ENABLED. Parameter kedua untuk KdPrintEx mengatur tingkat yang mirip dengan nilai Trace Level, sehingga Anda tidak perlu menentukan ulang nilai tersebut.


#define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(\
    myDriverTraceGuid, (11C3AAE4, 0D88, 41b3, 43BD, AC38BF747E19), \    /* change GUID for your provider */
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)        /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(TRACE_DRIVER)             /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(TRACE_DEVICE)             /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(TRACE_QUEUE)              /* bit  3 = 0x00000008 */ \
        WPP_DEFINE_BIT(DPFLTR_IHVDRIVER_ID)      /* bit  4 = 0x00000010 */\         /* Added for the ComponentID param of KdPrintEx */
    )

#define WPP_Flags_LEVEL_LOGGER(Flags, level)                                  \
    WPP_LEVEL_LOGGER(Flags)

#define WPP_Flags_LEVEL_ENABLED(Flags, level)                                 \
    (WPP_LEVEL_ENABLED(Flags) && \
    WPP_CONTROL(WPP_BIT_ ## Flags).Level >= level)



//
// This comment block is scanned by the trace preprocessor to convert the KdPrintEx function.
// Note the double parentheses for the KdPrint message, for compatiblility with the KdPrintEx function.
//
// begin_wpp config
// FUNC KdPrintEx((Flags, LEVEL, MSG, ...));   
// end_wpp
//

Langkah 3: Sertakan file header jejak terkait (.h dan .tmh) dalam file sumber C atau C++ Anda

Jika Anda menentukan GUID kontrol dan bendera pelacakan untuk driver Anda dalam file header (misalnya, trace.h), Anda perlu menyertakan file header dalam file sumber tempat Anda akan menginisialisasi dan membongkar WPP (Langkah 4) atau memanggil fungsi pesan pelacakan.

Selain itu, Anda perlu menambahkan perintah #include untuk File Header Pesan Lacak (.tmh). Saat Anda membangun driver atau aplikasi, preprocessor WPP menghasilkan file header pesan jejak (.tmh) untuk setiap file sumber yang berisi fungsi pesan pelacakan.

/* -- driver.c  - include the *.tmh file that is generated by WPP --*/

#include "trace.h"     /* file that defines WPP_CONFIG_GUIDS and trace flags */
#include "driver.tmh"  /* this file is auto-generated */

Langkah 4: Tambahkan makro ke fungsi panggilan balik yang sesuai untuk menginisialisasi dan membersihkan WPP

Untuk menginisialisasi WPP pada entri driver

  • Tambahkan makro WPP_INIT_TRACING ke DriverEntry rutin driver mode kernel atau driver UMDF 2.0, atau ke DLLMain rutin driver mode pengguna (UMDF 1.x) atau aplikasi.

Untuk membersihkan sumber daya WPP saat keluar dari driver

  • Tambahkan makro WPP_CLEANUP ke rutinitas pencopotan driver (misalnya, DriverContextCleanup atau DriverUnload) driver mode kernel atau driver UMDF 2.0.

    Untuk driver mode pengguna (UMDF 1.x) atau aplikasi, tambahkan makro WPP_CLEANUP ke DLLMain rutin.

    Anda juga harus menambahkan makro WPP_CLEANUP ke rutinitas DriverEntry jika DriverEntry gagal. Misalnya, jika DriverEntry gagal, rutinitas pembongkaran driver tidak akan dipanggil. Lihat panggilan ke WdfDriverCreate dalam contoh berikut.

Contoh driver mode kernel menggunakan WPP_INIT_TRACING dan WPP_CLEANUP di DriverEntry


NTSTATUS
DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
    )
{  

          //  ... 

                //
    // Initialize WPP Tracing in DriverEntry
    //
    WPP_INIT_TRACING( DriverObject, RegistryPath );

                //  ...


 //
    // Create a framework driver object to represent our driver.
    //
    status = WdfDriverCreate(
        DriverObject,
        RegistryPath,
        &attributes, // Driver Object Attributes
        &config,          // Driver Config Info
        WDF_NO_HANDLE // hDriver
        );

    if (!NT_SUCCESS(status)) {

        TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT,
                "WdfDriverCreate failed with status 0x%x\n", status);
        //
        // Cleanup tracing here because DriverContextCleanup will not be called
        // as we have failed to create WDFDRIVER object itself.
        // Please note that if you return failure from DriverEntry after the
        // WDFDRIVER object is created successfully, you don't have to
        // call WPP cleanup because in those cases DriverContextCleanup
        // will be executed when the framework deletes the DriverObject.
        //
        WPP_CLEANUP(DriverObject);

    }

                return status;

}

Contoh driver mode kernel menggunakan WPP_CLEANUP di DriverContextCleanup



VOID
DriverContextCleanup(
       PDRIVER_OBJECT DriverObject
       )
{
    // ...

    // Clean up WPP resources on unload
    //
    WPP_CLEANUP(DriverObject);

   // ...

}

Contoh untuk driver UMDF 2.0 menggunakan WPP_INIT_TRACING di DriverEntry


/
// Driver specific #defines in trace header file (trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF2.0\\UMDF2_0Driver1 V1.0"


 // Initialize WPP Tracing in the DriverEntry routine
 //
    WPP_INIT_TRACING( MYDRIVER_TRACING_ID );

Contoh untuk penggunaan driver UMDF 1.0 dari makro WPP_INIT_TRACING dan WPP_CLEANUP di DLLMain

/
// Driver specific #defines in trace header file (for example, trace.h)
//
#define MYDRIVER_TRACING_ID      L"Microsoft\\UMDF1.X\\UMDF1_XDriver1"


//
// DLL Entry Point - UMDF 1.0 example in the source file where you implement the DLL exports.
// 

extern "C"
BOOL
WINAPI
DllMain(
    HINSTANCE hInstance,
    DWORD dwReason,
    LPVOID lpReserved
    )
{
    if (dwReason == DLL_PROCESS_ATTACH) {
        WPP_INIT_TRACING(MYDRIVER_TRACING_ID);              // Initialize WPP tracing

        g_hInstance = hInstance;
        DisableThreadLibraryCalls(hInstance);

    } else if (dwReason == DLL_PROCESS_DETACH) {
        WPP_CLEANUP();                                                                                                              // Deactivate and cleanup WPP tracing
    }

    return _AtlModule.DllMain(dwReason, lpReserved);
}

Langkah 5: Instrumen kode driver untuk menghasilkan pesan pelacakan pada titik yang sesuai

Anda dapat menggunakan fungsi pesan pelacakan apa pun yang Anda pilih, asalkan fungsi pesan pelacakan, bendera pelacakan, dan tingkat didefinisikan dengan tepat. Fungsi pesan jejak default adalah makro DoTraceMessage. Anda dapat menambahkan makro ini ke kode Anda untuk menulis pesan ke file log. Tabel berikut ini mencantumkan beberapa fungsi pesan jejak yang telah ditentukan sebelumnya dan fungsi cetak debug yang dapat Anda gunakan untuk membuat pesan pelacakan.

Contoh fungsi pesan pelacakan Kapan harus menggunakan
DoTraceMessage Ini adalah fungsi pesan pelacakan default. Keuntungan menggunakan DoTraceMessage adalah bahwa fungsi sudah ditentukan untuk Anda. Anda dapat menggunakan bendera pelacakan yang Anda tentukan di makro WPP_CONFIG_GUIDS. Kerugian dari penggunaan DoTraceMessage, adalah bahwa fungsi hanya mengambil satu parameter kondisional, yaitu, bendera pelacakan. Jika Anda ingin menggunakan level pelacakan, untuk mencatat hanya pesan kesalahan atau peringatan, Anda dapat menggunakan makro DoDebugTrace, atau menggunakan TraceEvents, yang menggunakan kedua flag pelacakan dan level pelacakan.
TraceEvents Jika Anda membuat driver menggunakan templat WDF di Visual Studio, ini adalah fungsi pesan pelacakan default. Keuntungan menggunakan TraceEvents adalah fungsi pesan jejak, bendera pelacakan, dan Trace Level sudah ditentukan untuk Anda. Selain itu, templat juga menyertakan instrumentasi yang menulis pesan ke file log saat fungsi dimasukkan dan dikeluarkan.
KdPrint, KdPrintEx, DbgPrint, DbgPrintEx Keuntungan menggunakan fungsi cetak debug adalah Anda tidak perlu mengubah pernyataan cetak debug yang ada. Anda dapat dengan mudah beralih dari menampilkan pesan di debugger, ke merekam pesan pelacakan dalam file. Jika Anda mengkustomisasi fungsi pesan jejak untuk menyertakan salah satu fungsi cetak debug, Anda tidak perlu melakukan langkah tambahan. Saat Anda membuat sesi pelacakan dengan Logman atau Tracelog, atau pengontrol pelacakan lain, Anda cukup menentukan tanda dan level untuk penyedia Anda. Setiap pernyataan cetak debug yang memenuhi kondisi yang Anda tentukan dicetak ke log.

Menggunakan pernyataan DoTraceMessage

  1. Tambahkan makro DoTraceMessage ke kode Anda seperti Anda akan men-debug rutinitas cetak. Makro DoTraceMessage mengambil 3 parameter: tingkat bendera (TraceFlagName), yang menentukan kondisi saat pesan jejak ditulis, string Pesan, dan daftar variabel opsional.

    DoTraceMessage(TraceFlagName, Message, [VariableList... ])

    Misalnya, pernyataan DoTraceMessage berikut menulis nama fungsi yang berisi pernyataan DoTraceMessage saat bendera TRACE_DRIVER, seperti yang didefinisikan dalam WPP_CONTROL_GUIDS, diaktifkan untuk sesi pelacakan.

         DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

    Contoh menggunakan string yang telah ditentukan sebelumnya untuk fungsi yang sedang dijalankan (%FUNC!). Untuk informasi selengkapnya tentang string spesifikasi format yang ditentukan WPP, lihat Apa itu string spesifikasi format yang diperluas WPP?

  2. Untuk menghasilkan pesan jejak, buat sesi pelacakan untuk penyedia pelacakan Anda, menggunakan Logman atau Tracelog, dan tentukan bendera pelacakan yang mengatur bendera TRACE_DRIVER (bit 1, 0x2).

//
//  DoTraceMessage examples
// 

     ...

// writes the name of the function that contains the trace statement when the flag, TRACE_DRIVER (bit 1, 0x2), 
// as defined in WPP_CONTROL_GUIDS, is enabled for the trace session.

     DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

     ...

// writes the name of the function, the line number, and the error code 

      DoTraceMessage(
            TRACE_DRIVER,
            "[%s] Failed at %d (error code= %d)\n",
            __FUNCTION__,
            __LINE__,
            dwLastError);

Menggunakan instruksi TraceEvents

Jika Anda menggunakan templat driver Windows di Visual Studio, makro TraceEvents ditentukan untuk Anda dalam file header Trace.h.

  1. Tambahkan TraceEvents makro ke kode Anda seperti Anda akan men-debug rutinitas cetak. Makro TraceEvents mengambil parameter berikut: tingkat jejak (Level) dan flag pelacakan (Flags), yang menentukan kondisi saat pesan jejak ditulis, string pesan ( Message ), dan daftar variabel opsional.

    TraceEvents(Level, Flags, Message, [VariableList... ])

    Misalnya, pernyataan TraceEvents berikut menuliskan nama fungsi yang mengandung pernyataan TraceEvents ketika kondisi yang ditentukan dalam parameter Level Jejak dan Tanda Jejak terpenuhi. Tingkat Pelacakan adalah nilai bilangan bulat; apa pun di atau di bawah Tingkat Pelacakan yang ditentukan untuk sesi jejak tersebut akan dilacak. TRACE_LEVEL_INFORMATION didefinisikan dalam Evntrace.h dan memiliki nilai 4. Bendera TRACE_DRIVER (bit 1, 0x2) didefinisikan dalam WPP_CONTROL_GUIDS. Jika bit TRACE_DRIVER ini diaktifkan untuk sesi pelacakan dan Tingkat Pelacakan adalah 4 atau lebih tinggi, TraceEvents menulis pesan pelacakan.

            TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

    Contoh menggunakan string yang telah ditentukan sebelumnya untuk fungsi yang sedang dijalankan (%FUNC!). Untuk informasi selengkapnya tentang string spesifikasi format yang ditentukan WPP, lihat Apa itu string spesifikasi format yang diperluas WPP?

  2. Untuk menghasilkan pesan pelacakan, buat sesi pelacakan untuk penyedia pelacakan Anda, menggunakan Logman atau Tracelog. Tentukan tingkat jejak ke TRACE_LEVEL_INFORMATION (4) atau lebih tinggi, dan tentukan tingkat jejak yang mengatur bit TRACE_DRIVER (bit 1, 0x2).

//
//  TraceEvents examples
// 


    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

//


    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                       "OSRUSBFX2 Driver Sample - Driver Framework Edition.\n");

    TraceEvents(TRACE_LEVEL_INFORMATION, DBG_INIT,
                "Built %s %s\n", __DATE__, __TIME__);

Langkah 6: Ubah proyek Visual Studio untuk menjalankan prapemrosan WPP dan membangun solusi

WDK menyediakan dukungan untuk Praprosesor WPP, sehingga Anda dapat menjalankan praprosesor menggunakan Visual Studio dan lingkungan MSBuild.

Untuk menjalankan prapemroses WPP

  1. Pilih dan tahan (atau klik kanan) proyek driver di Penjelajah Solusi dan pilih Properti .
  2. Di halaman properti proyek, pilih Properti Konfigurasi dan pilih Pelacakan WPP.
  3. Di bawah Umum, atur opsi Jalankan WPP ke Ya.
  4. Di bawah Baris Perintah, tambahkan opsi tambahan apa pun untuk menyesuaikan perilaku pelacakan. Untuk informasi tentang apa yang dapat Anda tambahkan, lihat Praprosesor WPP.
  5. Bangun proyek atau solusi untuk konfigurasi dan platform target Anda. Lihat Membangun Driver menggunakan WDK.

Untuk informasi tentang proses build, lihat tugas TraceWPP dan lingkungan build WDK dan Visual Studio .

Anda juga dapat menjalankan pra-prosesor yang terpisah dari lingkungan build dengan menggunakan alat TraceWPP (TraceWPP.exe). Alat ini terletak di subdirektori bin/x86 dan bin/x64 WDK.

Langkah 7: Mulai sesi pelacakan untuk mengambil dan memverifikasi pesan pelacakan Anda

Untuk memverifikasi bahwa Anda telah menyiapkan pelacakan WPP dengan benar, Anda harus menginstal driver atau aplikasi Anda di komputer pengujian lalu membuat sesi pelacakan untuk mengambil pesan jejak. Anda dapat membuat sesi pelacakan untuk penyedia pelacakan Anda, menggunakan pengontrol pelacakan apa pun, seperti Logman, Tracelog, atau TraceView. Anda dapat menulis pesan ke file log atau dikirim ke debugger kernel. Bergantung pada fungsi pesan pelacakan yang Anda gunakan, Anda harus memastikan untuk menentukan bendera pelacakan dan tingkat pelacakan yang akan menghasilkan pesan.

Misalnya, jika Anda menggunakan tingkat pelacakan yang ditentukan dalam Evntrace.h, dan Anda ingin menangkap TRACE_LEVEL_INFORMATION (4) atau lebih besar, Anda perlu mengatur tingkat ke 4. Ketika Anda mengatur tingkat ke 4 untuk sesi pelacakan, semua pesan informasi (4), peringatan (3), kesalahan (2), dan kritis (1) juga akan ditangkap, dengan asumsi kondisi lain, seperti bendera pelacakan, juga terpenuhi.

Untuk memverifikasi bahwa semua pesan Anda dihasilkan, Anda mungkin perlu mengatur tingkat pelacakan dan bendera pelacakan ke nilai maksimum agar semua pesan dapat dihasilkan. Flag pelacakan menggunakan masker bit (ULONG), sehingga Anda bisa mengatur semua bit (misalnya, 0xFFFFFFFF). Tingkat jejak diwakili oleh nilai byte. Misalnya, jika Anda menggunakan Logman, Anda dapat menentukan, 0xFF untuk mencakup semua tingkatan.

(Contoh) Memulai sesi pelacakan menggunakan Logman

logman create trace "myWPP_session" -p {11C3AAE4-0D88-41b3-43BD-AC38BF747E19} 0xffffffff 0xff -o c:\DriverTest\TraceFile.etl 

logman start "myWPP_session"

logman stop "myWPP_session"

(Contoh) Memulai sesi pelacakan menggunakan TraceLog

tracelog -start MyTrace -guid  MyProvider.guid -f d:\traces\testtrace.etl -flag 2 -level 0xFFFF

Perintah Tracelog menyertakan parameter -f untuk menentukan nama dan lokasi file log jejak peristiwa. Ini termasuk parameter -flag untuk menentukan pengaturan flag dan parameter -level untuk menentukan pengaturan tingkat. Anda dapat menghilangkan parameter ini, tetapi beberapa penyedia pelacakan tidak menghasilkan pesan jejak apa pun kecuali Anda mengatur bendera atau tingkat. Tingkat Pelacakan didefinisikan dalam file Evntrace.h, dan tingkat jejak menyediakan cara yang nyaman untuk mengklasifikasikan pesan jejak sebagai pesan kritis, kesalahan, peringatan, dan informasi.

  • Last updated on