Freigeben über

TraceLogging für Kernelmodustreiber und -komponenten

In diesem Thema wird beschrieben, wie Sie die TraceLogging-API innerhalb von Kernelmodustreibern und -komponenten verwenden.

Voraussetzungen:

  • Windows 10
  • Visual Studio 2013 (oder höher)
  • Windows 10 SDK
  • Windows Driver Kit (WDK) für Windows 10

Einschließen der TraceLogging-Headerdateien

Um die TraceLogging-API zu verwenden, schließen Sie die TraceLogging-Headerdatei TraceLoggingProvider.h ein. Die andere TraceLogging-API-Headerdatei TraceLoggingActivity.h ist nur für die Verwendung in Benutzermodustreibern verfügbar, die in C++ geschrieben wurden.

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

Hinweis

Die Datei wdm.h ist für TraceLoggingProvider.h erforderlich, wenn Kernelmodustreiber entwickelt werden.

Deklarieren Des Treibers als TraceLogging-Anbieter

  1. Fügen Sie das TRACELOGGING_DECLARE_PROVIDER-Makro hinzu, um die Anbieterhandlevariable zu deklarieren. Das Makro weist die folgende Syntax auf:

    TRACELOGGING_DECLARE_PROVIDER(hProviderVariableName)

    Die folgende TraceLogging-Beispielanweisung deklariert die Variable mit dem Namen g_hProvider.

    TRACELOGGING_DECLARE_PROVIDER(g_hProvider);

    Die Variable, die Sie mit TRACELOGGING_DECLARE_PROVIDER deklarieren, wird zum Handle für den Anbieter, wenn Sie das makro TRACELOGGING_DEFINE_PROVIDER später im Code aufrufen.

    Hinweis

    Sie können dieses Makro in eine Headerdatei einfügen, damit das Handle für den TraceLogging-Anbieter global verfügbar ist.

  2. Fügen Sie das makro TRACELOGGING_DEFINE_PROVIDER hinzu, und geben Sie einen Namen für den Ablaufverfolgungsanbieter und das Ablaufverfolgungsanbieterhandle an. Das Handle ist die Variable, die Sie in Schritt 1 deklariert haben. Die Syntax des Makros lautet:

    TRACELOGGING_DEFINE_PROVIDER(hProviderVariableName, "ProviderName", providerId [,option])

    Die folgende Anweisung definiert beispielsweise einen Anbieter namens MyTraceLoggingProviderKM und weist ihn dem Handle g_hProvider zu. Der providerId-Parameter ist die ETW-Anbieter-GUID.

    TRACELOGGING_DEFINE_PROVIDER(g_hProvider, "MyTraceLoggingProviderKM",
    (0xb3864c38, 0x4273, 0x58c5, 0x54, 0x5b, 0x8b, 0x36, 0x08, 0x34, 0x34, 0x71));

    Das TRACELOGGING_DEFINE_PROVIDER Makro ordnet Speicher für einen Anbieter zu und definiert eine entsprechende Variable, die das globale Handle für den Anbieter darstellt. Der Anbietername muss ein Zeichenfolgenliteral (keine Variable) sein und darf keine "\0"-Zeichen enthalten. Das Handle und die Kopien des Handles sind gültig, solange sich das ursprüngliche Handle im Gültigkeitsbereich befindet.

    Wenn Sie das Handle zum ersten Mal mit dem Makro TRACELOGGING_DEFINE_PROVIDER erstellen, befindet sich der Anbieter im Status nicht registriert. In diesem Zustand ignoriert der Anbieter alle Ablaufverfolgungsschreibaufrufe, bis er registriert ist.

    Hinweis

    Beachten Sie für den Kernelmodus, dass anbietermetadaten zwar explizit in TLG_METADATA_SEGMENT (.rdata) gespeichert werden, den Variablen, die Sie für das Handle erstellen (z. B. g_hProvider) und dem Namen des Anbieters (z. B. "MyTraceLoggingProviderKM") nicht explizit ein Segment zugewiesen werden und die aktuellen impliziten Segmente verwenden.

Das TRACELOGGING_DEFINE_PROVIDER Makro erwartet, dass sich die an das Makro übergebenen Variablen im nicht auslagerten Pool befinden. Wenn dies noch nicht der Fall ist, muss der Aufrufer das Datensegment über #pragma data_seg (für uniqueVarName) oder das const-Segment über #pragma const_seg (für g_hMyProvider) festlegen, bevor das makro TRACELOGGING_DEFINE_PROVIDER aufgerufen wird.

Registrieren des Treibers mit TraceLogging

In Ihrer DriverEntry-Funktion müssen Sie den TraceLogging-Anbieter registrieren. Um den Anbieter bei TraceLogging zu registrieren, fügen Sie driverEntry das Makro TraceLoggingRegister hinzu:

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

Aufheben der Registrierung des Anbieters in der Routine zum Entladen oder Bereinigen des Treibers

Heben Sie in Ihrer DriverUnload - oder Cleanupfunktion die Registrierung des TraceLogging-Anbieters auf.

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

Protokollieren von Ereignissen im Code

TraceLogging stellt Makros zum Protokollieren von Ereignissen bereit.

Das grundlegende Makro ist TraceLoggingWrite. Dieses Makro weist die folgende Syntax auf:

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

Dabei ist g_hProvider das Handle für den von Ihnen definierten Anbieter, und "EventName" ist ein Zeichenfolgenliteral (keine Variable), das Sie zum Identifizieren des spezifischen Ereignisses verwenden. Wie printf oder DbgPrint unterstützt das TraceLoggingWrite-Makro eine variable Anzahl zusätzlicher Parameter (bis zu 99). Die Parameter (Args) müssen TraceLogging-Wrappermakros sein, z. B. TraceLoggingLevel, TraceLoggingInt32 oder TraceLoggingString. Die TraceLogging-Wrappermakros sind in TraceLoggingProvider.h definiert.

Hinweis

Wenn Sie C++ verwenden, können Sie das TraceLoggingValue-Wrappermakro verwenden, um den Typ automatisch anzupassen. Wenn Sie Ihren Treiber in C schreiben, müssen Sie die typspezifischen Feldmakros verwenden (z. B. TraceLoggingInt32 oder TraceLoggingUnicodeString).

Im folgenden Beispiel wird ein Ereignis für den Anbieter protokolliert, g_hProvider. Das Ereignis heißt "MyDriverEntryEvent". Das Makro verwendet die Wrapper TraceLoggingPointer und TraceLoggingUnicodeString, um den Zeiger auf das Treiberobjekt und den Registrierungspfad in das Ablaufverfolgungsprotokoll zu schreiben. Der TraceLoggingUnicodeString-Wrapper nimmt einen optionalen Namen an. In diesem Beispiel ist "RegPath" der Name des RegistryPath-Werts. Wenn kein Name angegeben wird, wird der Wert als Name verwendet.

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

Wenn Sie einen Kernelmodustreiber (in C) instrumentieren, verknüpfen Sie mit TraceLoggingProvider.h, und Sie können die Makros TraceLoggingWrite, TraceLoggingWriteActivity oder TraceLoggingActivityMarker verwenden. Beispiele für die Ablaufverfolgungsprotokollierung finden Sie unter TraceLogging-Beispiele.

Wenn Sie einen Treiber oder eine Komponente instrumentieren, der in C++ geschrieben ist, verknüpfen Sie mit TraceLoggingProvider.h und TraceLoggingActivity.h. Wenn Sie eine Verknüpfung mit dem C++-Header herstellen, können Sie Ereignisse mit den Makros TraceLoggingWriteStart, TraceLoggingWriteStop und TraceLoggingWriteTagged protokollieren.

Beispiele zum Erfassen und Anzeigen von TraceLogging-Daten finden Sie unter Erfassen und Anzeigen von TraceLogging-Daten.

  • Last updated on