Validación de controladores de Windows

Artículo
08/19/2024

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 al desarrollo de 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:

Cumple el principio declarativo (D) de los Principios de diseño de DCH
Cumple con el requisito de aislamiento del paquete de controladores que se indica en Introducción al desarrollo de controladores 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 y el sistema de archivos que no están permitidas para paquetes de controladores aislados.

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

Para habilitar las comprobaciones de aislamiento de controladores para que se notifiquen mediante el depurador de kernel y el registro de eventos del sistema, pero no comprueben el sistema:

verifier /rc 33 36 /driver myDriver.sys [myDriver2.sys ...]

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

verifier /onecheck /rc 33 36 /driver myDriver1.sys [myDriver2.sys ...]

Independientemente del método de supervisión que elija, deberá 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 como se muestran en el depurador de kernel:

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.

Nota:

DV no quiere inundar a los usuarios con una gran cantidad de informes de la misma infracción, por lo que tiene un mecanismo de limitación donde puede limitar el informe de cada error único. A partir de Windows 11 24H2, para asegurarse de que ve el conjunto completo de infracciones de aislamiento de controladores para cualquier ejecución determinada de una prueba o serie de pruebas, puedes solicitar que se restablezca la limitación de infracciones de aislamiento de controladores mediante:

verifier /dif 33 /action 1

Si no lo hace antes de ejecutar una prueba, es posible que no vea determinadas infracciones durante la ejecución de las pruebas si esas infracciones ya se produjeron antes de que se iniciara la prueba.

Cumplimiento del WHCP

Actualmente, el programa Programa de compatibilidad de hardware con Windows (WHCP) no exige el aislamiento completo del paquete de controladores. Sin embargo, a partir de Windows 11 24H2, el programa WHCP comienza incluyendo los requisitos relacionados con el aislamiento de controladores. Para habilitar el mismo nivel de validación de aislamiento de paquetes de controladores que el Kit de laboratorio de hardware (HLK) hace como parte de la aplicación de los requisitos de WHCP, usaría la sintaxis siguiente:

Verifier /dif 33 /33 whcp /driver myDriver.sys [myDriver2.sys ...]

Al usar esta sintaxis, se notificarán todas las infracciones de aislamiento de controladores, pero las que no se aplican actualmente para el HLK se notificarán como advertencias en lugar de errores. Las enumeradas como advertencias no provocarán errores de HLK y no harán que el sistema compruebe si habilita las comprobaciones de aislamiento del controlador con /onecheck para que genere una comprobación de errores cuando se produzca una infracción.

Al ver eventos con un depurador de kernel, los que se consideran errores tendrán el prefijo DRIVER_ISOLATION_VIOLATION, mientras que los que sean advertencias tendrán el prefijo DRIVER_ISOLATION_WARNING.

Al ver eventos en el registro de eventos del sistema, los eventos con un atributo ErrorLevel se consideran errores y los eventos con otro valor ErrorLevel no se consideran errores. Consulte la sección "Visualización de infracciones en el registro de eventos del sistema" a continuación para obtener más información.

Visualización de infracciones en el registro de eventos del sistema

Las infracciones del comprobador de controladores se notifican en el registro de eventos del sistema de Microsoft-Windows-Kernel-XDV del proveedor y con un identificador de evento de "4". En Windows 11 24H2 y versiones posteriores, los eventos contendrán un valor ErrorLevel. Los eventos con un valor de ErrorLevel se consideran errores según el modo de aislamiento del controlador activo (cumplimiento de aislamiento de controladores completo frente al cumplimiento del aislamiento de WHCP) cuando se generó la infracción. Los eventos con otros valores ErrorLevel no se consideran errores. Por ejemplo, un evento con estos atributos se consideraría un error:

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should not use absolute paths. Detected opening of unisolated registry key \Registry\Machine\System\CurrentControlSet\Services\ExampleDriver\Parameters
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0x0

Mientras que un evento con estos atributos no se consideraría un error:

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should only use key handles returned from WDF or WDM APIs. Detected querying of value under unisolated registry key \REGISTRY\MACHINE\SYSTEM\ControlSet001\Control
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0xf4240

Si usa la aplicación Visor de eventos para ver el registro de eventos del sistema, puede filtrar la vista del registro mediante el menú del lado derecho de la aplicación haciendo clic en "Filtrar registro actual". En el cuadro de diálogo que aparece, si va a la pestaña XML y edita la consulta manualmente, puede usar esta consulta para filtrar el registro de eventos del sistema a solo infracciones de DV que deben considerarse un error:

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

Si desea filtrar la vista del registro de eventos a todas las infracciones de DV que se deben considerar un error después de un tiempo determinado (por ejemplo, después del momento en que se inició una prueba), puede hacer lo siguiente:

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime&gt;='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

O bien, si prefiere un archivo XML que puede cargar para su visualización, puede usar wevtutil para generar este tipo de XML en función de las mismas consultas:

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime>='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

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 al desarrollo de 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

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.
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.
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:

Abra las propiedades del proyecto, vaya a General y cambie el nombre del Directorio de salida por lo siguiente:
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
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.

Compartir a través de