Création d’un pilote WDF pour plusieurs versions de Windows

  • Article

WDF vous a toujours permis de créer un pilote une seule fois et d’utiliser le fichier binaire résultant sur plusieurs versions de Windows, mais avant Windows 10 version 1803 (Redstone 4), cela se limitait à « générer sur des versions plus anciennes, exécuter sur des versions plus récentes ». À compter de Windows 10 version 1803, WDF ajoute « build sur plus récent, exécutez sur plus ancienne », avec l’avantage supplémentaire de l’exécution conditionnelle. Pour récapituler :

  • Existant : les fichiers binaires créés avec des versions antérieures de l’infrastructure s’exécutent sur des versions de Windows qui incluent des versions plus récentes de l’infrastructure, à condition que les versions principales correspondent. Par exemple, un pilote créé avec KMDF 1.9 (Windows 7) s’exécute sur un système Windows 8 (KMDF 1.11). Dans l’exemple, le pilote est limité aux fonctionnalités de KMDF 1.9.
  • Ajouté : à partir de KMDF version 1.25 et UMDF version 2.25 sur Windows 10 version 1803, vous pouvez créer un pilote avec une version de framework plus récente et le fichier binaire du pilote résultant s’exécute sur des versions antérieures de Windows (au minimum Windows 10 version 1803). En outre, le pilote peut utiliser de manière conditionnelle des fonctionnalités qui sont uniquement disponibles dans les versions plus récentes du framework.

Cela signifie que non seulement votre pilote s’exécute sur les versions futures de Windows, comme il l’a toujours fait, mais qu’il s’exécute également sur les versions antérieures, à Windows 10 version 1803.

Pour ce faire, il existe deux étapes : spécification des paramètres de build dans Visual Studio et exécution d’un case activée runtime avant d’appeler une API ou d’accéder à une structure ou à un champ qui peuvent être présents ou non.

Remarque : cette fonctionnalité est facultative et un pilote doit uniquement lui permettre de créer un pilote qui utilise la dernière fonctionnalité WDF tout en restant chargeable sur les versions antérieures de Windows qui ne disposent pas de la dernière fonctionnalité WDF.

Si vous ne définissez pas version mineure (version cible) ou version mineure (minimum requis), le contrôle de version reste le même qu’auparavant.

Spécification du minimum requis

Les nouveaux paramètres de configuration dans Visual Studio sont les suivants :

  • Version mineure de KMDF (minimum requis)
  • Version mineure de UMDF (minimum requis)

Conformément à cette modification, les noms de deux paramètres existants ont été mis à jour :

  • VERSION KMDF Mineure ->VERSION KMDF Mineure (Version cible)
  • Version mineure d’UMDF ->Version mineure d’UMDF (version cible)

Si vous ne définissez pas Minimum Obligatoire, Visual Studio génère pour la version cible et la version ultérieure, et ne fournit pas de prise en charge de niveau inférieur. Cela correspond au comportement des anciennes propriétés version mineure .

Si vous définissez Minimum Obligatoire, les conditions suivantes s’appliquent :

  • 25 <= Minimum Obligatoire <= Version cible
  • Dans Propriétés de configuration-Paramètres> du pilote-Général>, définissez _NT_TARGET_VERSION sur 0x0A000005 (RS4) ou version ultérieure.

Vérification de la présence de fonctionnalités

Avant toute utilisation d’une API, d’une structure ou d’un membre qui peut être présent ou non, vous devez appeler l’une des macros suivantes, qui sont définies dans WdfFuncEnum.h :

BOOLEAN
WDF_IS_FUNCTION_AVAILABLE (
    FunctionName
    );

BOOLEAN
WDF_IS_STRUCTURE_AVAILABLE (
    StructName
    );

BOOLEAN
WDF_IS_FIELD_AVAILABLE (
    StructName,
    FieldName
    );

Considérez l'exemple suivant. Lorsque WDF v29 est publié, il ajoute une nouvelle API : WdfSomeNewFeature. Si vous définissez version cible sur 29 et minimum requis sur 25, le pilote résultant se charge sur n’importe quelle version de framework de 25 à 29 (et au-delà, tant que la version principale ne change pas), appelle les API de la version 25 comme auparavant, et effectue les case activée suivantes avant chaque appel d’une API v29 :

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

Si vous n’effectuez pas la case activée conditionnelle, vous pouvez voir les éléments suivants :

  • Si l’API retourne NTSTATUS, l’appel retourne un code d’échec.
  • Si l’API retourne autre chose que NTSTATUS :
    • KMDF : vérification des bogues de la machine.
    • UMDF : le processus WudfHost se bloque avec une erreur DriverStop.
  • Si le vérificateur de pilotes est activé, le pilote se bloque également. Cela permet d’identifier le problème dans un environnement de test.
  • Altération de la mémoire en mode silencieux (lors de l’accès à une structure ou à un champ).

Un incident de pilote contient le nom du pilote ayant échoué, le nom de l’infrastructure et l’index d’API ayant échoué. Vous pouvez récupérer le nom de l’API en recherchant la valeur de WDFFUNCENUM dans WdfFuncEnum.h.

Pour plus d’informations sur les propriétés de Visual Studio pour WDF, consultez Propriétés des paramètres du modèle de pilote pour les projets de pilotes.