Utilisation du vérificateur de pilote statique pour rechercher des défauts dans les pilotes Windows

Article
07/03/2024

Static Driver Verifier (SDV) utilise un ensemble de règles d’interface et un modèle du système d’exploitation pour déterminer si le pilote interagit correctement avec le système d’exploitation Windows. SDV trouve des défauts dans le code du pilote qui pourraient pointer vers des bogues potentiels dans les pilotes.

SDV peut analyser les pilotes en mode noyau qui sont conformes à l’un des modèles de pilotes suivants : WDM, KMDF, NDIS ou Storport. Pour plus d’informations, consultez Pilotes pris en charge et détermination si le vérificateur de pilotes statiques prend en charge votre pilote ou bibliothèque. En outre, SDV fournit une prise en charge limitée (un ensemble de règles sévèrement restreint axé sur des erreurs générales telles que les déréférencements null) pour les pilotes qui ne suivent pas les modèles de pilotes ci-dessus.

Important

SDV n’est plus pris en charge et SDV n’est plus disponible dans les versions wdK ou EWDK de Windows 24H2. Il n’est pas disponible dans les kits WDK plus récents que la build 26017 et n’est pas inclus dans windows 24H2 RTM WDK. SDV peut toujours être utilisé en téléchargeant windows 11, version 22H2 EWDK (publiée le 24 octobre 2023) avec Visual Studio Build Tools 17.1.5 à partir du téléchargement du Kit de pilotes Windows (WDK). Seule l’utilisation du kit WDK Entreprise pour exécuter SDV est recommandée. L’utilisation de versions antérieures de WDK standard conjointement avec les versions récentes de Visual Studio n’est pas recommandée, car cela entraînera probablement des échecs d’analyse.
À l’avenir, CodeQL sera l’outil d’analyse statique principal pour les pilotes. CodeQL fournit un langage de requête puissant qui traite le code comme une base de données à interroger, ce qui facilite l’écriture de requêtes pour des comportements, des modèles spécifiques, etc. Pour plus d’informations sur l’utilisation de CodeQL, consultez CodeQL et le test du logo Static Tools.

Préparation de votre code source

Procédez comme suit pour préparer votre code à des fins d’analyse.

Déclarer des fonctions fournies par le pilote à l’aide de types de rôles de fonction

SDV exige que les fonctions soient déclarées à l’aide de déclarations de type de rôle de fonction. Par exemple, une routine DriverEntry doit être déclarée à l’aide du type de rôle de fonction DRIVER_INITIALIZE :
```
DRIVER_INITIALIZE DriverEntry;
```
Après la déclaration, vous implémentez (ou définissez) votre routine de rappel comme suit :
```
/
// Driver initialization routine
//
NTSTATUS
  DriverEntry(
    _In_ struct _DRIVER_OBJECT  *DriverObject,
    _In_ PUNICODE_STRING  RegistryPath
    )
  {
      // Function body
  }
```
Chaque modèle de pilote pris en charge a un ensemble de types de rôles de fonction pour les fonctions de rappel de pilote et les routines de répartition. Ces types de rôles de fonction sont déclarés dans les fichiers d’en-tête WDK. Par exemple, voici le prototype de fonction pour le type de rôle DRIVER_INITIALIZE tel qu’il apparaît dans 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;
```
Étant donné que les types de rôles de fonction sont déjà définis dans les fichiers d’en-tête WDK, vous devez uniquement déclarer vos fonctions de rappel à ce type. Dans ce cas, vous déclarez DriverEntry comme étant de type DRIVER_INITIALIZE. Pour obtenir la liste complète des types de rôles de fonction pour les modèles de pilotes, consultez Utilisation des déclarations de type de rôle de fonction.

Exécuter l’analyse du code pour C/C++

Pour vous aider à déterminer si le code source est préparé, exécutez l’outil Analyse du code dans Visual Studio. L’outil Analyse du code vérifie les déclarations de type de rôle de fonction requises par SDV. L’outil Analyse du code peut vous aider à identifier les déclarations de fonction qui ont pu être manquées ou vous avertir lorsque les paramètres de la définition de fonction ne correspondent pas à ceux du type de rôle de fonction.

Ouvrez votre projet de pilote dans Visual Studio.
Dans le menu Générer , cliquez sur Exécuter l’analyse du code sur la solution.

Les résultats sont affichés dans la fenêtre Analyse du code. Corrigez les déclarations de fonction que vous avez peut-être manquées. Vous pouvez également configurer l’outil Analyse du code afin qu’il s’exécute chaque fois que vous générez votre solution.

Le tableau suivant présente certains avertissements que l’outil Analyse du code peut trouver dans votre code de pilote. Pour exécuter static Driver Verifier, votre pilote doit être libre de ces défauts.

Analyse du code pour l’avertissement C/C++	Description
C28101	Le module Drivers a déduit que la fonction actuelle est une <fonction de type> fonction
C28022	Les classes de fonctions sur cette fonction ne correspondent pas aux classes de fonctions sur le typedef utilisé pour les définir.
C28023	La fonction affectée ou transmise doit avoir une annotation _Function_class_ pour au moins l’une des classes
C28024	Le pointeur de la fonction attribuée est annoté avec la classe de fonction, laquelle n’est pas contenue dans la liste des classes de fonctions.
C28169	La fonction <> de répartition n’a pas d’annotations _Dispatch_type_
C28208	La signature de fonction ne correspond pas aux déclarations de fonction

Exécution du vérificateur de pilote statique

Ouvrez votre fichier de projet de pilote (.vcxProj) dans Visual Studio. Dans le menu Pilote, cliquez sur Lancer Static Driver Verifier….

Cela ouvre l’application Static Driver Verifier, où vous pouvez contrôler, configurer et planifier quand static Driver Verifier effectue une analyse.
Si votre pilote inclut une bibliothèque, cliquez sur l’onglet Bibliothèques , puis cliquez sur Ajouter une bibliothèque pour ajouter la bibliothèque.

Accédez au répertoire du code source de votre bibliothèque et sélectionnez le fichier projet (.vcxProj). Ajoutez toutes les bibliothèques que votre pilote inclut. Les bibliothèques doivent être ajoutées avant que SDV analyse votre pilote. Lorsque vous démarrez une analyse de votre pilote, SDV analyse également les bibliothèques qui n’ont pas été traitées. Une fois qu’une bibliothèque est traitée, elle est stockée dans le cache SDV global. Pour plus d’informations, consultez Traitement de bibliothèque dans le vérificateur de pilote statique
Vérifiez les paramètres de configuration du vérificateur de pilote statique. Cliquez sur l'onglet Configurer .

Configuration du projet La configuration du projet affiche les paramètres de configuration et de plateforme que vous avez sélectionnés dans Visual Studio.

Dans la plupart des cas, vous pouvez utiliser les paramètres par défaut. Si SDV signale timeout, GiveUp ou Spaceout, vous pouvez essayer d’ajuster ces paramètres. Pour plus d’informations, consultez Recommandations pour la résolution des problèmes du vérificateur de pilote statique.

Planifiez la sélection d’une heure de début pour que la vérification commence. Le paramètre par défaut consiste à commencer l’analyse immédiatement après avoir cliqué sur Démarrer sous l’onglet Principal . En fonction de la taille du pilote et de sa complexité, l’analyse statique peut prendre beaucoup de temps. Vous pouvez planifier l’analyse pour commencer quand elle est la plus pratique pour vous ; par exemple, à la fin de la journée.

Remarque

Veillez à vérifier le plan de gestion de l’alimentation de votre ordinateur pour vous assurer que l’ordinateur n’entre pas dans un état de veille pendant l’analyse.
Cliquez sur l’onglet Règles pour sélectionner les règles d’utilisation de l’API de pilote à vérifier lorsque vous démarrez l’analyse.

Static Driver Verifier détecte le type de pilote que vous analysez (WDF, WDM, NDIS ou Storport) et sélectionne l’ensemble par défaut de règles pour votre type de pilote. Si c’est la première fois que vous exécutez SDV sur votre pilote, vous devez exécuter l’ensemble de règles par défaut.

Pour plus d’informations sur les règles, consultez règles de conformité DDI.
Démarrez l’analyse statique. Cliquez sur l’onglet Principal , puis sur Démarrer. Lorsque vous cliquez sur Démarrer, un message s’affiche pour vous informer que l’analyse statique est planifiée et que l’analyse peut prendre beaucoup de temps. Pour continuer, cliquez sur OK . L’analyse commence au moment où vous avez planifié.

Affichage et analyse des résultats

À mesure que l’analyse statique se poursuit, SDV signale l’état de l’analyse. Une fois l’analyse terminée, SDV signale les résultats et les statistiques. Si le pilote ne répond pas à une règle d’utilisation d’API, le résultat est signalé comme un défaut.

Si des problèmes ont été rencontrés, SDV les affiche dans les pages Avertissements et Erreurs . La page Propriétés du pilote affiche les résultats des tests pour certaines propriétés du pilote. Les tests de propriétés du pilote sont utilisés pour identifier les fonctionnalités du pilote afin de qualifier davantage l’analyse. Vous pouvez utiliser les résultats des propriétés du pilote pour confirmer les propriétés attendues et les fonctionnalités prises en charge de votre pilote.

Pour afficher des défauts spécifiques dans le rapport du vérificateur de pilote statique, cliquez sur le défaut dans le volet Résultats . Cela ouvre la Visionneuse de suivi, qui affiche une trace du chemin du code vers la violation de règle. Pour plus d’informations, consultez Interprétation des résultats du vérificateur de pilote statique.

Remarque

Static Driver Verifier conserve les résultats et les paramètres de l’analyse. Pour effacer les résultats, cliquez sur Nettoyer.

Résolution des problèmes des résultats du vérificateur de pilote statique

Si SDV signale qu’aucun défaut n’a été trouvé, vérifiez l’onglet Principal pour vous assurer que les points d’entrée sont détectés. Si le pilote ne déclare pas de fonctions à l’aide des types de rôles de fonction, SDV ne peut pas analyser et rechercher des défauts dans le code du pilote. Pour plus d’informations, consultez Utilisation des déclarations de type de rôle de fonction.

Si SDV signale des délais d’expiration ou ne retourne pas de résultats utiles, vous devrez peut-être modifier quelques options de configuration SDV. Pour plus d’informations sur la résolution des problèmes de SDV, consultez Recommandations pour la résolution des problèmes du vérificateur de pilote statique.

Déterminer si le vérificateur de pilotes statiques prend en charge votre pilote ou bibliothèque

Utilisation des déclarations de type de rôle de fonction

Règles du vérificateur de pilote statique

Outil Analyse du code