Средство записи трассировки в полете (IFR) для ведения журнала трассировки

Inflight Trace Recorder (IFR) — это функция трассировки, которая позволяет поставщику трассировки, например драйверу режима ядра или драйверу UMDF, создавать набор циклических буферов в памяти, в которых сохраняются последние сообщения журнала. Сообщения журнала можно просматривать с помощью отладчика.

IFR построен на основе программной трассировки WPP. Основное преимущество IFR по сравнению с WPP заключается в том, что оно включается автоматически, что вам не нужно заранее запускать сеансы трассировки.

Относится к:

• Минимальная ОС: Windows 8 для разработчиков драйверов KMDF и WDM
• Минимальная ОС: Windows 10 для разработчиков драйверов UMDF (2.15)

Как включить регистратор трассировки Inflight в Visual Studio

Сначала выполните действия, описанные в разделе "Добавление трассировки программного обеспечения WPP в драйвер Windows".

Затем на странице свойств проекта в разделе "Свойства конфигурации->трассировка WPP->Функции и параметры макроса->Включите средство записи трассировки в режиме 'В полете', выберите 'Да'.

Наконец, только для UMDF существует один дополнительный шаг: в разделе "Трассировка WPP-Опции функций и макросов-определения препроцессора", добавьте WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Включение Inflight Trace Recorder из командной строки

Если изменить файл .vcxproj вручную, задайте следующие записи:

Для драйвера KMDF или WDM:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppKernelMode>true</WppKernelMode>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        ...
    </ClCompile>

Для драйвера UMDF:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        <WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
        ...
    </ClCompile>

Как настроить параметры регистратора трассировки в полете

Вы можете настроить IFR, задав следующие необязательные записи реестра в разделе параметра драйвера.

Используйте следующие записи реестра:

LogPages: REG_DWORD

Задайте для хранения журнала по умолчанию количество страниц. Значение по умолчанию — "один".

VerboseOn: REG_DWORD

Значение по умолчанию ноль вызывает регистрацию ошибок, предупреждений и информационных событий в IFR. Установите значение один, чтобы добавить развернутый вывод в журнал.

WppRecorder_UseTimeStamp: REG_DWORD (доступно начиная с сборки WDK 22557)

Драйверы задают эту запись для добавления меток времени в записи журнала, которые затем можно просматривать с помощью !rcdrkd.rcdrlogdump или !wdfkd.wdflogdump.

WppRecorder_PreciseTimeStamp: REG_DWORD (доступно начиная с сборки WDK 22557)

Если вы хотите более точные метки времени в дополнение к WppRecorder_UseTimeStamp, добавьте WppRecorder_PreciseTimeStamp с помощью того же синтаксиса, показанного выше.

Примеры

В следующих примерах добавьте строки между начальными и конечными комментариями, чтобы задать количество страниц журнала двумя и включить метки времени.

Для драйвера в режиме ядра:

[IfrSample_Service_Inst] 
DisplayName    = %IfrSample.SvcDesc%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary  = %12%\IfrSample.sys
; =============== START
AddReg = IfrSample_Service_Inst.AddReg
 
[IfrSample_Service_Inst.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

[Strings]
REG_DWORD = 0x00010001

Для драйвера UMDF:

[IfrSampleUm_Install] 
UmdfLibraryVersion=$UMDFVERSION$
ServiceBinary=%13%\IfrSampleUm.dll
; =============== START
AddReg=IfrSampleUm_Install.AddReg
 
[IfrSampleUm_Install.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

Как отправить сообщения трассировки в журнал по умолчанию

Следуйте инструкциям по добавлению трассировки программного обеспечения WPP в драйвер Windows. Рассмотрим пример.

• В DriverEntry вызовите WPP_INIT_TRACING(DriverObject, RegistryPath).
• В EvtDriverUnload вызовите WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

Теперь драйвер может вызвать функцию трассировки по мере необходимости. Например: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

См. дополнительные сведения в WPP_INIT_TRACING и WPP_CLEANUP.

Отправка сообщений трассировки в пользовательский журнал

Это относится только к драйверам режима ядра (KMDF или WDM).

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

Например, при написании драйвера шины может потребоваться, чтобы у каждого дочернего устройства был собственный буфер. Затем можно использовать отладчик для выгрузки исключительно журнала конкретного дочернего устройства.

Чтобы настроить пользовательские журналы, драйвер должен включать компонент <WppRecorder.h>. Затем вызовите следующие API:

• WppRecorderLogCreate для создания нескольких буферов журнала
• WppRecorderLogDelete перед вызовом WPP_CLEANUP.
• WppRecorderLogSetIdentifier , чтобы задать строковый идентификатор для заданного журнала записи (необязательно)
• WppRecorderConfigure чтобы отключить журнал по умолчанию (необязательно)

Драйвер также должен определить новый макрос трассировки, который принимает дескриптор журнала в качестве первого параметра. Пример см. в драйвере примера тостера.

Как добавить временную метку в пользовательский журнал

Если драйвер вызывает WppRecorderLogCreate для создания дополнительных дескрипторов журналов, можно включить метки времени для некоторых дескрипторов журналов, но не других.

Для этого необходимо добавить одну строку в код драйвера для каждого дескриптора журнала, который должен использовать метки времени. Пример кода см. в разделе WppRecorderLogCreate.

Просмотр сообщений трассировки в отладчике

Для драйверов KMDF и UMDF используйте !wdfkd.wdflogdump как обычно. Он выведет журнал IFR платформы и журнал IFR драйвера.

Для драйверов WDM используйте !rcdrkd.rcdrloglist и !rcdrkd.rcdrlogdump.