Compartir a través de

Cómo escribir su primer controlador de cliente USB (KMDF)

  • Artículo

En este artículo usará la plantilla de controlador en modo kernel USB proporcionada con Microsoft Visual Studio para escribir un controlador cliente basado en el marco de controlador en modo kernel (KMDF) simple. Después de compilar e instalar el controlador cliente, verá el controlador cliente en Administrador de dispositivos y verá la salida del controlador en un depurador.

Para obtener una explicación sobre el código fuente generado por la plantilla, consulte Descripción del código de plantilla de KMDF para un controlador cliente USB.

Requisitos previos

Para desarrollar, depurar e instalar un controlador en modo kernel, necesita dos equipos:

  • Un equipo host que ejecute Windows 7 o una versión posterior del sistema operativo Windows. El equipo host es el entorno de desarrollo, donde escribe y depura el controlador.
  • Un equipo de destino que ejecute Windows Vista o una versión posterior de Windows. El equipo de destino tiene el controlador en modo kernel que desea depurar.

Antes de empezar, asegúrese de que cumple los siguientes requisitos:

Requisitos de software

  • El equipo host hospeda el entorno de desarrollo y tiene Visual Studio.
  • El equipo host tiene el Kit para controladores de Windows (WDK) más reciente. El kit incluye encabezados, bibliotecas, herramientas, documentación y las herramientas de depuración necesarias para desarrollar, compilar y depurar un controlador KMDF. Para obtener la versión más reciente del WDK, consulte Descarga del Kit para controladores de Windows (WDK).
  • El equipo host tiene la versión más reciente de las herramientas de depuración para Windows. Puede obtener la versión más reciente del WDK en Descarga e instalación de herramientas de depuración para Windows.
  • El equipo de destino ejecuta Windows Vista o una versión posterior de Windows.
  • Los equipos host y de destino están configurados para la depuración del kernel. Para obtener más información, consulte Configuración de una conexión de red en Visual Studio.

Requisitos de hardware

Obtenga un dispositivo USB para el que escribirá el controlador cliente. En la mayoría de los casos, se le proporciona un dispositivo USB y su especificación de hardware. La especificación describe las funcionalidades del dispositivo y los comandos de proveedor admitidos. Use la especificación para determinar la funcionalidad del controlador USB y las decisiones de diseño relacionadas.

Si no está familiarizado con el desarrollo de controladores USB, use el kit de aprendizaje OSR USB FX2 para consultar las muestras de USB incluidas con el WDK. Puede obtener el kit de aprendizaje de OSR Online. Contiene el dispositivo USB FX2 y todas las especificaciones de hardware necesarias para implementar un controlador cliente.

También puede obtener dispositivos de Microsoft USB Test Tool (MUTT). El hardware MUTT se puede comprar en JJG Technologies. El dispositivo no tiene instalado el firmware instalado. Para instalar el firmware, descargue el paquete de software MUTT de este sitio web y ejecute MUTTUtil.exe. Para obtener más información, consulte la documentación que se incluye con el paquete.

Paso 1: Generación del código del controlador KMDF mediante la plantilla de controlador USB de Visual Studio

Para obtener instrucciones sobre cómo generar código de controlador KMDF, consulte los pasos descritos en Escritura de un controlador KMDF basado en una plantilla.

Para código específico de USB, seleccione las opciones siguientes en Visual Studio:

  1. En el cuadro de diálogo Nuevo proyecto, en el cuadro de búsqueda de la parte superior, escriba USB.
  2. En el panel central, seleccione Controlador en modo kernel, USB (KMDF) .
  3. Seleccione Siguiente.
  4. Escriba un nombre de proyecto, elija una ubicación de guardado y seleccione Crear.

En las capturas de pantalla siguientes se muestra el cuadro de diálogo Nuevo proyecto para la plantilla Controlador en modo kernel USB.

opciones de nuevo proyecto de Visual Studio.

segunda pantalla de las opciones de nuevo proyecto de Visual Studio.

En este artículo se supone que el nombre del proyecto de Visual Studio es "MyUSBDriver_". Contiene los archivos siguientes:

Archivos Descripción
Public.h Proporciona declaraciones comunes compartidas por el controlador cliente y las aplicaciones de usuario que se comunican con el dispositivo USB.
<Nombre del proyecto>.inf Contiene información necesaria para instalar el controlador cliente en el equipo de destino.
Trace.h Declara funciones y macros de seguimiento.
Driver.h; Driver.c Declara y define los puntos de entrada del controlador y las rutinas de devolución de llamada de eventos.
Device.h; Device.c Declara y define la rutina de devolución de llamada de eventos para el evento prepare-hardware.
Queue.h; Queue.c Declara y define una rutina de devolución de llamada de evento para el evento generado por el objeto de cola del marco.

Paso 2: Modificación del archivo INF para agregar información sobre el dispositivo

Antes de compilar el controlador, debe modificar el archivo INF de plantilla con información sobre el dispositivo, específicamente la cadena de identificador de hardware.

En el Explorador de soluciones, en Archivos de controlador, haga doble clic en el archivo INF.

En el archivo INF puede proporcionar información como el nombre del fabricante y el proveedor, la clase de configuración del dispositivo, etc. Un fragmento de información que debe proporcionar es el identificador de hardware del dispositivo.

Para proporcionar la cadena de identificador de hardware:

  1. Conecte el dispositivo USB al equipo host y deje que Windows enumere el dispositivo.

  2. Abra el Administrador de dispositivos y abra las propiedades del dispositivo.

  3. En la pestaña Detalles, seleccione Identificadores de hardware en Propiedad.

    El identificador de hardware del dispositivo se muestra en el cuadro de lista. Mantenga pulsada (o haga clic con el botón derecho) la cadena de identificador de hardware y cópiela.

  4. Reemplace USB\VID_vvvv&PID_pppp en la siguiente línea por la cadena de ID de hardware.

    [Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp

Paso 3: Compilación del código del controlador cliente USB

Para compilar el controlador:

  1. Apertura del proyecto o la solución del controlador en Visual Studio
  2. Mantenga pulsada (o haga clic con el botón derecho) la solución en el Explorador de soluciones y seleccione Administrador de configuración.
  3. En Administrador de configuración, seleccione la Configuración de la solución activa (por ejemplo, Depuración o Versión) y la Plataforma de la solución activa (por ejemplo, Win32), que corresponden al tipo de compilación que le interesa.
  4. En el menú Compilar, seleccione Compilar solución.

Para obtener más información, consulte Compilación de un controlador.

Paso 4: Configuración de un equipo para probar y depurar

Para probar y depurar un controlador, ejecute el depurador en el equipo host y el controlador en el equipo de destino. Hasta ahora, ha usado Visual Studio en el equipo host para compilar un controlador. A continuación, debe configurar un equipo de destino. Para configurar un equipo de destino, siga las instrucciones de Aprovisionamiento de un equipo para la implementación y las pruebas de controladores.

Paso 5: Habilitación del seguimiento para la depuración de kernel

El código de plantilla contiene varios mensajes de seguimiento (TraceEvents) que pueden ayudarle a realizar un seguimiento de las llamadas de función. Todas las funciones del código fuente contienen mensajes de seguimiento que marcan la entrada y salida de una rutina. Para los errores, el mensaje de seguimiento contiene el código de error y una cadena significativa. Dado que el seguimiento de WPP está habilitado para el proyecto de controlador, el archivo de símbolos PDB creado durante el proceso de compilación contiene instrucciones de formato de mensaje de seguimiento. Si configura el equipo host y de destino para el seguimiento de WPP, el controlador puede enviar mensajes de seguimiento a un archivo o al depurador.

Para configurar el equipo host para el seguimiento de WPP:

  1. Cree archivos de formato de mensaje de seguimiento (TMF) mediante la extracción de instrucciones de formato de mensaje de seguimiento del archivo de símbolos PDB.

    Puede usar Tracepdb.exe para crear archivos TMF. La herramienta se encuentra en la <carpeta de instalación>Windows Kits\10.0\bin\<arquitectura> del WDK. El comando siguiente crea archivos TMF para el proyecto de controlador.

    tracepdb -f <PDBFiles> -p <TMFDirectory>

    La opción -f especifica la ubicación y el nombre del archivo de símbolos PDB. La opción -p especifica la ubicación de los archivos TMF creados por Tracepdb. Para obtener más información, consulte Comandos Tracepdb.

    En la ubicación especificada verá tres archivos (uno por archivo .c en el proyecto). Se les asignan nombres de archivo GUID.

  2. En el depurador, escriba los siguientes comandos:

    1. .load Wmitrace

      Carga la extensión Wmitrace.dll.

    2. .chain

      Comprueba que se carga la extensión del depurador.

    3. !wmitrace.searchpath +<Ubicación del archivo TMF>

      Agrega la ubicación de los archivos TMF a la ruta de búsqueda de la extensión del depurador.

      La salida será similar a esta:

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

Para configurar el equipo de destino para el seguimiento de WPP:

  1. Asegúrese de que tiene la herramienta Tracelog en el equipo de destino. La herramienta se encuentra en la <carpeta de instalación>Windows Kits\8.0\Tools\<arquitectura> del WDK. Para obtener más información, consulte Sintaxis del comando Tracelog.

  2. Abra una ventana del símbolo del sistema como administrador.

  3. Escriba el siguiente comando:

    tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

    El comando inicia una sesión de seguimiento denominada MyTrace.

    El argumento guid especifica el GUID del proveedor de seguimiento, que es el controlador cliente. Puede obtener el GUID de Trace.h en el proyecto de Visual Studio Professional 2019. Otra opción es escribir el siguiente comando y especificar el GUID en un archivo .guid. El archivo contiene el GUID en formato de guion:

    tracelog -start MyTrace -guid c:\drivers\Provider.guid -flag 0xFFFF -level 7-rt -kd

    Puede detener la sesión de seguimiento escribiendo el siguiente comando:

    tracelog -stop MyTrace

Paso 6: Implementación del controlador en el equipo de destino

  1. En el Explorador de soluciones, mantenga pulsado (o haga clic con el botón derecho) el *<nombre del proyecto>*Paquete y elija Propiedades.
  2. En el panel izquierdo, vaya a Propiedades de configuración> Instalación de controlador > Implementación.
  3. Active Habilitar implementación y active Importar en el almacén de controladores.
  4. En Nombre de equipo remoto, especifique el nombre del equipo de destino.
  5. Seleccione Instalar y comprobar.
  6. Seleccione Aceptar.
  7. En el menú Depurar, elija Iniciar depuración o pulse F5 en el teclado.

Nota:

No especifique el identificador de hardware del dispositivo en Actualización del controlador de ID de hardware. El identificador de hardware solo debe especificarse en el archivo de información del controlador (INF).

Para obtener más información sobre cómo implementar el controlador en el sistema de destino en Visual Studio, consulte Implementación de un controlador en un equipo de prueba.

También puede instalar manualmente el controlador en el equipo de destino mediante el Administrador de dispositivos. Si desea instalar el controlador desde un símbolo del sistema, estas utilidades están disponibles:

  • PnPUtil

    Esta herramienta viene con Windows. Está en Windows\System32. Puede usar esta utilidad para agregar el controlador al almacén de controladores.

    C:\>pnputil /a m:\MyDriver_.inf
Microsoft PnP Utility

Processing inf : MyDriver_.inf
Driver package added successfully.
Published name : oem22.inf

    Para obtener más información, consulte Ejemplos de PnPUtil.

  • DevCon Update

    Esta herramienta viene con el WDK. Puede usarla para instalar y actualizar controladores.

    devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6

Paso 7: Visualización del controlador en Administrador de dispositivos

  1. Escriba el siguiente comando para abrir el Administrador de dispositivos:

    devmgmt

  2. Compruebe que el Administrador de dispositivos muestra un nodo para el siguiente nodo:

    Muestras

    MyUSBDriver_Device

Paso 8: Visualización de la salida en el depurador

Visual Studio primero muestra el progreso en la ventana Salida. A continuación, abre la ventana Inmediato del depurador. Compruebe que los mensajes de seguimiento aparecen en el depurador en el equipo host. La salida debe parecerse a esta, donde "MyUSBDriver_" es el nombre del módulo de controlador:

[3]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverContextCleanup Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Exit
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Entry
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Exit