Compartir a través de

Uso del seguimiento de software de WPP en controladores UMDF

  • Artículo

El seguimiento de software de WPP le permite agregar mensajes de seguimiento que le ayudarán a depurar el controlador. Además, el registrador de eventos del marco proporciona cientos de mensajes de seguimiento que puede ver.

Puede ver los mensajes de seguimiento mediante TraceView o Tracelog. También puede enviar mensajes de seguimiento a un depurador de kernel.

Agregar mensajes de seguimiento al controlador

Para agregar mensajes de seguimiento al controlador basado en el marco, debe hacer lo siguiente:

  • Agregue una directiva #include a cada uno de los archivos de origen del controlador que contenga cualquiera de las macros de WPP. Esta directiva debe identificar un archivo de encabezado de mensaje de seguimiento (TMH). El nombre de archivo debe tener un formato <driver-source-file-name.tmh>.

    Por ejemplo, si el controlador consta de dos archivos de origen, denominados MyDriver1.c y MyDriver2.c, myDriver1.c debe contener:

    #include "MyDriver1.tmh"

    y MyDriver2.c deben contener:

    #include "MyDriver2.tmh"

    Al compilar el controlador en Microsoft Visual Studio, el preprocesador de WPP genera los archivos .tmh.

  • Defina una macro WPP_CONTROL_GUIDS en un archivo de encabezado. Esta macro define un GUID y marcas de seguimiento para los mensajes de seguimiento del controlador. (Para cada uno de los controladores de ejemplo basados en UMDF de WDK, el archivo de encabezado Internal.h incluye esta macro).

  • Incluya una macro de WPP_INIT_TRACING en la rutina DllMain del controlador. Esta macro activa el seguimiento de software en el controlador. (Para cada uno de los controladores de ejemplo basados en UMDF de WDK, el archivo de encabezado DllSup.h incluye esta macro).

  • Incluya una macro WPP_CLEANUP en la rutina DllMain del controlador. Esta macro desactiva el seguimiento de software en el controlador. (Para cada uno de los controladores de ejemplo basados en UMDF de WDK, el archivo de encabezado DllSup.h incluye esta macro).

  • Use la macro DoTraceMessage o una versión personalizada de la macro, en el controlador para crear mensajes de seguimiento. (Para cada uno de los controladores de ejemplo basados en UMDF de WDK, el archivo de encabezado Internal.h incluye una macro personalizada).

  • Abra las páginas de propiedades del proyecto de controlador. Haga clic con el botón derecho en el proyecto de controlador en Explorador de soluciones y seleccione Propiedades. En las páginas de propiedades del controlador, seleccione Propiedades de configuración y, a continuación, Wpp. En el menú General , establezca Ejecutar seguimiento de WPP en Sí. En el menú Opciones de archivo , también debe especificar el archivo de plantilla WPP del marco, por ejemplo:

    {km-WdfDefault.tpl}*.tmh

Para obtener más información sobre cómo agregar mensajes de seguimiento al controlador, vea Agregar macros de WPP a un controlador.

Controladores de ejemplo que usan el seguimiento de software de WPP

Todos los controladores de ejemplo basados en UMDF del WDK proporcionan archivos DllSup.h, Internal.h y Sources que habilitan el seguimiento de software de WPP. La mayoría de estos controladores de ejemplo también usan una macro personalizada para crear mensajes de seguimiento.

Visualización de los mensajes de seguimiento del controlador

Si ha agregado mensajes de seguimiento al controlador, el controlador es un proveedor de seguimiento. Puede usar un controlador de seguimiento, como Tracelog, para controlar una sesión de seguimiento y crear un registro de seguimiento. Puede usar un consumidor de seguimiento, como Tracefmt, para ver los mensajes.

Para obtener más información sobre cómo usar las herramientas de seguimiento de software, vea Survey of Software Tracing Tools.

Visualización del registro de seguimiento de UMDF

El archivo de registro de UMDF se encuentra en %ProgramData%*\\Microsoft\\WDF.

Puede ver el archivo de registro de UMDF mediante TraceView o Tracelog. Ambas herramientas requieren archivos de formato de mensaje de seguimiento (TMF) que formatearán los mensajes del registro de seguimiento. Los archivos TMF están disponibles en el WDK, en el subdirectorio \tools\tracing. (En TraceView, UMDF aparece como un proveedor con nombre con el nombre "UMDF-Framework Trace" o "Seguimiento del marco", según la versión de UMDF).

El comprobador de WDF le permite enviar mensajes de seguimiento tanto al registro de seguimiento de UMDF como al depurador de kernel. (No debe enviar mensajes de seguimiento al depurador de kernel mediante la opción -kd en Tracelog, ya que Tracelog puede interrumpir el registro de seguimiento dentro de UMDF).

También puede usar la extensión del depurador !wmitrace para ver los mensajes de seguimiento en el depurador:

  1. En WinDbg, adjunte a la instancia de WUDFHost que hospeda el controlador. Para obtener más información, vea Cómo habilitar la depuración de un controlador UMDF.

  2. Si el controlador usa la versión 1.11 o posterior, y usa el depurador de kernel de Windows 8 o posterior, puede omitir este paso. Si el controlador usa una versión de UMDF anterior a la 1.11, use !wmitrace.tmffile o !wmitrace.searchpath para especificar un archivo de formato de mensaje de seguimiento específico de la plataforma (.tmf) o una ruta de acceso a un archivo .tmf. Los archivos .tmf se encuentran en subdirectorios específicos de la plataforma en el WDK.

  3. Use el comando !wmitrace.logdump para mostrar el contenido de los búferes de seguimiento:

    !wmitrace.logdump WudfTrace

Control de mensajes de seguimiento

Puede controlar los mensajes de seguimiento de UMDF con la interfaz de usuario que proporciona el comprobador de WDF o modificando los valores del Registro. Debe usar la interfaz del comprobador de WDF siempre que sea posible, ya que los valores del Registro pueden cambiar en versiones futuras de UMDF. Además, no debe tener acceso a estos valores en archivos INF ni en el código del controlador.

Actualmente, puede modificar los siguientes valores del Registro, que se encuentran en la clave del Registro HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF :

  • El valor LogEnable controla si UMDF crea un registro de seguimiento para el controlador. Si este valor se establece en 1, UMDF crea un registro de seguimiento.

  • El valor logLevel controla la cantidad de información que contienen los mensajes de seguimiento de UMDF. El valor predeterminado de LogLevel es 3, lo que hace que los mensajes de seguimiento de UMDF contengan mensajes de error y advertencia. Establezca este valor en 7 para incluir mensajes de error y advertencia, además de mensajes informativos que no son de error. Establézcalo en 15 para incluir toda la información de seguimiento que UMDF puede proporcionar.

  • El valor LogKd controla si UMDF envía mensajes de seguimiento al depurador de kernel. Si LogKd está establecido en 1, UMDF envía sus mensajes de seguimiento al depurador de kernel.

  • El valor LogFlushPeriodSeconds especifica con qué frecuencia, en segundos, los mensajes de seguimiento se escriben en el registro de seguimiento.

  • El valor LogMinidumpType contiene marcas que especifican el tipo de información que contendrá un archivo de minivolcado, si se produce. Para obtener más información sobre estas marcas, vea la enumeración MINIDUMP_TYPE .

Puede encontrar más valores del Registro en la clave del Registro HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF . No debe modificar esos valores.