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

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

Вы можете просматривать сообщения трассировки с помощью TraceView или tracelog. Вы также можете отправлять сообщения трассировки наотладчик ядра.

Добавление сообщений трассировки в драйвер

Чтобы добавить сообщения трассировки в драйвер, использующий фреймворк, необходимо:

• Добавьте директиву #include в каждый исходный файл драйвера, содержащий любой из макросов WPP. Эта директива должна определить файл заголовка сообщения трассировки (TMH) . Имя файла должно иметь формат <driver-source-file-name>.tmh.

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

  #include "MyDriver1.tmh"

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

  #include "MyDriver2.tmh"

  При сборке драйвера в Microsoft Visual Studio препроцессор WPP создает tmh-файлы.

• Определите макрос WPP_CONTROL_GUIDS в файле заголовка. Этот макрос определяет GUID и флаги трассировки для сообщений трассировки драйвера. (Для каждого из примеров драйверов на основе UMDF в WDK файл заголовка Internal.h включает этот макрос.)

• Включите макрос WPP_INIT_TRACING в подпрограмму DllMain драйвера. Этот макрос активирует трассировку программного обеспечения в драйвере. (Для каждого из примеров драйверов на основе UMDF в WDK файл заголовка DllSup.h включает этот макрос.)

• Включите макрос WPP_CLEANUP в функцию DllMain драйвера. Этот макрос деактивирует трассировку программного обеспечения в драйвере. (Для каждого из примеров драйверов на основе UMDF в WDK файл заголовка DllSup.h включает этот макрос.)

• Используйте макрос DoTraceMessage или его настраиваемую версию в драйвере для создания сообщений трассировки. (Для каждого из примеров драйверов на основе UMDF в WDK файл заголовка Internal.h включает настраиваемый макрос.)

• Откройте страницы свойств для проекта драйвера. Щелкните правой кнопкой мыши проект драйвера в обозревателе решений и выберите Свойства. На страницах свойств драйвера выберите свойства конфигурации, а затем Wpp. В меню Общие установите Выполнение трассировки WPP в положение "Да". В меню "Параметры файла" также следует указать файл шаблона WPP фреймворка, например:

  {km-WdfDefault.tpl}*.tmh
  

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

Примеры драйверов, использующих трассировку программного обеспечения WPP

Все примеры драйверов на основе UMDF в WDK предоставляют файлы DllSup.h, Internal.h и Sources, которые обеспечивают трассировку программного обеспечения WPP. Большинство из этих примеров драйверов также используют настраиваемый макрос для создания сообщений трассировки.

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

Если вы добавили сообщения трассировки в драйвер, драйвер выступает в роли поставщика трассировки. Можно использовать контроллер трассировки , например Tracelog , для управления сеансом трассировки и создания журнала трассировки . Для просмотра сообщений можно использовать потребитель трассировки, например, Tracefmt.

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

Просмотр журнала трассировки UMDF

Файл журнала UMDF находится в %ProgramData%*\\Microsoft\\WDF.

Файл журнала UMDF можно просмотреть с помощью TraceView или tracelog. Оба средства требуют файлов формата сообщений трассировки (TMF), которые форматируют сообщения журнала трассировки. Файлы TMF доступны в WDK в подкаталоге \tools\tracing. (В TraceView UMDF отображается как именованный поставщик с именем "UMDF-Framework trace" или "Framework Trace", в зависимости от версии UMDF.)

Верификатор WDF позволяет вам отправлять сообщения трассировки как в журнал трассировки UMDF, так и в отладчик ядра. (Не следует отправлять сообщения трассировки в отладчик ядра, используя параметр -kd в Tracelog, потому что Tracelog может нарушить ведение журнала трассировки в UMDF.)

Можно также использовать расширение отладчика !wmitrace для просмотра сообщений трассировки в отладчике:

1. В WinDbg подключитесь к экземпляру WUDFHost, на котором размещен драйвер. Для получения дополнительных сведений см. раздел Как включить отладку драйвера UMDF.

2. Если драйвер использует версию 1.11 или более поздней версии, и вы используете отладчик ядра из Windows 8 или более поздней версии, этот шаг можно пропустить. Если драйвер использует версию UMDF ранее 1.11, используйте !wmitrace.tmffile или !wmitrace.searchpath, чтобы указать файл сообщения трассировки для конкретной платформы (.tmf) или путь к tmf-файлу. Файлы TMF находятся в подкаталогах для конкретной платформы в WDK.

3. Используйте команду !wmitrace.logdump, чтобы отобразить содержимое буферов трассировки:

   !wmitrace.logdump WudfTrace
   

Управление сообщениями трассировки

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

В настоящее время можно изменить следующие значения реестра, расположенные в разделе реестра HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF:

• Значение LogEnable определяет, будет ли UMDF создавать журнал трассировки для вашего драйвера. Если для этого значения задано значение 1, UMDF создает журнал трассировки.

• Значение LogLevel определяет объем сведений, содержащихся в сообщениях трассировки UMDF. Значение по умолчанию для LogLevel равно 3, что приводит к тому, что сообщения трассировки UMDF содержат сообщения об ошибках и предупреждениях. Задайте для этого значения значение 7, чтобы включить сообщения об ошибках и предупреждения, а также информационные сообщения без ошибок. Задайте для него значение 15, чтобы включить все сведения трассировки, которые UMDF может предоставлять.

• Значение LogKd определяет, отправляет ли UMDF трассировочные сообщения в отладчик ядра. Если LogKd имеет значение 1, UMDF отправляет сообщения трассировки в отладчик ядра.

• Значение LogFlushPeriodSeconds указывает, как часто (в секундах) сообщения трассировки записываются в журнал трассировки.

• Значение LogMinidumpType содержит флаги, указывающие тип сведений, которые будет содержать файл мини-дампа, если он будет создан. Дополнительные сведения об этих флагах см. в перечислении MINIDUMP_TYPE.

Дополнительные значения можно найти в разделе реестра HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF. Эти значения не следует изменять.