TraceLogging untuk driver dan komponen mode kernel

Artikel
06/15/2023

Topik ini menjelaskan cara menggunakan TRACELogging API dari dalam driver dan komponen mode kernel.

Prasyarat:

Windows 10
Visual Studio 2013 (atau yang lebih baru)
Windows 10 SDK
Windows Driver Kit (WDK) untuk Windows 10

Sertakan file header TraceLogging

Untuk menggunakan TRACELogging API, sertakan file header TraceLogging TraceLoggingProvider.h. File header TRACELogging API lainnya, TraceLoggingActivity.h, hanya tersedia untuk digunakan dalam driver mode pengguna yang ditulis dalam C++.

#include <wdm.h>
#include <TraceLoggingProvider.h>

Catatan

File wdm.h diperlukan untuk TraceLoggingProvider.h saat mengembangkan driver mode kernel.

Nyatakan driver Anda sebagai penyedia TraceLogging

Tambahkan makro TRACELOGGING_DECLARE_PROVIDER untuk mendeklarasikan variabel handel penyedia. Makro memiliki sintaks:
```
TRACELOGGING_DECLARE_PROVIDER(hProviderVariableName)
```
Contoh berikut pernyataan TraceLogging mendeklarasikan variabel bernama g_hProvider.
```
TRACELOGGING_DECLARE_PROVIDER(g_hProvider);
```
Variabel yang Anda deklarasikan dengan TRACELOGGING_DECLARE_PROVIDER menjadi handel ke penyedia saat Anda memanggil makro TRACELOGGING_DEFINE_PROVIDER nanti dalam kode Anda.

Catatan

Anda mungkin ingin menempatkan makro ini dalam file header sehingga handel ke penyedia TraceLogging tersedia secara global.
Tambahkan makro TRACELOGGING_DEFINE_PROVIDER , dan tentukan nama untuk penyedia pelacakan dan handel penyedia pelacakan. Handel adalah variabel yang Anda deklarasikan di langkah 1. Sintaks makro adalah:
```
TRACELOGGING_DEFINE_PROVIDER(hProviderVariableName, "ProviderName", providerId [,option])
```
Misalnya, pernyataan berikut mendefinisikan penyedia yang disebut MyTraceLoggingProviderKM dan menetapkannya ke handel g_hProvider. Parameter providerId adalah GUID penyedia ETW.
```
TRACELOGGING_DEFINE_PROVIDER(g_hProvider, "MyTraceLoggingProviderKM",
    (0xb3864c38, 0x4273, 0x58c5, 0x54, 0x5b, 0x8b, 0x36, 0x08, 0x34, 0x34, 0x71));
```
Makro TRACELOGGING_DEFINE_PROVIDER mengalokasikan penyimpanan untuk penyedia dan menentukan variabel terkait yang merupakan handel global ke penyedia. Nama penyedia harus berupa string literal (bukan variabel) dan tidak boleh berisi karakter '\0'. Handel dan salinan handel valid selama handel asli berada dalam cakupan.

Ketika Anda pertama kali membuat handel dengan makro TRACELOGGING_DEFINE_PROVIDER , penyedia berada dalam status tidak terdaftar. Dalam status ini, penyedia akan mengabaikan setiap panggilan tulis jejak sampai terdaftar.

Catatan

Untuk mode kernel, ketahuilah bahwa meskipun metadata penyedia disimpan secara eksplisit ke dalam TLG_METADATA_SEGMENT (.rdata), variabel yang Anda buat untuk handel (misalnya, g_hProvider) dan nama penyedia (misalnya, "MyTraceLoggingProviderKM") tidak secara eksplisit menetapkan segmen dan akan menggunakan segmen implisit saat ini.

Makro TRACELOGGING_DEFINE_PROVIDER mengharapkan variabel yang diteruskan ke dalamnya berada di kumpulan yang tidak disebarkan. Jika ini belum terjadi, pemanggil harus mengatur segmen data melalui #pragma data_seg (untuk uniqueVarName) atau segmen const melalui #pragma const_seg (untuk g_hMyProvider) sebelum memanggil makro TRACELOGGING_DEFINE_PROVIDER .

Daftarkan driver dengan TraceLogging

Dalam fungsi DriverEntry Anda, Anda harus mendaftarkan penyedia TraceLogging. Untuk mendaftarkan penyedia dengan TraceLogging, tambahkan makro TraceLoggingRegister ke DriverEntry:

// Register the TraceLogging provider in the DriverEntry method.
TraceLoggingRegister(g_hProvider);

Membatalkan pendaftaran penyedia dalam rutinitas pembongkaran driver atau pembersihan

Dalam fungsi DriverUnload atau pembersihan Anda, batalkan pendaftaran penyedia TraceLogging.

// Stop TraceLogging and unregister the provider
TraceLoggingUnregister(g_hProvider);

Mencatat peristiwa dalam kode Anda

TraceLogging menyediakan makro untuk peristiwa pengelogan.

Makro dasar adalah TraceLoggingWrite. Makro ini memiliki sintaks berikut:

TraceLoggingWrite(g_hProvider, "EventName", args...)

Jika g_hProvider adalah handel untuk penyedia yang Anda tentukan dan "EventName" adalah string literal (bukan variabel) yang Anda gunakan untuk mengidentifikasi peristiwa tertentu. Seperti printf atau DbgPrint, makro TraceLoggingWrite mendukung jumlah variabel parameter tambahan (hingga 99). Parameter (argumen) harus berupa makro pembungkus TraceLogging, seperti TraceLoggingLevel, TraceLoggingInt32, atau TraceLoggingString. Makro pembungkus TraceLogging ditentukan dalam TraceLoggingProvider.h.

Catatan

Jika Anda menggunakan C++, Anda bisa menggunakan makro pembungkus TraceLoggingValue untuk menyesuaikan tipe secara otomatis. Jika Anda menulis driver Anda di C, Anda harus menggunakan makro bidang khusus jenis (misalnya, TraceLoggingInt32 atau TraceLoggingUnicodeString).

Contoh berikut mencatat peristiwa untuk penyedia, g_hProvider. Acara ini disebut "MyDriverEntryEvent." Makro menggunakan pembungkus TraceLoggingPointer dan TraceLoggingUnicodeString untuk menulis penunjuk ke objek driver dan jalur registri ke log jejak. Pembungkus TraceLoggingUnicodeString mengambil nama opsional. Dalam contoh ini, "RegPath" adalah nama nilai RegistryPath. Jika tidak ada nama yang ditentukan, nilai digunakan sebagai nama.

TraceLoggingWrite(
        g_hProvider,
        "MyDriverEntryEvent",
        TraceLoggingPointer(DriverObject),
        TraceLoggingUnicodeString(RegistryPath, "RegPath")); 
);

Jika Anda melengkapi driver mode kernel (di C), Anda menautkan ke makro TraceLoggingProvider.h, dan Anda dapat menggunakan makro TraceLoggingWrite, TraceLoggingWriteActivity, atau TraceLoggingActivityMarker . Untuk contoh pembuatan log jejak, lihat Contoh TraceLogging.

Jika Anda melengkapi driver atau komponen yang ditulis dalam C++, Anda menautkan ke TraceLoggingProvider.h dan TraceLoggingActivity.h. Saat menautkan ke header C++, Anda dapat mencatat peristiwa dengan makro TraceLoggingWriteStart, TraceLoggingWriteStop, dan TraceLoggingWriteTagged .

Untuk contoh cara mengambil dan melihat data TraceLogging, lihat Mengambil dan melihat data TraceLogging.

Bagikan melalui