Uso del comprobador de controladores estático para buscar defectos en controladores de Windows

Artículo
07/03/2024

El comprobador de controladores estáticos (SDV) usa un conjunto de reglas de interfaz y un modelo del sistema operativo para determinar si el controlador interactúa correctamente con el sistema operativo Windows. SDV busca defectos en el código de controlador que podrían apuntar a posibles errores en los controladores.

SDV puede analizar controladores en modo kernel que se ajustan a uno de los siguientes modelos de controladores: WDM, KMDF, NDIS o Storport. Para obtener más información, consulte Controladores admitidos y Determinación de si el comprobador de controladores estáticos admite el controlador o la biblioteca. Además, SDV proporciona compatibilidad limitada (un conjunto de reglas gravemente restringido centrado en errores generales, como desreferencias null) para los controladores que no siguen los modelos de controladores anteriores.

Importante

SDV ya no es compatible y SDV no está disponible en las versiones de WDK o EWDK de Windows 24H2. No está disponible en WDK más reciente que la compilación 26017 y no se incluye en windows 24H2 RTM WDK. SDV todavía se puede usar descargando windows 11, versión 22H2 EWDK (publicada el 24 de octubre de 2023) con las herramientas de compilación de Visual Studio 17.1.5 desde Descargar el Kit de controladores de Windows (WDK). Solo se recomienda el uso de Enterprise WDK para ejecutar SDV. No se recomienda usar versiones anteriores del WDK estándar junto con las versiones recientes de Visual Studio, ya que esto probablemente provocará errores de análisis.
En el futuro, CodeQL será la herramienta de análisis estático principal para los controladores. CodeQL proporciona un lenguaje de consulta eficaz que trata el código como una base de datos que se va a consultar, lo que facilita la escritura de consultas para comportamientos, patrones y mucho más específicos. Para obtener más información sobre el uso de CodeQL, consulte CodeQL y la prueba de logotipo de herramientas estáticas.

Preparación del código fuente

Siga estos pasos para preparar el código para su análisis.

Declaración de funciones proporcionadas por controladores mediante tipos de rol de función

SDV requiere que las funciones se declaren mediante declaraciones de tipo de rol de función. Por ejemplo, una rutina DriverEntry debe declararse mediante el tipo de rol de función DRIVER_INITIALIZE:
```
DRIVER_INITIALIZE DriverEntry;
```
Después de la declaración, implemente (o defina) la rutina de devolución de llamada de la siguiente manera:
```
/
// Driver initialization routine
//
NTSTATUS
  DriverEntry(
    _In_ struct _DRIVER_OBJECT  *DriverObject,
    _In_ PUNICODE_STRING  RegistryPath
    )
  {
      // Function body
  }
```
Cada modelo de controlador compatible tiene un conjunto de tipos de roles de función para las funciones de devolución de llamada del controlador y las rutinas de envío. Estos tipos de rol de función se declaran en los archivos de encabezado WDK. Por ejemplo, este es el prototipo de función para el tipo de rol DRIVER_INITIALIZE tal como aparece en Wdm.h.
```
/
// Define driver initialization routine type.
//
_Function_class_(DRIVER_INITIALIZE)
_IRQL_requires_same_
typedef
NTSTATUS
DRIVER_INITIALIZE (
    _In_ struct _DRIVER_OBJECT *DriverObject,
    _In_ PUNICODE_STRING RegistryPath
    );

typedef DRIVER_INITIALIZE *PDRIVER_INITIALIZE;
```
Dado que los tipos de rol de función ya están definidos en los archivos de encabezado de WDK, solo es necesario declarar que las funciones de devolución de llamada sean de ese tipo. En este caso, declara que DriverEntry es de tipo DRIVER_INITIALIZE. Para obtener una lista completa de los tipos de roles de función para los modelos de controlador, consulte Using Function Role Type Declarations.

Ejecutar análisis de código para C/C++

Para ayudarle a determinar si el código fuente está preparado, ejecute la herramienta Análisis de código en Visual Studio. La herramienta Análisis de código comprueba si hay declaraciones de tipo de rol de función, lo que requiere SDV. La herramienta Análisis de código puede ayudar a identificar cualquier declaración de función que se haya perdido o advertirle cuando los parámetros de la definición de función no coincidan con los del tipo de rol de función.

Abra el proyecto de controlador en Visual Studio.
En el menú Compilar , haga clic en Ejecutar análisis de código en la solución.

Los resultados se muestran en la ventana Análisis de código. Corrija cualquier declaración de función que se haya perdido. También puede configurar la herramienta Análisis de código para que se ejecute cada vez que compile la solución.

En la tabla siguiente se muestran algunas de las advertencias que la herramienta Análisis de código puede encontrar en el código de controlador. Para ejecutar el comprobador de controladores estáticos, el controlador debe estar libre de estos defectos.

Análisis de código para advertencia de C/C++	Descripción
C28101	El módulo Controladores ha inferido que la función actual es una <función de tipo> función
C28022	Las clases de función de esta función no coinciden con las de la definición de tipo que se usa para definirlas.
C28023	La función que se asigna o se pasa debe tener una anotación de _Function_class_ para al menos una de las clases
C28024	El puntero de función al que se asigna tiene anotada la clase de función, que no está incluida en la lista de clases de función.
C28169	La función <> dispatch no tiene ninguna anotación de _Dispatch_type_
C28208	La firma de función no coincide con las declaraciones de función

Ejecución del comprobador de controladores estáticos

Abra el archivo del proyecto de controlador (.vcxProj) en Visual Studio. En el menú Controlador, haga clic en Iniciar comprobador de controladores estáticos....

Se abre la aplicación Comprobador de controladores estáticos, donde puede controlar, configurar y programar cuando el comprobador de controladores estáticos realiza un análisis.
Si el controlador incluye una biblioteca, haga clic en la pestaña Bibliotecas y haga clic en Agregar biblioteca para agregar la biblioteca.

Vaya al directorio del código fuente de la biblioteca y seleccione el archivo del proyecto (.vcxProj). Agregue todas las bibliotecas que incluye el controlador. Las bibliotecas deben agregarse antes de que SDV analice el controlador. Al iniciar un análisis del controlador, SDV también analiza las bibliotecas que no se han procesado. Una vez procesada una biblioteca, se almacena en la memoria caché global de SDV. Para obtener más información, consulte Procesamiento de bibliotecas en comprobador de controladores estáticos.
Compruebe los valores de configuración del Comprobador de controladores estáticos. Haga clic en la pestaña Configure .

Configuración del proyecto La configuración del proyecto muestra la configuración y la plataforma que seleccionó en Visual Studio.

Recursos En la mayoría de los casos, puede usar la configuración predeterminada. Si SDV notifica tiempo de espera, GiveUp o Spaceout, puede intentar ajustar esta configuración. Para obtener más información, consulte Recomendaciones para solucionar problemas del comprobador de controladores estáticos.

Programación Seleccione una hora de inicio para que comience la comprobación. La configuración predeterminada es comenzar el análisis inmediatamente después de hacer clic en Iniciar en la pestaña Principal . Según el tamaño del controlador y su complejidad, el análisis estático puede tardar mucho tiempo en ejecutarse. Es posible que quiera programar el análisis para comenzar cuando sea más conveniente para usted; por ejemplo, al final del día.

Nota:

Asegúrese de comprobar el plan de administración de energía del equipo para asegurarse de que el equipo no pasará a un estado de suspensión durante el análisis.
Haga clic en la pestaña Reglas para seleccionar qué reglas de uso de la API de controlador comprobará al iniciar el análisis.

El comprobador de controladores estáticos detecta el tipo de controlador que está analizando (WDF, WDM, NDIS o Storport) y selecciona el conjunto predeterminado de reglas para el tipo de controlador. Si es la primera vez que ejecuta SDV en el controlador, debe ejecutar el conjunto de reglas predeterminado.

Para obtener información sobre las reglas, consulte Reglas de cumplimiento de DDI.
Inicie el análisis estático. Haga clic en la pestaña Principal y haga clic en Inicio. Al hacer clic en Inicio, se muestra un mensaje para informarle de que el análisis estático está programado y que el análisis puede tardar mucho tiempo en ejecutarse. Haga clic en Aceptar para continuar. El análisis comienza en el momento programado.

Visualización y análisis de los resultados

A medida que continúa el análisis estático, SDV notifica el estado del análisis. Una vez completado el análisis, SDV notifica los resultados y las estadísticas. Si el controlador no cumple una regla de uso de API, el resultado se notifica como un defecto.

Si se encontraron problemas, SDV los muestra en las páginas Advertencias y Errores . En la página Propiedades del controlador se muestran los resultados de las pruebas de determinadas propiedades del controlador. Las pruebas de propiedades del controlador se usan para identificar las características del controlador para calificar aún más el análisis. Puede usar los resultados de las propiedades del controlador para confirmar las propiedades esperadas y las funcionalidades admitidas del controlador.

Para ver defectos específicos en el informe del comprobador de controladores estáticos, haga clic en el defecto en el panel Resultados. Se abre el Visor de seguimiento, que muestra un seguimiento de la ruta de acceso del código a la infracción de regla. Para obtener más información, consulte Interpretación de los resultados del comprobador de controladores estáticos.

Nota:

El comprobador de controladores estáticos conserva los resultados y la configuración del análisis. Para borrar los resultados, haga clic en Limpiar.

Solución de problemas de resultados del comprobador de controladores estáticos

Si SDV informa de que no se encontraron defectos, compruebe la pestaña Principal para asegurarse de que se detectan puntos de entrada. Si el controlador no declara funciones mediante los tipos de rol de función, SDV no podrá analizar y encontrar defectos en el código del controlador. Para obtener más información, consulte Using Function Role Type Declarations.

Si SDV notifica tiempos de espera o no devuelve resultados útiles, es posible que tenga que cambiar algunas opciones de configuración de SDV. Para obtener más información sobre cómo solucionar problemas de SDV, consulte Recomendaciones para solucionar problemas del comprobador de controladores estáticos.

Determinar si el comprobador de controladores estáticos admite el controlador o la biblioteca

Uso de declaraciones de tipo de rol de función

Reglas de comprobador de controladores estáticos

Herramienta de análisis de código