Dapatkah saya menyesuaikan DoTraceMessage?

Artikel
03/08/2023

Ya, Anda dapat menulis versi makro DoTraceMessage Anda sendiri. DoTraceMessage menghasilkan pesan jejak.

Driver sampel TraceDrv menyediakan contoh metode yang dijelaskan dalam topik ini. TraceDrv tersedia di repositori sampel driver Windows di GitHub.

DoTraceMessage: Versi Default

Secara default, makro DoTraceMessage memiliki format berikut:

DoTraceMessage(Flag,"Message",MessageVariables...);

Dalam versi default ini, Bendera mewakili bendera pelacakan, yang merupakan kondisi di mana pesan dihasilkan. MessageVariables berisi daftar variabel yang dipisahkan koma yang ditentukan driver dan yang muncul dalam pesan pelacakan. Variabel MessageVariables diformat dengan menggunakan elemen printf . Praprosesor WPP membuat arahan kompilator dari makro DoTraceMessage. Makro ini menambahkan informasi definisi pesan dan informasi pemformatan ke file PDB yang dihasilkan untuk penyedia pelacakan, seperti driver mode kernel atau aplikasi mode pengguna.

Makro DoTraceMessage diperluas, secara logis, ke dalam hal berikut:

PRE macro // If defined
If (WPP_CHECK_INIT && Flag is enabled) {
 ....Call WmiTraceMessage;
}
POST macro // If defined

Perhatikan contoh kode berikut.

DoTraceMessage(ERROR, "IOCTL = %d", ControlCode);

Panggilan ini menghasilkan pesan jejak saat bendera ERROR diaktifkan. Pesannya adalah "IOCTL=%d" dan MessageVariables adalah nilai ControlCode.

Jika makro PRA-pengelogan dan pengelogan POST telah ditentukan, makro tersebut juga akan diperluas. Makro PRE dan makro POST didukung di Sistem operasi Microsoft Windows 2000 dan yang lebih baru. Untuk menggunakan makro, Anda harus membangun driver dengan menggunakan WDK. Jika Anda membangun driver dengan menggunakan versi Windows Driver Development Kit (DDK) yang lebih lama, fungsionalitas PRE dan POST tidak tersedia, dan makro tidak akan dijalankan sebagai bagian dari pernyataan pelacakan. Membangun driver dengan menggunakan versi Windows DDK yang lebih lama mungkin tidak menyebabkan kerusakan build, tetapi kode tidak akan berfungsi seperti yang diharapkan.

DoTraceMessage: Format Umum

Berikut ini adalah format umum dari fungsi pesan pelacakan yang valid:

FunctionName(Conditions...,"Message",MessageVariables...);

Parameter yang muncul sebelum pesan ditafsirkan sebagai kondisi. Parameter yang muncul setelah pesan ditafsirkan sebagai variabel pesan.

Kondisi adalah daftar nilai yang dipisahkan koma. Pesan pelacakan dihasilkan hanya jika semua kondisi benar. Anda dapat menentukan kondisi apa pun yang didukung dalam kode.

Contoh: MyTrace

Berikut ini adalah sampel fungsi pelacakan. Contoh ini menambahkan kondisi untuk tingkat pelacakan dan subkomponen penyedia yang menghasilkan pesan jejak.

MyDoTrace(Level, Flag, Subcomponent,"Message",MessageVariables...);

Contohnya:

MyDoTrace(TRACE_LEVEL_ERROR, VERBOSE, Network,"IOCTL = %d", ControlCode);

Tingkat pelacakan adalah tingkat standar yang ditentukan dalam Evntrace.h, file header publik yang ada di subdirektori Sertakan WDK.

#define TRACE_LEVEL_NONE        0   // Tracing is not on
#define TRACE_LEVEL_FATAL       1   // Abnormal exit or termination
#define TRACE_LEVEL_ERROR       2   // Severe errors that need logging
#define TRACE_LEVEL_WARNING     3   // Warnings such as allocation failure
#define TRACE_LEVEL_INFORMATION 4   // Includes non-error cases(for example, Entry-Exit)
#define TRACE_LEVEL_VERBOSE     5   // Detailed traces from intermediate steps
#define TRACE_LEVEL_RESERVED6   6
#define TRACE_LEVEL_RESERVED7   7
#define TRACE_LEVEL_RESERVED8   8
#define TRACE_LEVEL_RESERVED9   9

Cara Membuat Fungsi Pelacakan Kustom

Untuk membuat fungsi pelacakan kustom, ikuti langkah-langkah berikut:

Tulis versi alternatif makro yang mendukung makro DoTraceMessage.
Tambahkan parameter -func ke pernyataan RUN_WPP yang memanggil pra-prosesor WPP.

Tulis Makro Kustom

Untuk membuat fungsi pelacakan kustom yang mengubah kondisi untuk pesan pelacakan (parameter yang muncul sebelum pesan), Anda harus menulis versi alternatif makro yang mendukung fungsi pelacakan, WPP_LEVEL_ENABLED dan WPP_LEVEL_LOGGER.

WPP_LEVEL_ENABLED(Flags) menentukan apakah pengelogan diaktifkan dengan nilai bendera yang ditentukan. Ini mengembalikan TRUE atau FALSE.
WPP_LEVEL_LOGGER(Flags) menemukan sesi pelacakan tempat penyedia diaktifkan dan mengembalikan handel ke sesi pelacakan.

Misalnya, jika Anda ingin menyertakan tingkat pelacakan, selain bendera, sebagai kondisi, tentukan makro WPP_LEVEL_ENABLED baru yang menyertakan tingkat pelacakan. Anda dapat mendasarkan definisi makro baru pada makro default, seperti yang ditunjukkan contoh kode berikut.

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

Biasanya, makro WPP_LEVEL_LOGGER tidak terpengaruh. Dalam kasus ini, Anda dapat menentukan makro baru menjadi makro default. Contohnya:

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

Namun, dalam beberapa kasus, Anda perlu mengubah makro LOGGER. Misalnya, Anda mungkin ingin menulis fungsi pelacakan yang hanya bergantung pada tingkat pelacakan dan bukan pada bendera.

Dalam contoh kode berikut, nilai bendera dalam makro digantikan oleh nilai dummy. Tidak ada bendera yang ditentukan saat mendeklarasikan definisi GUID kontrol.

#define WPP_CONTROL_GUIDS \
   WPP_DEFINE_CONTROL_GUID(CtlGuid,(a044090f,3d9d,48cf,b7ee,9fb114702dc1),  \
        WPP_DEFINE_BIT(DUMMY))

#define WPP_LEVEL_LOGGER(lvl) (WPP_CONTROL(WPP_BIT_ ## DUMMY).Logger)

Menambahkan Fungsi ke WPP

Untuk menambahkan fungsi pelacakan kustom ke WPP, tambahkan parameter -func ke pernyataan RUN_WPP dengan deklarasi fungsi, seperti yang ditunjukkan contoh kode berikut.

RUN_WPP=$(SOURCES) -km -func:DoTraceLevelMessage(LEVEL,FLAGS,MSG,...)

Catatan Anda tidak boleh menentukan sakelar -km dalam direktif RUN_WPP untuk aplikasi mode pengguna atau pustaka tautan dinamis (DLL).

Untuk daftar lengkap parameter opsional untuk RUN_WPP, lihat Preproscessor WPP.

Bagikan melalui