Поделиться через

Добавление программной трассировки WPP в драйвер Windows

Чтобы использовать трассировку программного обеспечения WPP в поставщике трассировки, например драйвер в режиме ядра или приложение пользовательского режима, необходимо добавить код (или инструментировать) исходные файлы драйвера и изменить проект драйвера. В этом разделе описаны эти действия.

Замечание

Самый простой способ добавить трассировку WPP в драйвер — использовать один из шаблонов драйверов KMDF или UMDF в Visual Studio. Если вы используете шаблоны, большая часть кода, которую вам нужно добавить, уже сделана. В Visual Studio выберите файл > нового > проекта, а затем выберите проект WDF драйвера Windows (режим пользователя или режима ядра). Макросы WPP определяются в файле заголовка Trace.h, который входит в проект. Если вы используете один из шаблонов, перейдите к шагу 5.

Шаг 1: Определение GUID управления и флагов отслеживания

Каждый поставщик трассировки (например, драйвер или приложение пользовательского режима) должен быть однозначно определен. Для этого добавьте макрос WPP_CONTROL_GUIDS , определяющий GUID элемента управления, идентификатор и флаги трассировки. Это делается, чтобы вы могли определить и контролировать, что и когда хотите отслеживать. Хотя каждый драйвер обычно имеет отдельный GUID элемента управления, драйвер может иметь несколько идентификаторов GUID элемента управления или несколько драйверов могут совместно использовать один GUID элемента управления.

Для удобства макрос WPP_CONTROL_GUIDS обычно определяется в общем файле заголовка. Файл заголовка должен быть включен (#include) в любой исходный файл, который планируется инструментировать для трассировки.

Чтобы добавить макрос WPP_CONTROL_GUIDS в драйвер, выполните приведенные действия.

  1. Добавьте новый файл заголовка C++ в проект Visual Studio, который можно использовать для определения макросов трассировки WPP. Например, выберите и удерживайте (или щелкните правой кнопкой мыши) драйвер в обозревателе решений и выберите пункт "Добавить > новый элемент". Сохраните файл (например, Trace.h).

  2. Добавьте макрос WPP_CONTROL_GUIDS, чтобы указать понятное имя для поставщика трассировок, задать контрольный GUID и определить флаги трассировки, которые можно использовать для уточнения конкретных сообщений трассировки.

    Макрос WPP_CONTROL_GUIDS имеет следующий синтаксис:

    Синтаксис для 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) \
        )

    Например, следующий код использует myDriverTraceGuid в качестве GUIDFriendlyName. Обратите внимание, что ControlGUID имеет немного другой формат, чем стандартная форма 32-значного шестнадцатеричного GUID. ControlGUID имеет пять полей, но они разделены запятыми и скобками, а не обычными дефисами и фигурными скобками. Например, укажите ((84bdb2e9,829e,41b3,b891,02f454bc2bd7) вместо {84bdb2e9-829e-41b3-b891-02f454bc2bd7}.

    Пример инструкции 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 */ \
        )

    Замечание

    Этот фрагмент кода можно скопировать в файл заголовка. Обязательно измените GUID управления и удобочитаемое имя. Для создания GUID элемента управления можно использовать GUIDgen.exe. Guidgen.exe входит в состав Visual Studio (tools > Create GUID). Вы также можете использовать средство Uuidgen.exe, доступное в окне командной строки Visual Studio (введите uuidgen.exe /? для получения дополнительных сведений).

  3. Определите флаги трассировки для поставщика трассировки.

    Элементы WPP_DEFINE_BIT макроса WPP_CONTROL_GUIDS определяют флаги трассировки для поставщика трассировки. Как правило, флаги представляют собой все более подробные уровни отчетности, но вы можете использовать флаги любым удобным для вас образом в качестве условий для создания сообщений трассировки. В примере WPP_CONTROL_GUIDS WPP_DEFINE_BIT определяет четыре флага трассировки (MYDRIVER_ALL_INFO, TRACE_DRIVER, TRACE_DEVICE и TRACE_QUEUE).

    Можно определить до 31 флагов трассировки. WPP назначает битовые значения элементам в порядке их отображения, например бит 0 (0x1), бит 1 (0x2), бит 2 (0x4), бит 3 (0x8) и т. д. Флаги трассировки используются при добавлении функций сообщения трассировки в исходный код (описано на шаге 5. Инструментирование кода драйвера для создания сообщений трассировки в соответствующих точках).

    Замечание

    С помощью флагов трассировки можно управлять трассировкой определенных компонентов (например, конкретных запросов ввода-вывода или действий объектов устройства или драйвера). Вы добавляете флаг трассировки в инструкцию сообщения трассировки (например, DoTraceMessage (TRACE_DRIVER, "Hello World!\n"). При создании сеанса трассировки с контроллером трассировки, например Tracelog, вы указываете параметр -flag , используемый для поставщика трассировки в этом сеансе, в данном случае флаг имеет бит 1 (0x1), соответствующий флагу TRACE_DRIVER. При запуске сеанса трассировки все сообщения трассировки, связанные с указанным флагом трассировки, записываются в журнал.

Шаг 2. Выбор функций трассировки сообщений, которые вы планируете использовать, и определение макросов WPP для этих функций

Как и функция отладки печати, функция сообщения трассировки — это функция (или макрос), добавляемая в код для записи сообщений трассировки.

Выбор функции сообщения трассировки

  • Функция сообщения трассировки по умолчанию — макрос DoTraceMessage . Если вы используете функцию по умолчанию, вы можете контролировать, когда создавать сообщения с помощью значений флага трассировки для поставщика. Значения флагов трассировки — это те флаги, которые были определены при создании GUID для управления на шаге 1. Если вы используете DoTraceMessage, макросы WPP по умолчанию уже определены для вас (WPP_LEVEL_ENABLED и WPP_LEVEL_LOGGER), чтобы пропустить остальную часть этого шага и перейти к шагу 5.

  • Если вы используете один из шаблонов KMDF или UMDF, функция TraceEvents и необходимые макросы WPP уже определены для включения этой функции, чтобы перейти к шагу 5.

  • Если вы создаете собственную функцию вывода сообщений трассировки или преобразуете существующую функцию отладки, продолжайте выполнение текущего шага.

Создание или настройка функции сообщения отслеживания

  1. Если вы используете пользовательские функции сообщения трассировки или хотите преобразовать функции отладки печати (например, KdPrint) для создания сообщений трассировки, необходимо определить макросы WPP, определяющие и разрешающие функции сообщения трассировки в поставщике трассировки. Поместите эти макросы в файл заголовка Trace.h, который вы добавили в проект.

  2. Определите макросы WPP, чтобы включить функцию трассировки.

    Каждая используемая функция сообщения трассировки должна иметь соответствующую пару макросов. Эти макросы определяют поставщика трассировки и указывают условия, которые создают сообщения. Обычно вы определяете пару макросов, WPP_<condition>_LOGGER и WPP_<condition>_ENABLED с точки зрения макросов по умолчанию WPP_LEVEL_ENABLED и WPP_LEVEL_LOGGER.

Срок Описание
WPP_CONDITIONS_LOGGER Используется для поиска сеанса трассировки, связанного с поставщиком, и для возврата идентификатора сеанса.
WPP_CONDITIONS_ENABLED Используется для определения, включено ли ведение журнала при заданном условии.

Для определяемых макросов WPP условия представляют условия, поддерживаемые функцией сообщения трассировки, в том порядке, в который они отображаются в списке параметров функции, разделенных подчеркиваниями. Например, функция сообщения трассировки по умолчанию DoTraceMessage поддерживает только флаг трассировки в качестве условия, поэтому в именах макросов имеется только один параметр (WPP_LEVEL_ENABLED).

Замечание

К сожалению, имена макросов по умолчанию (WPP_LEVEL_ENABLED и WPP_LEVEL_LOGGER), как представляется, указывают на параметр уровня трассировки , но они на самом деле ссылаются на флаг трассировки.

Если вы используете пользовательскую функцию сообщения трассировки, можно задать дополнительные квалификаторы, например уровень трассировки. Уровень трассировки определяется в файле Evntrace.h, а уровни трассировки обеспечивают удобный способ классификации сообщений трассировки как ошибок, предупреждений и информационных сообщений.

Например, можно добавить следующий фрагмент кода в файл заголовка, добавленный в проект. Следующий код определяет пользовательские макросы WPP для функции сообщения трассировки, которая поддерживает параметры уровня трассировки и флага трассировки в качестве условий для создания сообщений трассировки. Макрос WPP_LEVEL_FLAGS_ENABLED возвращает значение TRUE, если ведение журнала включено для указанного значения FLAGS, а включенное значение LEVEL больше или равно аргументу уровня, используемому в вызове функции трассировки.

#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)

Затем необходимо указать пользовательские функции трассировки в блоке конфигурации WPP (begin_wpp config и end_wpp). Например, если вы используете шаблон для проектов драйверов UMDF или KMDF в Visual Studio, шаблон определяет макросы WPP для пользовательской функции трассировки сообщений, называемой TraceEvents. Макрос TraceEvents использует уровень трассировки и флаг трассировки в качестве условий для создания сообщений. Если вы определили макрос WPP_LEVEL_FLAGS_ENABLED в файле заголовка Trace.h, можно добавить следующее определение макроса.

//
// This comment block is scanned by the trace preprocessor to define the 
// TraceEvents function.
//
// begin_wpp config
// FUNC TraceEvents(LEVEL, FLAGS, MSG, ...);
// end_wpp
//

Вы также можете преобразовать существующие инструкции отладки печати в инструкции трассировки сообщений, добавив аналогичное объявление FUNC в блок конфигурации WPP. Например, в следующем примере добавляется код для преобразования существующих инструкций KdPrint . Объявление FUNC также глобально задаёт KdPrint для использования указанного уровня трассировки и флага {LEVEL=TRACE_LEVEL_INFORMATION, FLAGS=TRACE_DRIVER}. Вместо отправки выходных данных отладчику инструкции отладки отправляются в журнал трассировки.

//
// 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
//

Замечание

Если вы хотите преобразовать KdPrintEx в функцию сообщения трассировки, необходимо выполнить несколько дополнительных действий. По сравнению с KdPrint функция KdPrintEx принимает два дополнительных аргумента. Чтобы преобразовать функцию KdPrintEx, необходимо определить WPP_DEFINE_BIT для ComponentID и определить пользовательские макросы WPP_<condition>_LOGGER и WPP_<condition>_ENABLED. Второй параметр для KdPrintEx указывает уровень, аналогичный значениям уровня трассировки , поэтому их не обязательно нужно переопределить.


#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
//

Шаг 3: Включите связанные файлы заголовков трассировки (.h и .tmh) в ваши исходные файлы C или C++.

Если вы определили GUID элемента управления и флаги трассировки для драйвера в файле заголовка (например, trace.h), необходимо включить файл заголовка в исходные файлы, где вы будете инициализировать и выгружать WPP (шаг 4) или вызывать функции сообщения трассировки.

Кроме того, необходимо добавить инструкцию #include для файла заголовка сообщения трассировки (.tmh). При сборке драйвера или приложения препроцессор WPP создает файлы заголовков сообщений трассировки (.tmh) для каждого исходного файла, содержащего функции сообщения трассировки.

/* -- 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 */

Шаг 4. Добавление макросов в соответствующие функции обратного вызова для инициализации и очистки WPP

Инициализация WPP при входе в драйвер

  • Добавьте макрос WPP_INIT_TRACING в подпрограмму DriverEntry драйвера режима ядра или драйвера UMDF 2.0 или в подпрограмму DLLMain драйвера пользовательского режима (UMDF 1.x) или приложения.

Очистка ресурсов WPP при выходе драйвера

  • Добавьте макрос WPP_CLEANUP в подпрограмму выгрузки драйвера (например, DriverContextCleanup или DriverUnload) драйвера в режиме ядра или драйвера UMDF 2.0.

    Для драйвера пользовательского режима (UMDF 1.x) или приложения добавьте макрос WPP_CLEANUP в подпрограмму DLLMain .

    Кроме того, необходимо добавить макрос WPP_CLEANUP в подпрограмму DriverEntry в случае сбоя DriverEntry . Например, если DriverEntry не выполняется, процедура выгрузки драйвера не будет вызвана. См. вызов WdfDriverCreate в следующем примере.

Пример драйвера в режиме ядра с помощью WPP_INIT_TRACING и WPP_CLEANUP в 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;

}

Пример драйвера в режиме ядра с помощью WPP_CLEANUP в DriverContextCleanup



VOID
DriverContextCleanup(
       PDRIVER_OBJECT DriverObject
       )
{
    // ...

    // Clean up WPP resources on unload
    //
    WPP_CLEANUP(DriverObject);

   // ...

}

Пример драйвера UMDF 2.0 с помощью WPP_INIT_TRACING в 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 );

Пример для использования драйвера UMDF 1.0 с макросами WPP_INIT_TRACING и WPP_CLEANUP в 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);
}

Шаг 5. Добавление инструментов в код драйвера для создания сообщений трассировки в нужных местах

Вы можете использовать любую функцию сообщения трассировки по вашему выбору, при условии, что функция сообщения трассировки, флаги трассировки и уровни определены должным образом. Функция сообщения трассировки по умолчанию — макрос DoTraceMessage . Этот макрос можно добавить в код для записи сообщений в файл журнала. В следующей таблице перечислены некоторые предустановленные функции для сообщений трассировки и функции печати отладки, которые можно использовать для создания сообщений трассировки.

Примеры функций трассировочных сообщений Когда следует использовать
DoTraceMessage Это функция трассировки сообщений по умолчанию. Преимущество использования DoTraceMessage заключается в том, что функция уже определена для вас. Вы можете использовать флаги трассировки, указанные в макросе WPP_CONFIG_GUIDS. Недостатком использования DoTraceMessage является то, что функция принимает только один условный параметр, то есть флаги трассировки. Если вы хотите использовать уровни трассировки, регистрировать только сообщения об ошибках или предупреждениях, можно использовать макрос DoDebugTrace или использовать TraceEvents, в котором используются как флаги трассировки, так и уровни трассировки.
TraceEvents Если вы создаете драйвер с помощью шаблонов WDF в Visual Studio, это функция трассировки по умолчанию. Преимущество использования TraceEvents заключается в том, что функция сообщения трассировки, флаги трассировки и уровень трассировки уже определены для вас. Кроме того, шаблоны также включают инструментирование, которое записывает сообщения в файл журнала при входе и выходе функции.
KdPrint, KdPrintEx, DbgPrint, DbgPrintEx Преимущество использования функций отладки печати заключается в том, что не нужно изменять существующие инструкции отладки печати. Вы можете легко переключаться с просмотра сообщений в отладчике на запись сообщений трассировки в файле. Если вы настроили функцию сообщений трассировки для включения одной из функций вывода отладочной информации, вам больше ничего не нужно делать. При создании сеанса трассировки с помощью Logman или Tracelog или другого контроллера трассировки необходимо просто указать флаги и уровни для поставщика. Все инструкции отладки печати, соответствующие заданным условиям, печатаются в журнале.

Использование инструкций DoTraceMessage

  1. Добавьте макрос DoTraceMessage в код, как функцию отладки печати. Макрос DoTraceMessage принимает 3 параметра: уровень флага (TraceFlagName), определяющий условие при записи сообщения трассировки, строку сообщения и необязательный список переменных.

    DoTraceMessage(TraceFlagName, Message, [VariableList... ])

    Например, следующая инструкция DoTraceMessage записывает имя функции, содержащей инструкцию DoTraceMessage , когда флаг TRACE_DRIVER, как определено в WPP_CONTROL_GUIDS, включен для сеанса трассировки.

         DoTraceMessage( TRACE_DRIVER, "\nEntering %!FUNC!" );

    В примере используется предопределенная строка для выполняемой функции (%FUNC!). Дополнительные сведения о строках спецификации определенного формата WPP см. в разделе "Что такое строки спецификации расширенного формата WPP"?

  2. Чтобы создать сообщение трассировки, создайте сеанс трассировки для поставщика трассировки с помощью Logman или Tracelog и укажите флаг трассировки, который задает флаг TRACE_DRIVER (бит 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);

Использование инструкций TraceEvents

Если вы используете шаблоны драйверов Windows в Visual Studio, макрос TraceEvents определяется для вас в файле заголовка Trace.h.

  1. Добавьте макрос TraceEvents в свой код подобно тому, как вы бы добавили процедуру печати для отладки. Макрос TraceEvents принимает следующие параметры: уровень трассировки (уровень) и флаг трассировки (флаги), определяющие условие при записи сообщения трассировки, строку сообщения и необязательный список переменных.

    TraceEvents(Level, Flags, Message, [VariableList... ])

    Например, следующая инструкция TraceEvents записывает имя функции, содержащей инструкцию TraceEvents , когда выполняются условия, указанные в параметрах уровня трассировки и флага трассировки. Уровень трассировки — это целочисленное значение; в этом сеансе будут трассироваться все события, уровень которых равен или ниже заданного уровня трассировки. TRACE_LEVEL_INFORMATION определен в Evntrace.h и имеет значение 4. Флаг TRACE_DRIVER (бит 1, 0x2) определен в WPP_CONTROL_GUIDS. Если этот TRACE_DRIVER бит установлен для сеанса трассировки, а уровень трассировки равен 4 или больше, TraceEvents записывает сообщение трассировки.

            TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DRIVER, "%!FUNC! Entry");

    В примере используется предопределенная строка для выполняемой функции (%FUNC!). Дополнительные сведения о строках спецификации определенного формата WPP см. в разделе "Что такое строки спецификации расширенного формата WPP"?

  2. Чтобы создать сообщение трассировки, создайте сеанс трассировки для поставщика трассировки с помощью Logman или Tracelog. Укажите уровень трассировки TRACE_LEVEL_INFORMATION (4) или выше, и укажите уровень трассировки, устанавливающий бит TRACE_DRIVER (бит 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__);

Шаг 6. Изменение проекта Visual Studio для запуска препроцессора WPP и сборки решения

WDK обеспечивает поддержку препроцессора WPP, чтобы запустить препроцессор с помощью Visual Studio и среды MSBuild.

Запуск препроцессора WPP

  1. Выберите и удерживайте (или щелкните правой кнопкой мыши) проект драйвера в обозревателе решений и выберите пункт "Свойства".
  2. На странице свойств проекта выберите "Свойства конфигурации" и выберите трассировку WPP.
  3. В разделе "Общие" задайте для параметра Run WPP значение "Да".
  4. В командной строке добавьте дополнительные параметры для настройки поведения трассировки. Чтобы узнать, что можно добавить, см. препроцессор WPP.
  5. Создайте проект или решение для целевой конфигурации и платформы. См. статью "Создание драйвера с помощью WDK".

Сведения о процессе сборки см. в разделе "Задача TraceWPP " и среда сборки WDK и Visual Studio.

Вы также можете запустить препроцессор отдельно от среды сборки с помощью средства TraceWPP (TraceWPP.exe). Это средство находится в подкаталоге bin/x86 и bin/x64 в WDK.

Шаг 7. Запуск сеанса трассировки для записи и проверки сообщений трассировки

Чтобы убедиться, что трассировка WPP настроена правильно, необходимо установить драйвер или приложение на тестовом компьютере, а затем создать сеанс трассировки для записи сообщений трассировки. Сеанс трассировки для поставщика трассировки можно создать с помощью любого контроллера трассировки, например Logman, Tracelog или TraceView. Вы можете записать сообщения в файл журнала или отправить в отладчик ядра. В зависимости от используемых вами функций трассировки, вам необходимо указать флаги и уровни трассировки, чтобы генерировать сообщения.

Например, если вы используете уровни трассировки, определенные в Evntrace.h, и вы хотите записать TRACE_LEVEL_INFORMATION (4) или больше, необходимо задать уровень 4. При установке уровня 4 для сеанса трассировки будут также записаны все информационные сообщения (4), предупреждающие сообщения (3), сообщения об ошибках (2) и критические сообщения (1), если выполнены все другие условия, такие как флаги трассировки.

Чтобы убедиться, что создаются все сообщения, можно просто установить уровень трассировки и флаги трассировки на максимальные значения, чтобы все сообщения были созданы. Флаги трассировки используют битовую маску (ULONG), поэтому можно задать все биты (например, 0xFFFFFFFF). Уровни следов представляются значением байта. Например, если вы используете Logman, можно указать 0xFF для покрытия всех уровней.

(Пример) Запуск сеанса трассировки с помощью 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"

(Пример) Запуск сеанса трассировки с помощью TraceLog

tracelog -start MyTrace -guid  MyProvider.guid -f d:\traces\testtrace.etl -flag 2 -level 0xFFFF

Команда Tracelog включает параметр -f , чтобы указать имя и расположение файла журнала трассировки событий. Он включает параметр -flag , чтобы указать набор флагов и параметр уровня , чтобы указать параметр уровня. Эти параметры можно опустить, но некоторые поставщики трассировки не создают сообщения трассировки, если вы не настроили флаг или уровень. Уровень трассировки определен в файле Evntrace.h, а уровни трассировки позволяют классифицировать сообщения трассировки как критические, ошибки, предупреждения и информационные сообщения.

  • Last updated on