Использование средства записи трассировки (IFR) в драйверах KMDF и UMDF 2
Начиная с Windows 10, можно создать драйвер KMDF или UMDF, чтобы он получал дополнительные сведения об отладке драйверов с помощью предварительной обработки трассировки программного обеспечения Windows. Эта функция, называемая inflight Trace Recorder (IFR), доступна начиная с KMDF версии 1.15 и UMDF версии 2.15.
Inflight Trace Recorder является расширением программной трассировки WPP. В отличие от трассировки WPP, средство записи трассировки в полете продолжает работать без присоединенного потребителя трассировки. Платформа записывает сообщения в циклический буфер, и драйвер также может добавлять собственные сообщения. Каждый драйвер имеет собственный журнал, поэтому несколько устройств, связанных с драйвером, совместно используют один журнал.
Если включить IFR в двоичном файле драйвера, ТО IFR будет присутствовать и работать в течение всего времени существования драйвера. Вам не нужно запускать явный сеанс сбора данных трассировки.
Журналы хранятся в нестраничной памяти, поэтому их можно восстановить после сбоя системы. Кроме того, журналы средства записи трассировки при полете включаются в файлы minidump, за исключением случаев, когда не определен ответственный драйвер или если сбой был превышен.
Как включить inflight trace Recorder и отправлять сообщения из драйвера
В Microsoft Visual Studio выполните следующие действия.
Откройте страницы свойств для проекта драйвера. Щелкните правой кнопкой мыши проект драйвера в Обозреватель решений и выберите Свойства. На страницах свойств драйвера выберите Свойства конфигурации, а затем Трассировка Wpp. В меню Общие установите для параметра Запуск трассировки WPP значение Да.
Перейдите к свойствам Трассировка> Wpp и> Параметры макросов и выберите Включить запись WPP.
В том же меню задайте для параметра Проверить данные конфигурации файл, содержащий сведения о трассировки, например 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 для Kernel-Mode Drivers с объектом драйвера и путем в реестре, как правило, из DriverEntry:
WPP_INIT_TRACING( DriverObject, RegistryPath );Чтобы отключить трассировку, драйверы KMDF и UMDF 2 вызывают WPP_CLEANUP для Kernel-Mode Drivers из 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 в следующем расположении реестра:
SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<YourDriver>\Parameters\Wdf
<HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\YourDriver>\Parameters\Wdf
Это значение типа REG_DWORD , содержащее размер выделенного буфера журнала в страницах. Допустимые значения находятся в диапазоне от 0x1 до 0x10.
Для драйвера KMDF
- Загрузите команды RCDRKD, введя .load rcdrkd.dll в отладчике.
- Используйте расширение !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 — журналы платформы
Если для указанного драйвера нет журнала драйверов, расширение отображает только журнал платформы.
Просмотр журналов средства записи трассировки в полете после сбоя драйвера UMDF
В WinDbg выберите Файл Открыть> аварийный дамп и укажите файл минидампа, который требуется отладить.
Введите !wdfkd.wdfcrashdump <YourDriverName.dll><идентификатор процесса параметра> узла><драйвера, где <параметр> имеет значение:
- 0x1 — объединенные журналы платформы и драйверов
- 0x2 — журналы драйверов
- 0x3 — журналы платформы
Если драйвер не указан, !wdfcrashdump отображает сведения для всех драйверов. Если не указать хост-процесс, а есть только один, расширение использует процесс с одним узлом. Если не указать процесс узла, а их несколько, в расширении перечислены активные хост-процессы.
Если данные журнала, хранящиеся в минидампе, не совпадают с введенным именем, минидампа не содержит журналы драйвера.
Если у вас нет подключенного отладчика, вы по-прежнему можете получить доступ к журналам драйвера и платформы. Чтобы узнать, как это сделать, см. видео: доступ к журналам IFR драйвера без отладчика.
Дополнительные сведения о добавлении сообщений трассировки в драйвер см. в статье Добавление макросов WPP в драйвер.
Похожие статьи
Включение отладки драйвера UMDF
Использование средства ведения журнала событий платформы
Использование трассировки программного обеспечения WPP в драйверах UMDF
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по