Fungsi EtwWrite (wdm.h)

Artikel
02/29/2024

Fungsi EtwWrite adalah fungsi pelacakan untuk menerbitkan peristiwa dalam kode driver mode kernel Anda.

Sintaks

NTSTATUS EtwWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in, optional] LPCGUID                ActivityId,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

Parameter

[in] RegHandle

Penunjuk ke handel pendaftaran penyedia peristiwa, yang dikembalikan oleh fungsi EtwRegister jika pendaftaran penyedia peristiwa berhasil.

[in] EventDescriptor

Penunjuk ke struktur EVENT_DESCRIPTOR .

[in, optional] ActivityId

Pengidentifikasi yang menunjukkan aktivitas yang terkait dengan peristiwa. ActivityID menyediakan cara untuk mengelompokkan peristiwa terkait dan digunakan dalam pelacakan end-to-end.

[in] UserDataCount

Jumlah struktur EVENT_DATA_DESCRIPTOR di UserData.

[in, optional] UserData

Penunjuk ke array struktur EVENT_DATA_DESCRIPTOR.

Nilai kembali

Jika peristiwa berhasil diterbitkan, EtwWrite akan mengembalikan STATUS_SUCCESS.

Jika penunjuk ke handel pendaftaran penyedia peristiwa tidak valid, EtwWrite mengembalikan STATUS_INVALID_HANDLE. Penyedia acara harus terdaftar sebelum EtwWrite dipanggil. EtwWrite juga dapat mengembalikan STATUS_INVALID_HANDLE jika tidak dapat mencatat peristiwa.

Jika jumlah struktur EVENT_DATA_DESCRIPTOR yang ditentukan dalam UserDataCount lebih besar dari maksimum yang diizinkan (128), EtwWrite mengembalikan STATUS_INVALID_PARAMETER.

Jika ActivityID ditentukan, tetapi tidak ada cukup memori yang tersedia untuk mencatat data yang terkait dengan peristiwa, EtwWrite mengembalikan STATUS_NO_MEMORY.

Jika penyedia tidak diaktifkan untuk sesi apa pun, EtwWrite mengembalikan STATUS_SUCCESS dan peristiwa tidak dicatat.

Peristiwa dapat hilang karena beberapa alasan; misalnya, jika tingkat peristiwa terlalu tinggi atau jika ukuran peristiwa lebih besar dari ukuran buffer. Dalam kasus ini, penghitung EventsLost , anggota struktur EVENT_TRACE_PROPERTIES untuk pencatat yang sesuai, diperbarui dengan jumlah peristiwa yang tidak direkam.

Keterangan

Fungsi EtwWrite adalah mode kernel yang setara dengan fungsi EventWrite mode pengguna. Untuk memastikan bahwa ada konsumen untuk peristiwa yang Anda terbitkan, Anda dapat mendahului panggilan ke EtwWrite dengan panggilan ke EtwEventEnabled atau EtwProviderEnabled.

Sebelum Anda dapat memanggil fungsi EtwWrite untuk menerbitkan peristiwa, Anda harus mendaftarkan penyedia dengan EtwRegister. Tidak ada panggilan pelacakan yang harus dilakukan yang berada di luar kode yang dibatasi oleh fungsi EtwRegister dan EtwUnregister . Untuk performa terbaik, Anda dapat memanggil fungsi EtwRegister dalam rutinitas DriverEntry dan fungsi EtwUnregister dalam rutinitas DriverUnload Anda.

Jika Anda menggunakan parameter UserData opsional dalam fungsi EtwWrite untuk mencatat data peristiwa tambahan, Anda dapat menggunakan makro EventDataDescCreate untuk menyederhanakan pembuatan struktur EVENT_DATA_DESCRIPTOR. Contoh berikut menggunakan makro EventDataDescCreate untuk menginisialisasi struktur EVENT_DATA_DESCRIPTOR dengan nama perangkat dan statusnya. Makro EventDataDescCreate menyimpan pointer ke data (artinya, tidak menyimpan salinan data). Pointer harus tetap valid sampai panggilan ke EtwWrite kembali.

Anda dapat memanggil EtwWrite di IRQL apa pun. Namun, ketika IRQL lebih besar dari APC_LEVEL, data apa pun yang diteruskan ke fungsi EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer tidak boleh dapat dipaginasi. Artinya, setiap rutinitas mode kernel yang berjalan di IRQL yang lebih besar dari APC_LEVEL tidak dapat mengakses memori yang dapat dipaginasi. Data yang diteruskan ke fungsi EtwWrite, EtwWriteEx, EtwWriteString, dan EtwWriteTransfer harus berada di memori ruang sistem, terlepas dari apa itu IRQL.

Contoh

 
 //
 // Register the provider with ETW in DriverEntry
 // Unregister the provider in DriverUnload 
    //
 //  Build the EVENT_DATA_DESCRIPTOR structures using 
 //   the EventDataDescCreate macros 
 
 if (RegHandle != (REGHANDLE)NULL) {
 //
 // Log an Event with : DeviceNameLength
 //                      DeviceName
 //                      Status
 //
 
 EventDataDescCreate(&EventDataDescriptor[0],
                            (PVOID)&DeviceName.Length,
 sizeof(USHORT));
 

 EventDataDescCreate(&EventDataDescriptor[1],
                            (PVOID)DeviceName.Buffer,
 DeviceName.Length);
 
 EventDataDescCreate(&EventDataDescriptor[2],
                            (PVOID)&Status,
 sizeof(ULONG));
 
 EtwWrite(RegHandle,            // Handle from EtwRegister
                 &StartEvent,          // EventDescriptor
                 NULL,                 // Activity ID
                 3,                    // Number of data items
 EventDataDescriptor); // Array of data descriptors
    }              

//

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Tingkat apa pun (Lihat bagian Komentar.)