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.
Tips 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 dilakukan 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 melompat ke Langkah 5.
- Langkah 1: Tentukan GUID kontrol dan bendera pelacakan
- Langkah 2: Pilih fungsi pesan pelacakan mana yang ingin Anda gunakan dan tentukan makro WPP untuk fungsi tersebut
- Langkah 3: Sertakan file header jejak terkait (.h dan .tmh) dalam file sumber C atau C++ Anda
- Langkah 4: Tambahkan makro ke fungsi panggilan balik yang sesuai untuk menginisialisasi dan membersihkan WPP
- Langkah 5: Instrumen kode driver untuk menghasilkan pesan pelacakan pada titik yang sesuai
- Langkah 6: Ubah proyek Visual Studio untuk menjalankan prapemrosea WPP dan membangun solusi
- Langkah 7: Mulai sesi pelacakan untuk mengambil dan memverifikasi pesan pelacakan Anda
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 apa pun yang ingin Anda instrumen untuk pelacakan.
Untuk menambahkan makro WPP_CONTROL_GUIDS ke driver Anda:
Tambahkan file header C++ baru ke proyek Visual Studio yang bisa 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).
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 berikut menggunakan myDriverTraceGuid sebagai GUIDFriendlyName. Perhatikan bahwa ControlGUID memiliki format yang sedikit berbeda dari bentuk standar GUID heksadesimal 32 digit. ControlGUID memiliki lima bidang, tetapi dipisahkan oleh koma dan dikurung oleh tanda kurung, bukan tanda hubung dan kurung kurawal biasa. Misalnya, Anda menentukan ((84bdb2e9,829e,41b3,b891,02f454bc2bd7) alih-alih {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 */ \ )Tips Anda dapat menyalin cuplikan kode ini ke dalam file header. Pastikan untuk mengubah GUID kontrol dan nama yang mudah diingat. Anda dapat menggunakan GUIDgen.exe untuk menghasilkan GUID kontrol. Guidgen.exe disertakan dengan Visual Studio (Alat > Buat GUID). Anda juga dapat menggunakan alat Uuidgen.exe, yang tersedia dari jendela prompt Perintah Visual Studio (ketik uuidgen.exe /? untuk informasi selengkapnya).
Tentukan Bendera Pelacakan 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 sukai sebagai kondisi untuk menghasilkan pesan pelacakan. Dalam contoh WPP_CONTROL_GUIDS, WPP_DEFINE_BIT menentukan empat bendera pelacakan (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 munculnya, 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).
Catatan 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 yang akan digunakan untuk 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 pelacakan yang menentukan bahwa bendera pelacakan ditulis ke log.
Langkah 2: Pilih fungsi pesan pelacakan mana yang ingin Anda gunakan dan tentukan makro WPP untuk fungsi tersebut
Seperti fungsi cetak debug, fungsi pesan pelacakan adalah fungsi (atau makro) yang Anda tambahkan ke kode Anda untuk menulis pesan pelacakan.
Memilih fungsi pesan pelacakan
Fungsi pesan pelacakan default adalah makro DoTraceMessage . Jika Anda menggunakan fungsi default, Anda dapat mengontrol kapan membuat pesan menggunakan nilai Bendera Pelacakan 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 pelacakan Anda sendiri, atau mengonversi fungsi cetak debug yang ada, lanjutkan dengan langkah lainnya.
Membuat atau menyesuaikan fungsi pesan pelacakan
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 jejak di penyedia pelacakan Anda. Letakkan makro ini di file header Trace.h yang Anda tambahkan ke proyek Anda.
Tentukan makro WPP untuk mengaktifkan fungsi pelacakan.
Setiap fungsi pesan jejak 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 hal makro WPP_LEVEL_ENABLED dan WPP_LEVEL_LOGGER default.
Setiap fungsi pesan jejak 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 hal 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, KONDISI mewakili kondisi yang didukung fungsi pesan jejak, dalam urutan yang muncul dalam daftar parameter fungsi, dipisahkan oleh garis bawah. Misalnya, fungsi pesan pelacakan default, DoTraceMessage, hanya mendukung Bendera Pelacakan sebagai kondisi, sehingga hanya ada satu parameter dalam nama makro (WPP_LEVEL_ENABLED).
Catatan Sayangnya, nama makro default (WPP_LEVEL_ENABLED dan WPP_LEVEL_LOGGER) tampaknya menunjukkan parameter Tingkat Pelacakan , tetapi mereka benar-benar merujuk ke Bendera Pelacakan.
Jika Anda menggunakan fungsi pesan pelacakan kustom, Anda dapat mengatur kualifikasi tambahan, seperti Tingkat Pelacakan. Tingkat Pelacakan didefinisikan dalam file Evntrace.h, dan tingkat pelacakan menyediakan cara yang mudah 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 Bendera Pelacakan sebagai kondisi untuk menghasilkan pesan pelacakan. Makro WPP_LEVEL_FLAGS_ENABLED mengembalikan TRUE jika pengelogan diaktifkan untuk nilai FLAGS yang ditentukan dan nilai LEVEL yang diaktifkan lebih besar dari atau sama dengan argumen tingkat yang digunakan dalam panggilan fungsi pesan pelacakan.
#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 (konfigurasi begin_wpp 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 Pelacakan dan Bendera Pelacakan sebagai kondisi untuk menghasilkan pesan. Jika Anda telah menentukan makro WPP_LEVEL_FLAGS_ENABLED dalam file header Trace.h, Anda bisa 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 untuk melacak pernyataan pesan dengan menambahkan deklarasi FUNC serupa di blok konfigurasi WPP. Misalnya, contoh berikut menambahkan kode untuk mengonversi pernyataan KdPrint yang ada. Deklarasi FUNC juga secara global mendefinisikan KdPrint untuk menggunakan tingkat pelacakan yang ditentukan dan bendera {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
//
Catatan 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 menentukan WPP_kondisi> kustom<_LOGGER dan WPP_<kondisi>_ENABLED makro. Parameter kedua untuk KdPrintEx menentukan tingkat mirip dengan nilai Tingkat Pelacakan , sehingga Anda tidak perlu menentukan ulang.
#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 pernyataan #include untuk Lacak File Header Pesan (.tmh). Saat Anda membangun driver atau aplikasi, preprosektor 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 rutinitas DriverEntry driver mode kernel atau driver UMDF 2.0, atau ke rutinitas DLLMain driver mode pengguna (UMDF 1.x) atau aplikasi.
Untuk membersihkan sumber daya WPP saat driver keluar
Tambahkan makro WPP_CLEANUP ke rutinitas pembongkaran driver (misalnya, DriverContextCleanup atau DriverUnload) dari driver mode kernel atau driver UMDF 2.0.
Untuk driver mode pengguna (UMDF 1.x) atau aplikasi, tambahkan makro WPP_CLEANUP ke rutinitas DLLMain .
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 pelacakan default adalah makro DoTraceMessage . Anda bisa menambahkan makro ini ke kode Anda untuk menulis pesan ke file log. Tabel berikut ini mencantumkan beberapa fungsi pesan pelacakan yang telah ditentukan sebelumnya dan fungsi cetak debug yang bisa Anda gunakan untuk membuat pesan pelacakan.
| Contoh fungsi lacak pesan | Waktu menggunakan |
|---|---|
| DoTraceMessage | Ini adalah fungsi pesan pelacakan default. Keuntungan menggunakan DoTraceMessage adalah fungsi tersebut sudah ditentukan untuk Anda. Anda dapat menggunakan bendera pelacakan yang Anda tentukan di makro WPP_CONFIG_GUIDS. Kerugian menggunakan DoTraceMessage, adalah bahwa fungsi hanya mengambil satu parameter kondisional, yaitu, melacak bendera. Jika Anda ingin menggunakan tingkat pelacakan, untuk mencatat hanya kesalahan atau pesan peringatan, Anda dapat menggunakan makro DoDebugTrace , atau menggunakan TraceEvents, yang menggunakan bendera pelacakan dan tingkat pelacakan. |
| TraceEvents | Jika Anda membuat driver menggunakan templat WDF di Visual Studio, ini adalah fungsi pesan pelacakan default. Keuntungan menggunakan TraceEvents adalah fungsi pesan pelacakan, bendera pelacakan, dan Tingkat Pelacakan sudah ditentukan untuk Anda. Selain itu, templat juga menyertakan instrumentasi yang menulis pesan ke file log saat entri fungsi dan keluar. |
| 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 menyesuaikan fungsi pesan pelacakan untuk menyertakan salah satu fungsi cetak debug, Anda tidak perlu melakukan pekerjaan lagi. Saat Anda membuat sesi pelacakan dengan Logman atau Tracelog, atau pengontrol pelacakan lain, Anda cukup menentukan bendera dan tingkat untuk penyedia Anda. Setiap pernyataan cetak debug yang memenuhi kondisi yang Anda tentukan dicetak ke log. |
Menggunakan pernyataan DoTraceMessage
Tambahkan makro DoTraceMessage ke kode Anda seperti yang Anda lakukan pada rutinitas cetak debug. 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 saja string spesifikasi format yang diperluas WPP?
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);
Jika Anda menggunakan templat driver Windows di Visual Studio, makro TraceEvents ditentukan untuk Anda dalam file header Trace.h.
Menggunakan pernyataan TraceEvents
Tambahkan makro TraceEvents ke kode Anda seperti yang Anda lakukan pada rutinitas cetak debug. Makro TraceEvents mengambil parameter berikut: tingkat pelacakan (Tingkat) dan bendera pelacakan (Bendera), yang menentukan kondisi saat pesan jejak ditulis, string Pesan , dan daftar variabel opsional.
TraceEvents(Level, Flags, Message, [VariableList... ]Misalnya, pernyataan TraceEvents berikut menulis nama fungsi yang berisi pernyataan TraceEvents ketika kondisi yang ditentukan dalam parameter Tingkat Pelacakan dan Bendera Pelacakan terpenuhi. Tingkat Pelacakan adalah nilai bilangan bulat; apa pun di atau di bawah Tingkat Pelacakan yang ditentukan untuk sesi pelacakan 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 diatur untuk sesi pelacakan dan Tingkat Pelacakan adalah 4 atau lebih besar, 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 saja string spesifikasi format yang diperluas WPP?
Untuk menghasilkan pesan pelacakan, buat sesi pelacakan untuk penyedia pelacakan Anda, menggunakan Logman atau Tracelog. Tentukan tingkat pelacakan ke TRACE_LEVEL_INFORMATION (4) atau lebih besar, dan tentukan tingkat pelacakan 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 WPP Preprocessor, sehingga Anda dapat menjalankan pra-prosesor menggunakan Visual Studio dan lingkungan MSBuild.
Untuk menjalankan pra-prosesor WPP
- Pilih dan tahan (atau klik kanan) proyek driver di Penjelajah Solusi dan pilih Properti.
- Di halaman properti proyek, pilih Properti Konfigurasi dan pilih Pelacakan WPP.
- Di bawah Umum, atur opsi Jalankan WPP ke Ya.
- Di bawah Baris Perintah, tambahkan opsi tambahan untuk menyesuaikan perilaku pelacakan. Untuk informasi tentang apa yang dapat Anda tambahkan, lihat Preprosektor WPP.
- Bangun proyek atau solusi untuk konfigurasi dan platform target Anda. Lihat Membangun Driver dengan 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 dari 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 uji lalu membuat sesi pelacakan untuk mengambil pesan pelacakan. 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 hanya mengatur tingkat pelacakan dan melacak bendera ke nilai maksimum sehingga semua pesan dihasilkan. Bendera pelacakan menggunakan masker bit (ULONG), sehingga Anda dapat mengatur semua bit (misalnya, 0xFFFFFFFF). Tingkat pelacakan 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 set bendera 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 pelacakan menyediakan cara yang mudah untuk mengklasifikasikan pesan pelacakan sebagai pesan kritis, kesalahan, peringatan, dan informasi.
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