Compartir a través de

Escribir un controlador universal de Windows (KMDF) basado en una plantilla

  • Artículo

En este tema se describe cómo escribir un controlador universal de Windows mediante Kernel-Mode Driver Framework (KMDF). Comenzará con una plantilla de Microsoft Visual Studio y, a continuación, implementará e instalará el controlador en un equipo independiente.

Antes de continuar, deberá seguir los pasos de instalación que se indican en Descargar el Kit de controladores de Windows (WDK).

Las herramientas de depuración para Windows se incluyen al instalar el WDK.

Creación y compilación de un controlador

  1. Abra Microsoft Visual Studio. En el menú Archivo , elija Nuevo > proyecto.

  2. En el cuadro de diálogo Crear un proyecto , seleccione C++ en la lista desplegable de la izquierda, elija Windows en la lista desplegable central y elija Controlador en la lista desplegable derecha.

  3. Seleccione Controlador de modo kernel (KMDF) en la lista de tipos de proyecto. Seleccione Next (Siguiente).

    Captura de pantalla del cuadro de diálogo nuevo proyecto, que muestra el controlador de modo kernel seleccionado.

  4. En el cuadro de diálogo Configurar el nuevo proyecto , escriba "KmdfDriver" en el campo Nombre del proyecto.

    Nota

    Al crear un nuevo controlador KMDF o UMDF, debe seleccionar un nombre de controlador que tenga 32 caracteres o menos. Este límite de longitud se define en wdfglobals.h.  

  5. En el campo Ubicación , escriba el directorio donde desea crear el nuevo proyecto.

  6. Active Colocar solución y proyecto en el mismo directorio y seleccione Crear.

    Captura de pantalla del cuadro de diálogo de configuración del proyecto.

    Visual Studio crea un proyecto y una solución. Puede verlos en la ventana Explorador de soluciones. (Si la ventana Explorador de soluciones no está visible, elija Explorador de soluciones en el menú Ver). La solución tiene un proyecto de controlador denominado KmdfDriver. Para ver el código fuente del controlador, abra cualquiera de los archivos en Archivos de código fuente. Driver.c y Device.c son buenos lugares para empezar.

    Captura de pantalla del Explorador de soluciones que muestra los archivos en el proyecto de controlador.

  7. En la ventana Explorador de soluciones, seleccione y mantenga pulsado (o haga clic con el botón derecho) KmdfDriver y elija Propiedades. Vaya a Configuración de propiedades de configuración Driver Settings General (Configuración general del controlador de > propiedades > de configuración) y tenga en cuenta que el valor predeterminado de la plataforma de destino es Universal.

  8. Para compilar el controlador, elija Compilar solución en el menú Compilar . Microsoft Visual Studio muestra el progreso de la compilación en la ventana Salida . (Si la ventana Salida no está visible, elija Salida en el menú Ver ).

    Compruebe que la salida de la compilación incluye:

    >    Driver is 'Universal'.

    Cuando haya comprobado que la solución se ha compilado correctamente, puede cerrar Visual Studio.

  9. Para ver el controlador compilado, en Explorador de archivos, vaya a la carpeta KmdfDriver y, a continuación, a x64\Debug\KmdfDriver. El directorio incluye los siguientes archivos:

    • KmdfDriver.sys: el archivo de controlador en modo kernel
    • KmdfDriver.inf: un archivo de información que Windows usa al instalar el controlador.

Implementación del controlador

Normalmente, al probar y depurar un controlador, el depurador y el controlador se ejecutan en equipos independientes. El equipo que ejecuta el depurador se denomina equipo host y el equipo que ejecuta el controlador se denomina equipo de destino. El equipo de destino también se denomina equipo de prueba. Para obtener más información sobre los controladores de depuración, vea Herramientas de depuración para Windows.

Hasta ahora ha usado Visual Studio para compilar un controlador en el equipo host. Ahora debe configurar un equipo de destino.

  1. Siga las instrucciones de Aprovisionamiento de un equipo para la implementación y pruebas de controladores (WDK 10).

    Sugerencia

    Cuando siga los pasos para aprovisionar el equipo de destino automáticamente mediante un cable de red, anote el puerto y la clave. Los usará más adelante en el paso de depuración. En este ejemplo, usaremos 50000 como puerto y 1.2.3.4 como clave.

    En escenarios de depuración de controladores reales, se recomienda usar una clave generada por KDNET. Para obtener más información sobre cómo usar KDNET para generar una clave aleatoria, consulte el tema Controladores de depuración: laboratorio paso a paso (modo kernel sysvad).

  2. En el equipo host, abra la solución en Visual Studio. Puede hacer doble clic en el archivo de solución, KmdfDriver.sln, en la carpeta KmdfDriver.

  3. En la ventana Explorador de soluciones, seleccione y mantenga presionado (o haga clic con el botón derecho) en el proyecto KmdfDriver y elija Propiedades.

  4. En la ventana Páginas de propiedades del paquete KmdfDriver , en el panel izquierdo, vaya a Configuración Propiedades > del controlador Instalar > implementación.

  5. Active Quitar versiones anteriores del controlador antes de la implementación.

  6. En Nombre de equipo remoto, seleccione el nombre del equipo que configuró para probar y depurar. En este ejercicio, usamos un equipo denominado MyTestComputer.

  7. Seleccione Actualización del controlador de id. de hardware y escriba el identificador de hardware del controlador. En este ejercicio, el identificador de hardware es Root\KmdfDriver. Seleccione Aceptar.

    captura de pantalla de la ventana de páginas de propiedades del paquete kmdfdriver, en la que se muestra la instalación del controlador de implementación seleccionada

    Nota

    En este ejercicio, el identificador de hardware no identifica un elemento real de hardware. Identifica un dispositivo imaginario que se asignará a un lugar en el árbol de dispositivos como elemento secundario del nodo raíz. Para hardware real, no seleccione Hardware ID Driver Update; en su lugar, seleccione Instalar y comprobar. Verá el identificador de hardware en el archivo de información del controlador (INF). En la ventana Explorador de soluciones, vaya a KmdfDriver Driver Files (Archivos de controlador kmdfDriver>) y haga doble clic en KmdfDriver.inf. El identificador de hardware se encuentra en [Standard.NT$ARCH$].

    [Standard.NT$ARCH$]
%KmdfDriver.DeviceDesc%=KmdfDriver_Device, Root\KmdfDriver

  8. En el menú Compilar , elija Implementar solución. Visual Studio copia automáticamente los archivos necesarios para instalar y ejecutar el controlador en el equipo de destino. Esto puede tardar un par de minutos.

    Al implementar un controlador, los archivos de controlador se copian en la carpeta %Systemdrive%\drivertest\drivers del equipo de prueba. Si algo va mal durante la implementación, puede comprobar si los archivos se copian en el equipo de prueba. Compruebe que los archivos .inf, .cat, test cert y .sys, y cualquier otro archivo necesario, estén presentes en la carpeta %systemdrive%\drivertest\drivers.

    Para obtener más información sobre la implementación de controladores, vea Deploying a Driver to a Test Computer.

Instalación del controlador

Con el controlador KMDF implementado en el equipo de destino, ahora instalará el controlador. Cuando aprovisionó previamente el equipo de destino con Visual Studio con la opción automática , Visual Studio configuró el equipo de destino para ejecutar controladores firmados de prueba como parte del proceso de aprovisionamiento. Ahora solo tiene que instalar el controlador mediante la herramienta DevCon.

  1. En el equipo host, vaya a la carpeta Herramientas de la instalación de WDK y busque la herramienta DevCon. Por ejemplo, busque en la carpeta siguiente:

    C:\Archivos de programa (x86)\Windows Kits\10\Tools\x64\devcon.exe

    Copie la herramienta DevCon en el equipo remoto.

  2. En el equipo de destino, instale el controlador; para ello, vaya a la carpeta que contiene los archivos de controlador y ejecute la herramienta DevCon.

    1. Esta es la sintaxis general de la herramienta devcon que usará para instalar el controlador:

      devcon install <INF file><hardware ID>

      El archivo INF necesario para instalar este controlador es KmdfDriver.inf. El archivo INF contiene el identificador de hardware para instalar el archivo binario del controlador, KmdfDriver.sys. Recuerde que el identificador de hardware, ubicado en el archivo INF, es Root\KmdfDriver.

    2. Abra una ventana del símbolo del sistema como administrador. Vaya a la carpeta del paquete de controladores y escriba este comando:

      devcon install kmdfdriver.inf root\kmdfdriver

      Si recibe un mensaje de error sobre devcon que no se reconoce, intente agregar la ruta de acceso a la herramienta devcon . Por ejemplo, si la copió en una carpeta del equipo de destino denominada C:\Tools, pruebe a usar el siguiente comando:

      c:\tools\devcon install kmdfdriver.inf root\kmdfdriver

      Aparecerá un cuadro de diálogo que indica que el controlador de prueba es un controlador sin firmar. Seleccione Instalar este controlador de todos modos para continuar.

      Captura de pantalla de la advertencia de instalación del controlador.

Depuración del controlador

Ahora que ha instalado el controlador KMDF en el equipo de destino, asociará un depurador de forma remota desde el equipo host.

  1. En el equipo host, abra una ventana del símbolo del sistema como administrador. Cambie al directorio WinDbg.exe. Usaremos la x64version de WinDbg.exe del Kit de controladores de Windows (WDK) que se instaló como parte de la instalación del kit de Windows. Esta es la ruta de acceso predeterminada a WinDbg.exe:

    C:\Archivos de programa (x86)\Windows Kits\10\Debuggers\x64

  2. Inicie WinDbg para conectarse a una sesión de depuración del kernel en el equipo de destino mediante el siguiente comando. El valor del puerto y la clave deben ser los mismos que los que usó para aprovisionar el equipo de destino. Usaremos 50000 para el puerto y 1.2.3.4 para la clave, los valores que usamos durante el paso de implementación. La marca k indica que se trata de una sesión de depuración del kernel.

    WinDbg -k net:port=50000,key=1.2.3.4

  3. En el menú Depurar , elija Interrumpir. El depurador del equipo host se dividirá en el equipo de destino. En la ventana Comando del depurador , puede ver el símbolo del sistema de depuración del kernel: kd>.

  4. En este momento, puede experimentar con el depurador escribiendo comandos en el símbolo del sistema kd> . Por ejemplo, podría probar estos comandos:

  5. Para permitir que el equipo de destino vuelva a ejecutarse, elija Ir en el menú Depurar o presione "g" y presione "entrar".

  6. Para detener la sesión de depuración, elija Desasociar depurado en el menú Depurar .

    Importante

    Asegúrese de usar el comando "go" para permitir que el equipo de destino vuelva a ejecutarse antes de salir del depurador, o el equipo de destino seguirá sin responder a la entrada del mouse y del teclado porque sigue hablando con el depurador.

Para obtener un tutorial detallado paso a paso del proceso de depuración de controladores, consulte Depuración de controladores universales: laboratorio paso a paso (modo kernel de eco) .

Para obtener más información sobre la depuración remota, vea Depuración remota mediante WinDbg.

Uso de Driver Module Framework (DMF)

Driver Module Framework (DMF) es una extensión de WDF que permite una funcionalidad adicional para un desarrollador de controladores WDF. Ayuda a los desarrolladores a escribir cualquier tipo de controlador WDF mejor y más rápido.

DMF como marco permite la creación de objetos WDF denominados módulos DMF. El código de estos módulos DMF se puede compartir entre distintos controladores. Además, DMF agrupa una biblioteca de módulos DMF que hemos desarrollado para nuestros controladores y se siente que proporcionaría valor a otros desarrolladores de controladores.

DMF no reemplaza WDF. DMF es un segundo marco que se usa con WDF. El desarrollador que aprovecha DMF sigue usando WDF y todos sus primitivos para escribir controladores de dispositivo.

Para obtener más información, consulte Marco de módulo de controladores (DMF).