Использование Inflight Trace Recorder (IFR) в драйверах KMDF и UMDF 2

Статья
2025-04-04

Начиная с Windows 10, вы можете создать драйвер KMDF или UMDF, чтобы получить дополнительные сведения об отладке драйверов с помощью предварительной обработки трассировки программного обеспечения Windows. Эта функция, называемая inflight Trace Recorder (IFR), доступна начиная с KMDF версии 1.15 и UMDF версии 2.15.

Устройство записи трассировки Inflight является расширением трассировки программного обеспечения WPP. В отличие от трассировки WPP, средство записи трассировки Inflight продолжает работать без подключенного потребителя данных трассировки. Платформа записывает сообщения в циклический буфер, а драйвер также может добавлять собственные сообщения. Каждый драйвер имеет собственный журнал, поэтому несколько устройств, связанных с драйвером, совместно используют один журнал.

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

Журналы хранятся в нестраничной памяти, поэтому их можно восстановить после сбоя системы. Кроме того, журналы записи трассировки полета включаются в мини-файлы, за исключением случаев, когда ответственный драйвер не определен или сбой вызван временем ожидания узла.

Включение средства записи трассировки в полете и отправка сообщений от вашего драйвера

В Microsoft Visual Studio выполните следующие действия.
- Откройте страницы свойств для проекта драйвера. Щелкните правой кнопкой мыши проект драйвера в обозревателе решений и выберите Свойства. На страницах свойств драйвера выберите свойства конфигурации, а затем трассировки Wpp. В меню Общие установите Выполнение трассировки WPP на Да.
- Перейдите к разделу Properties->Wpp Tracing->Function and Macro Options и выберите Включить запись WPP.
- В том же меню установите Scan Configuration Data на файл, содержащий информацию о трассировке, например Trace.h.
В каждом исходном файле, который вызывает макрос WPP, добавьте директиву #include для использования файла заголовка сообщения трассировки (TMH). Имя файла должно иметь формат <driver-source-file-name>.tmh.

Например, если драйвер состоит из двух исходных файлов, называемых MyDriver1.c и MyDriver2.c, то MyDriver1.c должен содержать:

#include "MyDriver1.tmh"

и MyDriver2.c должен содержать:

#include "MyDriver2.tmh"

При сборке драйвера в Visual Studio препроцессор WPP создает файлы .tmh.
Определите макрос WPP_CONTROL_GUIDS в файле заголовка. Этот макрос определяет GUID и флаги трассировки для сообщений трассировки драйвера.

Пример драйвера Osrusbfx2 определяет один GUID элемента управления и семь флагов трассировки в файле заголовка Trace.h, как показано в следующем примере:
```
#define WPP_CONTROL_GUIDS \
WPP_DEFINE_CONTROL_GUID(OsrUsbFxTraceGuid, \
  (d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \
  WPP_DEFINE_BIT(DBG_INIT)          /* bit  0 = 0x00000001 */ \
  WPP_DEFINE_BIT(DBG_PNP)           /* bit  1 = 0x00000002 */ \
  WPP_DEFINE_BIT(DBG_POWER)         /* bit  2 = 0x00000004 */ \
  WPP_DEFINE_BIT(DBG_WMI)           /* bit  3 = 0x00000008 */ \
  WPP_DEFINE_BIT(DBG_CREATE_CLOSE)  /* bit  4 = 0x00000010 */ \
  WPP_DEFINE_BIT(DBG_IOCTL)         /* bit  5 = 0x00000020 */ \
  WPP_DEFINE_BIT(DBG_WRITE)         /* bit  6 = 0x00000040 */ \
  WPP_DEFINE_BIT(DBG_READ)          /* bit  7 = 0x00000080 */ \
)
```
В этом примере:
- #B0 OsrUsbFxTraceGuid #C1 — дружественное имя GUID {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB}.
- Флаги трассировки используются для различения сообщений трассировки, создаваемых, когда драйвер обрабатывает различные типы запросов ввода-вывода.
Драйвер (как KMDF, так и UMDF 2) должен вызывать WPP_INIT_TRACING для драйверов категории Kernel-Mode с объектом драйвера и путем в реестре, как правило, из DriverEntry:
```
WPP_INIT_TRACING( DriverObject, RegistryPath );
```
Чтобы отключить трассировку, драйверы KMDF и UMDF 2 вызывают WPP_CLEANUP для драйверов Kernel-Mode из EvtCleanupCallback или EvtDriverUnload:
```
WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));
```
Макрос WPP_CLEANUP принимает параметр типа PDRIVER_OBJECT, поэтому, если функция DriverEntry вашего драйвера завершается неудачей, можно пропустить вызов WdfDriverWdmGetDriverObject и вместо него вызвать WPP_CLEANUP с указателем на объект драйвера WDM.

Так как драйверы UMDF используют подписи режима ядра этих макросов для инициализации и очистки трассировки, вызовы выглядят идентичными для KMDF и UMDF.
Используйте макрос DoTraceMessage или настраиваемую версию макроса в вашем драйвере для создания сообщений трассировки.

В следующем примере показано, как драйвер Osrusbfx2 использует функцию #B0 TraceEvents #C1 в части кода, посвященной обработке запросов на чтение:
```
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
    TraceEvents(TRACE_LEVEL_ERROR,
                DBG_READ,
                "Transfer exceeds %d\n",
                TEST_BOARD_TRANSFER_BUFFER_SIZE);

    status = STATUS_INVALID_PARAMETER;
}
```
Вызов TraceEvents создает сообщение трассировки, если контроллер трассировки включает уровень TRACE_LEVEL_ERROR и флаг трассировки DBG_READ. Сообщение содержит значение константы, определённой драйвером, TEST_BOARD_TRANSFER_BUFFER_SIZE.
Чтобы изменить размер кругового буфера, используемого журналом драйвера, измените значение реестра LogPages в следующем расположении в реестре:

Для UMDF:

SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\YourDriver\Parameters\Wdf

для KMDF:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\<YourDriver>\Parameters\Wdf

Это значение типа REG_DWORD, которое указывает размер выделяемого буфера журнала в страницах. Допустимые значения находятся между 0x1 и 0x10.

для драйвера KMDF

Загрузите команды RCDRKD, введя rcdrkd.dll.load в отладчике.
Используйте расширение !wdfkd.wdfldr для отображения информации о драйверах, которые в настоящее время динамически связаны с Windows Driver Frameworks (WDF).
Используйте !rcdrkd.rcdrlogdump и !rcdrkd.rcdrcrashdump для просмотра сообщений, предоставляемых драйвером.
Используйте !wdfkd.wdflogdump или !wdfkd.wdfcrashdump для просмотра сообщений, предоставляемых фреймворком.

#B0 Интерактивная отладка драйвера UMDF #C1

Используйте расширение !wdfkd.wdfldr для отображения сведений о драйверах, которые в настоящее время динамически привязаны к WDF. Найдите драйвер в пользовательском режиме. Введите связанный хост-процесс.
Введите !wdfkd.wdflogdump<YourDriverName.dll><Флаг> , где <Флаг>:
- 0x1 — совмещенные каркасы и журналы драйверов
- 0x2 — журналы драйверов
- 0x3 — журналы Платформы
Если для указанного драйвера нет журнала драйверов, расширение отображает только журнал платформы.

Просмотр журналов трассировки Inflight Trace Recorder после сбоя драйвера UMDF

В WinDbg выберите File-Open Crash Dump и укажите файл дампа мини-снимка, который вы хотите отладке.
Введите !wdfkd.wdfcrashdump <YourDriverName.dll><идентификатор процесса узла драйвера><. Параметр>, где <Параметр> следующий:
- 0x1 — объединённые журналы фреймворка и драйверов
- 0x2 — журналы драйверов
- 0x3 — логи фреймворка
Если вы не укажете драйвер, !wdfcrashdump отображает информацию для всех драйверов. Если вы не указываете процесс узла, а есть только один, расширение использует один процесс узла. Если не указать хост-процесс и существует более одного, расширение перечисляет активные хост-процессы.

Если данные журнала, хранящиеся в минидампе, не совпадают с введённым именем, минидамп не содержит журналов драйвера.

Если у вас нет отладчика, вы по-прежнему можете получить доступ к журналам драйверов и платформ. Чтобы узнать как, см. Видео: доступ к журналам IFR драйвера без отладчика.

Дополнительные сведения о добавлении сообщений трассировки в драйвер см. в разделе Добавление макросов WPP в драйвер.

Как включить отладку драйвера UMDF

Расширения RCDRKD

Использование средства ведения журнала событий фреймворка

Использование трассировки программного обеспечения WPP в драйверах UMDF

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

Использование Inflight Trace Recorder (IFR) в драйверах KMDF и UMDF 2

Связанные статьи

Обратная связь

Дополнительные ресурсы