Препроцессор WPP
В этом разделе описывается препроцессор трассировки программного обеспечения Windows, известный как препроцессор WPP.
Вызов препроцессора WPP
Вы можете вызвать препроцессор WPP с помощью Visual Studio и среды MSBuild.
Вызов препроцессора WPP
Щелкните правой кнопкой мыши проект драйвера в обозревателе решений и выберите пункт "Свойства".
На странице свойств проекта щелкните "Свойства конфигурации" и щелкните " Трассировка WPP"
В разделе "Общие" задайте для параметра Run WPP значение "Да".
В командной строке можно добавить параметры ниже, чтобы настроить поведение трассировки.
Например, в разделе трассировки WPP можно указать один файл данных конфигурации сканирования.
Если необходимо указать несколько файлов конфигурации, например, чтобы указать пользовательские типы данных, наведите ссылку на файл в командной строке с помощью параметра -scan, например:
-scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
Дополнительные сведения о процессе сборки см. в разделе "Задача TraceWPP" и среда сборки WDK и Visual Studio.
Вы также можете запустить препроцессор отдельно от среды сборки с помощью средства TraceWPP (TraceWPP.exe). Это средство находится в подкаталоге bin/x86 WDK.
Общие параметры трассировки WPP
В следующих таблицах описаны параметры препроцессора WPP. Эти параметры можно настроить в Visual Studio с помощью страницы свойств трассировки WPP для проекта или в качестве параметров в средстве TraceWPP.
| Параметр трассировки WPP | Description |
|---|---|
Запуск WPP |
Если значение true, вызывает WPP. |
Включение минимального перестроения |
Если значение true, выполняется отслеживаемая добавочная сборка; Значение false, выполняется перестроение. |
Параметры функции и макроса
| Параметр трассировки WPP | Параметр команды TraceWPP | Description |
|---|---|---|
Определения препроцессора |
-DМакрос |
Добавляет #define макрос в начало созданного файла, где макрос — имя макроса. Этот параметр имеет тот же эффект, что и параметр компилятора /D (определение макроса). Он включается для обеспечения допустимости определений в начале файлов TMH. |
Расширение макроса=-D |
Добавляет #define расширение макросов в начало созданного файла, где макрос — имя макроса и расширение — это развернутое значение. Этот параметр имеет тот же эффект, что и параметр компилятора /D (определение макроса). Он включается для обеспечения допустимости определений в начале файлов TMH. |
|
Компоненты режима трассировки ядра |
-км |
Определяет макрос WPP_KERNEL_MODE, который отслеживает компоненты режима ядра. По умолчанию трассируются только компоненты пользовательского режима. |
Включение макроса DLL |
-библиотека dll |
Определяет макрос WPP_DLL, который приводит к инициализации структур данных WPP при вызове WPP_INIT_TRACING. В противном случае структуры инициализированы только один раз. |
Указание GUID элемента управления |
-ctl: GUID |
Определяет макрос WPP_CONTROL_GUIDS с указанным GUID элемента управления и WPP_DEFINE_BIT записи с именем Error, Unusual и Noise.
Это альтернатива добавлению макроса в исходный файл. GUID представляет guid элемента управления. |
Параметры поиска и форматирования
| Параметр трассировки WPP | Параметр команды TraceWPP | Description |
|---|---|---|
Игнорировать восклицательные знаки |
-noshrieks |
Направляет WPP игнорировать восклицательные знаки, также известные как "креветки". Используется в сложном форматировании, например %!timestamp!%. По умолчанию восклицательные знаки требуются, и WPP пытается интерпретировать их. |
Числовая база для нумерирования строк форматирования |
-argbase: Number |
Устанавливает числовую базу для нумерирования строк формата, таких как "%1!d!, %2!s!". Значение по умолчанию — 1. |
Функция для создания сообщений трассировки |
-func: FunctionDescription |
Задает альтернативные варианты макроса DoTraceMessage . Затем эти функции можно использовать для создания сообщений трассировки. Например, можно определить функцию, указывающую флаги и уровень для сообщения трассировки, например: Можно использовать несколько экземпляров параметра -func . Этот параметр является альтернативой указанию описаний функций в локальном файле конфигурации. |
Указание строки для поиска |
-lookfor:String |
Направляет WPP на поиск исходных файлов для указанной строки, чтобы инициировать трассировку. По умолчанию WPP ищет строку "WPP_INIT_TRACING". Это расширенный вариант для пользователей, которые пишут собственные шаблоны. Например, в default.tpl: |
Указание имени модуля |
-p: Строка |
Задает альтернативное понятное имя для GUID сообщения из этого поставщика трассировки. По умолчанию понятное имя GUID сообщения — это имя каталога, в котором был создан поставщик трассировки. Понятное имя GUID сообщения по умолчанию отображается в префиксе сообщения трассировки, представленном переменной % 1. Этот параметр можно использовать для добавления строки в префикс, который помогает пользователю определить поставщика трассировки, например понятное имя поставщика трассировки, имя модуля, включающего поставщика трассировки, или имя проекта, реализуемого путем создания нескольких поставщиков трассировки. Эта информация помогает пользователям связывать связанные поставщики трассировки, которые находятся в разных файлах или различных путях. Для параметра -p требуется версия WPP, включенная в комплект драйверов Windows (WDK) для Windows Vista и более поздних версий WDK. Параметр -p работает в Windows 2000 и более поздних версиях Windows. Примеры: |
Параметры файла
| Параметр трассировки WPP | Параметр команды TraceWPP | Description |
|---|---|---|
Дополнительные каталоги включаемых файлов |
-I Path1[;Path2] |
Задает один или несколько каталогов для добавления в качестве пути включения; несколько значений разделяются точками с запятой. То же, что и -cfgdir. |
Каталоги конфигурации |
-cfgdir: Path1[;Path2] |
Указывает расположение файлов конфигурации и шаблонов. Path1 и Path2 представляют полный путь к каталогу. Можно указать несколько путей. По умолчанию используется локальный каталог. |
Расширения файлов |
-ext:. ext1 [.ext2] |
Указывает типы файлов, которые WPP распознает как исходные файлы. WPP игнорирует файлы с другим расширением имени файла. По умолчанию WPP распознает только C, C++, .cpp и CXX-файлы. Этот параметр позволяет использовать параметры по умолчанию для WPP, не удаляя или переименовывая файлы ресурсов, которые WPP не использует, например RC и MC-файлы. Например, чтобы добавить трассировку в файлы C++ и файлы заголовка (H), используйте следующую команду: -ext:.cpp. CPP.h.H Кроме того, чтобы предоставить файлы TMH для файлов C++ и заголовков, используйте параметр -preserveext . |
Сохранение расширений файлов |
-preserveext: .ext1[.ext2] |
Сохраняет указанные расширения имен файлов при создании файлов TMH. По умолчанию TMH-файлы для всех типов файлов называются filename.tmh. Это вызвало конфликты имен файлов при наличии нескольких исходных файлов с одинаковым именем. Например, по умолчанию файлы TMH для файлов C (C) и заголовка (H) будут называться <filename.tmh>. С помощью -preserveext:.c .h файлы TMH называются <filename.c.c.tmh> и <filename.h.tmh>. |
Выходной каталог |
-odir: путь | Указывает каталог для выходных файлов, создаваемых WPP. Путь — это полный путь к каталогу. По умолчанию используется локальный каталог. |
Указание файла шаблона |
-gen{ File.tpl }. ext |
Для каждого исходного файла, который WPP обрабатывает с именем, указанным между фигурными скобками {}, создайте другой файл с указанным расширением имени файла. File.tpl представляет исходный файл. *.ext представляет тип создаваемого файла и его расширение имени файла. Можно указать несколько параметров поколения . Например, -gen{um-default.tpl}.tmh означает, что для каждого файла um-default.tpl , который обрабатывает WPP, он создает файл um-default.tmh . |
Сканирование данных конфигурации |
-scan:File |
Выполняет поиск данных конфигурации, таких как пользовательские типы данных, в файле, который не является файлом конфигурации, а также в defaultwpp.ini. Поместите begin_wpp конфигурацию и end_wpp строки вокруг данных конфигурации для его идентификации. Используйте тот же формат для данных конфигурации, что и в defaultwpp.ini. Если вы добавили данные конфигурации в пользовательский файл конфигурации, используйте параметр -ini . |
Альтернативный файл конфигурации |
-defwpp:path |
Указывает альтернативный файл конфигурации. Wpp использует этот файл вместо файла defaultwpp.ini. |
Дополнительный файл конфигурации |
-ini:Path |
Указывает дополнительный файл конфигурации. WPP использует указанный файл в дополнение к файлу по умолчанию defaultwpp.ini. Используйте этот параметр при создании нового файла конфигурации для хранения данных конфигурации для трассировки. Если вы добавили данные конфигурации в другой тип файла, например исходный или заголовок, используйте параметр -scan . |
Процесс сборки WPP
Если WPP включен для приложения драйвера или пользовательского режима, создание драйвера или приложения вызывает препроцессор WPP перед компиляцией файлов драйверов или приложений.
Процесс сборки WPP выполняет следующие действия.
Препроцессор WPP обрабатывает макросы WPP в каждом исходном файле и создает файл заголовка сообщения трассировки для каждого исходного файла. Исходный код не изменяется напрямую.
После того как препроцессор WPP создал файлы заголовков сообщений трассировки, препроцессор C обрабатывает встроенные макросы WPP в файлах заголовков сообщений трассировки обычным образом.