Использование средства записи трассировки inflight (IFR) в драйверах KMDF и UMDF 2

Статья
07/08/2024

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

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

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

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

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

В Microsoft Visual Studio выполните следующие действия.
- Откройте страницы свойств для проекта драйвера. Щелкните правой кнопкой мыши проект драйвера в Обозреватель решений и выберите "Свойства". На страницах свойств драйвера выберите "Свойства конфигурации" и " Трассировка Wpp". В меню "Общие" задайте для запуска трассировки WPP значение "Да".
- Перейдите в раздел Properties-Wpp> Trace-Function> и Macro Options и выберите Enable WPP Recorder.
- В том же меню задайте для файла данные конфигурации сканирования, содержащего сведения о трассировки, например 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 */ \
)
```
В этом примере:
- OsrUsbFxTraceGuid — понятное имя GUID {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB} .
- Флаги трассировки используются для различения сообщений трассировки, создаваемых в качестве драйвера, обрабатывает различные типы запросов ввода-вывода.
Драйвер (как KMDF, так и UMDF 2) должен вызывать WPP_INIT_TRACING для драйверов в режиме ядра с объектом драйвера и путем реестра, как правило, из DriverEntry:
```
WPP_INIT_TRACING( DriverObject, RegistryPath );
```
Чтобы отключить трассировку, драйверы KMDF и UMDF 2 вызывают WPP_CLEANUP для драйверов режима ядра из EvtCleanupCallback или EvtDriverUnload:
```
WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));
```
Макрос WPP_CLEANUP принимает параметр типа PDRIVER_OBJECT, поэтому если драйвер DriverEntry завершается ошибкой, можно пропустить вызов WdfDriverWdmGetDriverObject и вместо этого вызвать WPP_CLEANUP с указателем на объект драйвера WDM.

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

В следующем примере показано, как драйвер Osrusbfx2 использует функцию TraceEvents в части кода, посвященной обработке запросов на чтение:
```
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 Framework (WDF).
Используйте !rcdrkd.rcdrlogdump и !rcdrkd.rcdrcrashdump для просмотра сообщений, предоставляемых драйвером.
Используйте !wdfkd.wdflogdump или !wdfkd.wdfcrashdump , чтобы просмотреть сообщения, предоставляемые платформой.

Динамическое отладка драйвера UMDF

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

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

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

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

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

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

Включение отладки драйвера UMDF

Расширения RCDRKD

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

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

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

Использование средства записи трассировки inflight (IFR) в драйверах KMDF и UMDF 2

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

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

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

Использование средства записи трассировки inflight (IFR) в драйверах KMDF и UMDF 2

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

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

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