Compartir a través de

Compilación de un controlador WDF para varias versiones de Windows

  • Artículo

WDF siempre le ha permitido compilar un controlador una vez y usar el binario resultante en varias versiones de Windows, pero antes de Windows 10 versión 1803 (Redstone 4), esto se limitaba a "compilar en versiones anteriores, ejecutarse en versiones más recientes". A partir de Windows 10 versión 1803, WDF agrega "compilación sobre versiones más recientes y ejecutadas en versiones anteriores", con la ventaja adicional de la ejecución condicional. En resumen:

  • Existente: los archivos binarios compilados con versiones anteriores del marco se ejecutan en versiones de Windows que incluyen versiones más recientes del marco, siempre que coincidan las versiones principales. Por ejemplo, un controlador compilado con KMDF 1.9 (Windows 7) se ejecuta en un sistema Windows 8 (KMDF 1.11). En el ejemplo, el controlador se limita a la funcionalidad de KMDF 1.9.
  • Agregado: a partir de la versión 1.25 de KMDF y la versión 2.25 de UMDF en Windows 10 versión 1803, puede compilar un controlador con una versión de marco más reciente y el binario del controlador resultante se ejecuta en versiones anteriores de Windows (como mínimo Windows 10 versión 1803). Además, el controlador puede usar condicionalmente la funcionalidad que solo está disponible en versiones más recientes del marco.

Esto significa que el controlador no solo se ejecuta en versiones futuras de Windows, como siempre, sino que también se ejecuta en versiones anteriores, de vuelta a Windows 10 versión 1803.

Hay dos pasos para hacerlo: especificar la configuración de compilación en Visual Studio y realizar una comprobación en tiempo de ejecución antes de invocar una API o acceder a una estructura o campo que puede o no estar presente.

Nota: Esta característica es opcional y un controlador solo debe habilitarlo para crear un controlador que use la funcionalidad de WDF más reciente, mientras permanece cargable en versiones anteriores de Windows que no tienen la funcionalidad WDF más reciente.

Si no establece versión secundaria (versión de destino) o versión secundaria (mínima requerida), el control de versiones sigue siendo el mismo que antes.

Especificar el mínimo requerido

Las nuevas opciones de configuración de Visual Studio son:

  • Versión secundaria de KMDF (mínima requerida)
  • Versión secundaria de UMDF (mínima requerida)

De acuerdo con este cambio, se actualizaron los nombres de dos configuraciones existentes:

  • Versión secundaria de KMDF :>versión secundaria de KMDF (versión de destino)
  • Versión secundaria de UMDF:>versión secundaria de UMDF (versión de destino)

Si no establece Mínimo requerido, Visual Studio compila para la versión de destino y versiones posteriores, y no proporciona compatibilidad con el nivel inferior. Esto coincide con el comportamiento de las propiedades anteriores de la versión secundaria .

Si establece Mínimo requerido, se aplican los siguientes requisitos:

  • 25 <= Mínimo requerido <= Versión de destino
  • En Propiedades de configuración-Configuración del> controlador-General>, establezca _NT_TARGET_VERSION en 0x0A000005 (RS4) o posterior.

Comprobación de si la funcionalidad está presente

Antes de cada uso de una API, estructura o miembro que puede o no estar presente, debe llamar a una de las macros siguientes, que se definen en WdfFuncEnum.h:

BOOLEAN
WDF_IS_FUNCTION_AVAILABLE (
    FunctionName
    );

BOOLEAN
WDF_IS_STRUCTURE_AVAILABLE (
    StructName
    );

BOOLEAN
WDF_IS_FIELD_AVAILABLE (
    StructName,
    FieldName
    );

Considere el ejemplo siguiente. Cuando se publica WDF v29, agrega una nueva API: WdfSomeNewFeature. Si establece Versión de destino en 29 y Mínima requerida en 25, el controlador resultante se carga en cualquier versión de marco de trabajo de 25 a 29 (y versiones posteriores, siempre y cuando la versión principal no cambie), llama a las API de la versión 25 como antes y realiza la siguiente comprobación antes de cada llamada de cualquier API v29:

if (WDF_IS_FUNCTION_AVAILABLE(WdfSomeNewFeature)) {
    WdfSomeNewFeature();
}

Si no realiza la comprobación condicional, es posible que vea lo siguiente:

  • Si la API devuelve NTSTATUS, la llamada devuelve un código de error.
  • Si la API devuelve algo distinto de NTSTATUS:
    • KMDF: comprobaciones de errores de la máquina.
    • UMDF: el proceso WudfHost se bloquea con un error DriverStop.
  • Si el comprobador de controladores está habilitado, el controlador también se bloquea. Esto ayuda a identificar el problema en un entorno de prueba.
  • Daños en la memoria silenciosa (al acceder a una estructura o campo).

Un bloqueo de controlador contiene el nombre del controlador con errores, el nombre del marco y el índice de API con errores. Para recuperar el nombre de la API, busque el valor de WDFFUNCENUM en WdfFuncEnum.h.

Para obtener más información sobre las propiedades de Visual Studio para WDF, vea Propiedades de configuración del modelo de controladores para proyectos de controladores.