Preprocesador de WPP

Artículo
06/15/2023

En esta sección se describe el preprocesador de seguimiento de software de Windows, conocido normalmente como preprocesador de WPP.

Invocación del preprocesador de WPP

Puede invocar el preprocesador de WPP mediante Visual Studio y el entorno de MSBuild.

Para invocar el preprocesador de WPP

Haga clic con el botón derecho en el proyecto de controlador en el Explorador de soluciones y haga clic en Propiedades.
En la página de propiedades del proyecto, haga clic en Propiedades de configuración y haga clic en Seguimiento de WPP.
En General, establezca la opción Ejecutar WPP en Sí.
En Línea de comandos, puede agregar opciones a continuación para personalizar el comportamiento de seguimiento.

Por ejemplo, en Seguimiento de WPP, puede especificar un único archivo de datos de configuración de examen.

Si necesita proporcionar más de un archivo de configuración, por ejemplo, para especificar tipos de datos personalizados, haga referencia al archivo en línea de comandos mediante la opción -scan , por ejemplo:
```
-scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"
```

Para obtener más información sobre el proceso de compilación, vea Tarea TraceWPP y WDK y entorno de compilación de Visual Studio.

También puede ejecutar el preprocesador independiente del entorno de compilación mediante la herramienta TraceWPP (TraceWPP.exe). Esta herramienta se encuentra en el subdirectorio bin/x86 del WDK.

Opciones generales de seguimiento de WPP

En las tablas siguientes se describen las opciones del preprocesador de WPP. Puede configurar estas opciones en Visual Studio mediante la página de propiedades Seguimiento de WPP para el proyecto o como parámetros en la herramienta TraceWPP.

Opción de seguimiento de WPP	Descripción
Ejecución de WPP	Si es true, invoca WPP.
Habilitar recompilación mínima	Si es true, se realiza una compilación incremental de seguimiento; si es false, se realiza una recompilación.

Opciones de función y macro

Opción de seguimiento de WPP	Opción de comando TraceWPP	Descripción
Definiciones de preprocesador	-D (macro)	Agrega #define Macro al principio del archivo generado donde Macro es el nombre de una macro. Esta opción tiene el mismo efecto que la opción del compilador /D (definir una macro). Se incluye para asegurarse de que las definas sean válidas al principio de los archivos TMH.
	-D Expansión demacros=	Agrega #define Expansión de macros al principio del archivo generado donde Macro es el nombre de una macro y Expansion es el valor expandido. Esta opción tiene el mismo efecto que la opción del compilador /D (definir una macro). Se incluye para asegurarse de que las definas sean válidas al principio de los archivos TMH.
Componentes del modo kernel de seguimiento	-Km	Define la macro WPP_KERNEL_MODE, que realiza un seguimiento de los componentes del modo kernel. De forma predeterminada, solo se realiza un seguimiento de los componentes en modo de usuario.
Habilitar macro dll	-Dll	Define la macro WPP_DLL, lo que hace que las estructuras de datos de WPP se inicialicen siempre que se llame a WPP_INIT_TRACING. De lo contrario, las estructuras solo se inicializan una vez.
Especificación del GUID de control	-ctl: GUID	Define una macro de WPP_CONTROL_GUIDS con el GUID de control especificado y WPP_DEFINE_BIT entradas denominadas Error, Inusual y Ruido. Esta es una alternativa a agregar la macro al archivo de origen. GUID representa el GUID de control.

Opciones de búsqueda y formato

Opción de seguimiento de WPP	Opción de comando TraceWPP	Descripción
Omitir signos de exclamación	-noshrieks	Dirige a WPP para omitir las signos de exclamación, también conocidos como "gritos". Se usa en formato complejo, como %!timestamp!%. De forma predeterminada, se requieren signos de exclamación y WPP intenta interpretarlos.
Base numérica para la numeración de cadenas de formato	-argbase: Número	Establece una base numérica para la numeración de cadenas de formato, como "%1!d!, %2!s!". El valor predeterminado es 1.
Función para generar mensajes de seguimiento	-func: FunctionDescription	Especifica alternativas a la macro DoTraceMessage. Estas funciones se pueden usar para generar mensajes de seguimiento. Por ejemplo, puede definir una función que especifique las marcas y el nivel de un mensaje de seguimiento, como: `-func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...)` Puede usar varias instancias de la opción -func . Esta opción es una alternativa a especificar descripciones de función en un archivo de configuración local.
Especificar cadena para buscar	-lookfor:String	Dirige a WPP a buscar los archivos de origen de la cadena especificada para iniciar el seguimiento. De forma predeterminada, WPP busca la cadena "WPP_INIT_TRACING". Esta es una opción avanzada para los usuarios que escriben sus propias plantillas. Por ejemplo, en default.tpl: `IF FOUND WPP_INIT_TRACING INCLUDE um-init.tpl ENDIF`
Especificar el nombre del módulo	-p: String	Especifica un nombre descriptivo alternativo para el GUID de mensaje de los mensajes de este proveedor de seguimiento. De forma predeterminada, el nombre descriptivo del GUID del mensaje es el nombre del directorio en el que se creó el proveedor de seguimiento. El nombre descriptivo del GUID del mensaje aparece, de forma predeterminada, en el prefijo del mensaje de seguimiento representado por la variable %1. Puede usar este parámetro para agregar una cadena al prefijo que ayuda al usuario a identificar el proveedor de seguimiento, como el nombre descriptivo del proveedor de seguimiento, el nombre del módulo que incluye el proveedor de seguimiento o el nombre de un proyecto que se implementa mediante la creación de varios proveedores de seguimiento. Esta información ayuda a los usuarios a asociar proveedores de seguimiento relacionados que se encuentran en archivos diferentes o rutas de acceso diferentes. El parámetro -p requiere la versión de WPP que se incluye en el Kit de controladores de Windows (WDK) para Windows Vista y versiones posteriores del WDK. El parámetro -p funciona en Windows 2000 y versiones posteriores de Windows. Ejemplos: `-p:TraceDrv -p:AudioModule`

Opciones de archivo

Opción de seguimiento de WPP	Opción de comando TraceWPP	Descripción
Directorios de inclusión adicionales	-I Path1[;Path2]	Especifica uno o más directorios que se agregarán a la ruta de acceso de inclusión; si hay más de uno, sepárelos mediante punto y coma. Igual que -cfgdir.
Directorios de configuración	-cfgdir: Path1[;Path2]	Especifica la ubicación de los archivos de configuración y plantilla. Path1 y Path2 representan la ruta de acceso completa a un directorio. Puede especificar varias rutas de acceso. El valor predeterminado es el directorio local.
Extensiones de archivo	-Ext:. ext1 [.ext2]	Especifica los tipos de archivo que WPP reconoce como archivos de origen. WPP omite los archivos con una extensión de nombre de archivo diferente. De forma predeterminada, WPP reconoce solo los archivos .c, .c++, .cpp y .cxx. Esta opción permite usar la configuración predeterminada para WPP sin tener que eliminar ni cambiar el nombre de los archivos de recursos que WPP no usa, como archivos .rc y .mc. Por ejemplo, para agregar seguimiento a archivos de C++ y archivos de encabezado (.h), use el siguiente comando: -ext:.cpp. CPP.h.H Además, para proporcionar los archivos TMH para los archivos de C++ y de encabezado diferentes nombres, use la opción -preserveext .
Conservar extensiones de archivo	-preserveext: .ext1[.ext2]	Conserva las extensiones de nombre de archivo especificadas al crear archivos TMH. De forma predeterminada, los archivos TMH para todos los tipos de archivo se denominan filename.tmh. Esto causó conflictos de nombre de archivo cuando tiene más de un archivo de origen con el mismo nombre. Por ejemplo, de forma predeterminada, los archivos TMH para los archivos C (.c) y los archivos de encabezado (.h) se denominarían <filename.tmh>. Con -preserveext:.c .h, los archivos TMH se denominan <filename.c.tmh y <filename.h.tmh>>.
Directorio de salida	-odir: ruta de acceso	Especifica el directorio de los archivos de salida que crea WPP. Path es la ruta de acceso completa al directorio. El valor predeterminado es el directorio local.
Especificar archivo de plantilla	-gen{ File.tpl }. ext	Para cada archivo de origen que WPP procesa con el nombre especificado entre llaves {}, cree otro archivo con la extensión de nombre de archivo especificada. File.tpl representa el archivo de origen. .ext representa el tipo de archivo que se crea y su extensión de nombre de archivo. Puede especificar varias opciones de generación* . Por ejemplo, -gen{mmm-default.tpl}.tmh significa que para cada archivo mmm-default.tpl que WPP procesa, genera un archivo mmm-default.tmh .
Examinar datos de configuración	-scan:File	Busca datos de configuración, como tipos de datos personalizados, en un archivo que no es un archivo de configuración, así como en defaultwpp.ini. Coloque begin_wpp config y end_wpp cadenas alrededor de los datos de configuración para identificarlos. Use el mismo formato para los datos de configuración que se usan en defaultwpp.ini. Si agregó los datos de configuración a un archivo de configuración personalizado, use el parámetro -ini .
Archivo de configuración alternativo	-defwpp:path	Especifica un archivo de configuración alternativo. Wpp usa este archivo en lugar del archivo defaultwpp.ini.
Archivo de configuración adicional	-ini:Path	Especifica un archivo de configuración adicional. WPP usa el archivo especificado además del archivo predeterminado, defaultwpp.ini. Use este parámetro cuando haya creado un nuevo archivo de configuración para almacenar los datos de configuración para el seguimiento. Si ha agregado los datos de configuración a otro tipo de archivo, como un archivo de origen o encabezado, use el parámetro -scan .

Proceso de compilación de WPP

Si WPP está habilitado para un controlador o una aplicación en modo de usuario, la compilación del controlador o la aplicación invoca el preprocesador wpP antes de compilar los archivos de controlador o aplicación.

El proceso de compilación de WPP completa los pasos siguientes:

El preprocesador wpP procesa macros de WPP en cada archivo de origen y crea un archivo de encabezado de mensaje de seguimiento para cada archivo de origen. El código fuente no se modifica directamente.
Después de que el preprocesador de WPP haya creado los archivos de encabezado del mensaje de seguimiento, el preprocesador de C procesa las macros de WPP integradas en los archivos de encabezado del mensaje de seguimiento de forma normal.

Compartir a través de