Compartir a través de

Validación de controladores de Windows

  • Artículo

Usa las herramientas InfVerif, comprobaciones de aislamiento de controlador del comprobador de controladores y ApiValidator para probar el paquete de controladores para saber si cumple con los requisitos de controladores de Windows que se describen en Introducción a los controladores de Windows.

InfVerif

InfVerif es una herramienta que valida la sintaxis del INF y comprueba si el INF cumple los requisitos y restricciones.

Use InfVerif con /w para comprobar que un controlador de Windows:

Para obtener más información, consulte Ejecución de InfVerif desde la línea de comandos.

InfVerif valida los requisitos de aislamiento de controladores con el argumento '/w', como se muestra aquí:

infverif.exe /w <INF file> [<INF file>]

Si InfVerif no notifica ningún error al validar con /w, significa que el INF cumple el requisito de aislamiento de paquetes de controladores de controladores de Windows.

Destino de las versiones actuales y anteriores de Windows

Si el INF contiene la sintaxis introducida en una versión reciente de Windows, como la directiva AddEventProvider de INF, que está disponible a partir de Windows 10 versión 1809, y también quiere tener como destino versiones anteriores de Windows, use decoraciones de INF para marcar entradas INF específicas de la versión. Para obtener código de ejemplo que muestra cómo usar las decoraciones de versiones del sistema operativo, consulte Combinación de extensiones de plataforma con versiones del sistema operativo.

Es posible que los archivos INF que usen decoraciones de versiones del sistema operativo produzcan errores en InfVerif, ya que puede que los requisitos de aislamiento de controladores no se admitan en las versiones anteriores de Windows. Para validar este tipo de INF, puede especificar la versión mínima de Windows en la que se deben aplicar comprobaciones de aislamiento de controladores mediante el argumento '/wbuild'. Por ejemplo, un archivo INF que usa la directiva AddEventProvider podría usar lo siguiente para aplicar solo comprobaciones de aislamiento de controladores a Windows 10 versión 1809 y posteriores:

infverif.exe /w /wbuild NTAMD64.10.0.0.17763 <INF file> [<INF file>]

Comprobaciones de aislamiento de controlador del comprobador de controladores

Para ser considerado controlador de Windows, un paquete de controladores debe cumplir los requisitos de aislamiento del paquete de controladores. A partir de Windows 11, el comprobador de controladores (DV) puede supervisar los archivos binarios del kernel para las lecturas y escrituras del Registro que no están permitidas para paquetes de controladores aislados.

Puede ver las infracciones a medida que se producen en un depurador de kernel o puede configurar DV para detener el sistema y generar un volcado de memoria con detalles cuando se produzca una infracción. Puede empezar a desarrollar el controlador con el primer método y cambiar al segundo cuando el controlador esté casi terminado.

Para ver las infracciones a medida que se producen, conecte primero un depurador de kernel y, a continuación, use los siguientes comandos. Una vez que un reinicio ha habilitado la configuración de DV, puede supervisar las infracciones en la salida del depurador de kernel.

Para habilitar las comprobaciones de aislamiento de controladores en un solo controlador:

verifier /rc 33 36 /driver myDriver.sys

Para comprobar más de un controlador, separe cada nombre de controlador con un espacio:

verifier /rc 33 36 /driver myDriver1.sys myDriver2.sys

Para configurar DV para comprobar errores cuando se produce una infracción, use la sintaxis siguiente:

verifier /onecheck /rc 33 36 /driver myDriver1.sys

Tendrá que reiniciar para habilitar la configuración de comprobación. Para ello, desde la línea de comandos, especifique:

shutdown /r /t 0

Estos son algunos ejemplos de mensajes de error:

Ejemplo: ZwCreateKey proporciona la ruta de acceso absoluta completa:

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should not use absolute paths. Detected creation of unisolated registry key \Registry\Machine\SYSTEM

Ejemplo: ZwCreateKey proporciona la ruta de acceso relativa a un identificador que no procede de una API aprobada:

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should only use key handles returned from WDF or WDM APIs. Detected creation of unisolated registry key \REGISTRY\MACHINE\SYSTEM\SomeKeyThatShouldNotExist

Considere la posibilidad de ejecutar pruebas de aspectos básicos del dispositivo con comprobaciones de aislamiento de controladores DV habilitadas en el controlador para ayudar a detectar las infracciones de aislamiento del controlador antes.

Controladores de KMDF

Cuando los controladores de KMDF usan las API de WDF para acceder al registro, como WdfRegistryCreateKey, WdfRegistryOpenKey o WdfRegistryQueryValue, el acceso al Registro se produce a través de wdf01000.sys en lugar de producirse mediante el archivo binario del controlador KMDF directamente. Para ver las infracciones causadas por el archivo binario del controlador KMDF, habilite las comprobaciones de aislamiento de controladores en wdf01000.sys, además del archivo binario del controlador KMDF. Tenga en cuenta que, al hacerlo, verá infracciones de todos los controladores KMDF del sistema que usan WDF para sus accesos al registro.

ApiValidator

La herramienta ApiValidator comprueba que las API a las que llaman los archivos binarios son válidas para un controlador de Windows. La herramienta devuelve un error si los archivos binarios llaman a una API que está fuera del conjunto de API válidas para controladores de Windows. Esta herramienta forma parte del WDK para Windows 10.

ApiValidator valida que un controlador admita capas de API, uno de los requisitos de los controladores de Windows. Para obtener una lista completa de los requisitos, consulte Introducción a los controladores de Windows.

Ejecución de ApiValidator en Visual Studio.

Si la propiedad Plataforma de destino del proyecto de controlador está establecida en Controlador de Windows, Visual Studio ejecuta ApiValidator automáticamente como un paso posterior a la compilación.

Para ver todos los mensajes que muestra ApiValidator, vaya a Herramientas->Opciones->Proyectos y soluciones->Compilación y ejecución y establezca Detalle de la salida de la compilación del proyecto de MSBuild en Detallado. Al compilar desde la línea de comandos, agregue el modificador /v:detailed o /v:diag al comando de compilación para aumentar el nivel de detalle.

En el ejemplo de controlador umdf2_fx2, los errores de validación de API tienen este aspecto:

Warning  1   warning : API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 2   warning : API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 3   warning : API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 4   warning : API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 5   warning : API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.  C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 6   warning : API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 7   warning : API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 8   warning : API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 9   warning : API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Error   10  error MSB3721: The command ""C:\Program Files (x86)\Windows Kits\10\bin\x64\ApiValidator.exe" -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug\\" -SupportedApiXmlFiles:"C:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x86\UniversalDDIs.xml" -ApiExtractorExePath:"C:\Program Files (x86)\Windows Kits\10\bin\x64"" exited with code -1.    C:\Program Files (x86)\Windows Kits\10\build\WindowsDriver.common.targets   1531    5   osrusbfx2um

Corrección de los errores de validación

  1. Si ha cambiado un proyecto de controlador UMDF de escritorio heredado a controlador de Windows, compruebe que incluye las bibliotecas correctas al compilar los archivos binarios. Seleccione y mantenga pulsado (o haga clic con el botón derecho) el proyecto y seleccione Propiedades. Vaya a Enlazador->Entrada. Las Dependencias adicionales deben contener:

    %AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib

    Para revisar otras opciones del enlazador para elegir como destino las SKU de OneCore, consulte Compilación para OneCore.

  2. Quite o reemplace las llamadas a la API que no están permitidas de una en una y vuelva a ejecutar la herramienta hasta que no haya errores.

  3. En algunos casos, puede reemplazar estas llamadas por DDI alternativas que aparecen en las páginas de referencia de la DDI de solo escritorio. Es posible que tenga que codificar una solución alternativa si no hay un reemplazo adecuado. Si es necesario, escriba un nuevo controlador de Windows a partir de las plantillas de controlador en WDK.

Si ve errores como los siguientes, consulte las instrucciones de Compilación para OneCore.

ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSEnumerateSessionsW' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSFreeMemory' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: NOT all binaries are Universal

Ejecución de ApiValidator desde el símbolo del sistema

También puede ejecutar Apivalidator.exe desde el símbolo del sistema. En la instalación de WDK, vaya a C:\Archivos de programa (x86)\Windows Kits\10\bin<arch> y C:\Archivos de programa (x86)\Windows Kits\10\build\universalDDIs<arch>.

Notas importantes:

  • ApiValidator requiere los siguientes archivos: ApiValidator.exe, Aitstatic.exe, Microsoft.Kits.Drivers.ApiValidator.dll y UniversalDDIs.xml.
  • El UniversalDDIs.xml debe coincidir con la arquitectura binaria que se valida; por ejemplo, para un controlador x64, use el UniversalDDI.xml x64.
  • ApiValidator solo prueba una arquitectura a la vez
  • Consulte Problemas conocidos de ApiValidator a continuación para obtener información adicional

Use la sintaxis siguiente:

Apivalidator.exe -DriverPackagePath: <driver folder path> -SupportedApiXmlFiles: (path to XML files containing supported APIs for Windows drivers)

Por ejemplo, para comprobar las API a las que llama el ejemplo de actividad en WDK, compile primero el ejemplo en Visual Studio. A continuación, abra un símbolo del sistema y vaya al directorio que contiene la herramienta, por ejemplo C:\Program Files (x86\Windows Kits\10\bin\x64. Escriba el comando siguiente:

apivalidator.exe -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2\_fx2\Debug" -SupportedApiXmlFiles:"c:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x64\UniversalDDIs.xml"

El comando genera el siguiente resultado:

ApiValidator.exe: Warning: API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API.

ApiValidator.exe Driver located at C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug is NOT a Universal Driver

Solución de problemas de ApiValidator

Si ApiValidator.exe genera un error de formato incorrecto, como el siguiente:

Error      1              error : AitStatic output file has incorrect format or analysis run on incorrect file types.     C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe            osrusbfx2um

Use esta solución alternativa:

  1. Abra las propiedades del proyecto, vaya a General y cambie el nombre del Directorio de salida por lo siguiente:

    $(SolutionDir)$(Platform)\$(ConfigurationName)\

  2. Compile la solución.

Problemas conocidos de ApiValidator

  • ApiValidator no se ejecuta en Arm64 porque AitStatic no funciona en Arm64.
  • Los archivos binarios arm64 se pueden probar en máquinas x64, pero no en una máquina x86.
  • ApiValidator se puede ejecutar en x86 para probar archivos binarios x86 y archivos binarios de Arm.
  • ApiValidator se puede ejecutar en x64 para probar archivos binarios x86, x64, Arm y Arm64.