Validation des pilotes Windows

  • Article

Utilisez les outils InfVerif, Vérificateur de pilotes (Driver Verifier) pour les vérifications d’isolation des pilotes, et ApiValidator pour tester votre package de pilotes afin de garantir sa conformité avec les exigences des pilotes Windows décrites dans Prise en main des pilotes Windows.

InfVerif

InfVerif est un outil qui valide la syntaxe INF et vérifie que l’INF est conforme aux exigences et restrictions.

Utilisez InfVerif avec /w pour vérifier qu’un pilote Windows :

Pour plus de détails, veuillez consulter la rubrique Exécution d’InfVerif à partir de la ligne de commande.

InfVerif valide les exigences d’isolation des pilotes avec l’argument « /w », comme illustré ici :

infverif.exe /w <INF file> [<INF file>]

Si InfVerif ne signale aucune erreur lors de la validation avec /w, l’INF satisfait l’exigence d’isolation du package de pilotes des pilotes Windows.

Ciblage des versions actuelles et antérieures de Windows

Si votre INF contient une syntaxe introduite dans une version récente de Windows, telle que la Directive AddEventProvider INF disponible à partir de la version 1809 de Windows 10 et que vous souhaitez également cibler des versions antérieures de Windows, utilisez les décorations INF pour marquer les entrées INF spécifiques à la version. Pour voir un exemple de code montrant comment utiliser des décorations de version du système d’exploitation, veuillez consulter la rubrique Combinaison d’extensions de plateforme avec des versions du système d’exploitation.

Les fichiers INF utilisant des décorations de version OS peuvent échouer à InfVerif car les exigences d’isolation des pilotes peuvent ne pas être prises en charge sur les versions antérieures de Windows. Pour valider un tel INF, vous pouvez spécifier la version minimale de Windows où les vérifications d’isolation des pilotes doivent être appliquées, en utilisant l’argument « /wbuild ». Par exemple, un fichier INF utilisant la directive AddEventProvider pourrait utiliser ce qui suit pour n’appliquer les vérifications d’isolation des pilotes qu’à Windows 10 version 1809 et les versions ultérieures :

infverif.exe /w /wbuild NTAMD64.10.0.0.17763 <INF file> [<INF file>]

Vérifications d’isolation des pilotes avec Vérificateur de pilotes

Pour être retenu comme pilote Windows, un package de pilotes doit respecter les exigences d’isolation du package de pilotes. À partir de Windows 11, le Vérificateur de pilotes (DV) peut surveiller les binaires du noyau pour les lectures et écritures de registre qui ne sont pas autorisées pour les packages de pilotes isolés.

Vous pouvez soit afficher les violations au fur et à mesure qu’elles se produisent dans un débogueur de noyau, soit configurer DV pour arrêter le système et générer un vidage mémoire avec les détails lorsqu’une violation se produit. Vous pouvez commencer le développement de pilotes avec la première méthode, puis passer à la deuxième lorsque votre pilote est presque terminé.

Pour afficher les violations au fur et à mesure qu’elles se produisent, connectez d’abord un débogueur de noyau, puis utilisez les commandes suivantes. Après un redémarrage ayant activé les paramètres DV, vous pouvez surveiller les violations dans la sortie du débogueur de noyau.

Pour activer les vérifications d’isolation des pilotes sur un seul pilote :

verifier /rc 33 36 /driver myDriver.sys

Pour vérifier plus d’un pilote, séparez chaque nom de pilote par un espace :

verifier /rc 33 36 /driver myDriver1.sys myDriver2.sys

Pour configurer DV pour provoquer un plantage en cas de violation, utilisez la syntaxe suivante :

verifier /onecheck /rc 33 36 /driver myDriver1.sys

Vous devrez redémarrer pour activer les paramètres de vérification. Pour faire cela à partir de la ligne de commande, spécifiez :

shutdown /r /t 0

Voici quelques exemples de messages d’erreur :

Exemple : ZwCreateKey fournit un chemin absolu complet :

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should not use absolute paths. Detected creation of unisolated registry key \Registry\Machine\SYSTEM

Exemple : ZwCreateKey fournit un chemin relatif à une poignée qui ne provient pas d’une API approuvée :

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

Considérez l’exécution des tests des fondamentaux du périphérique avec les vérifications d’isolation des pilotes DV activées sur votre pilote pour aider à détecter tôt les violations d’isolation des pilotes.

Pilotes KMDF

Lorsque les pilotes KMDF utilisent les API WDF pour accéder au registre, telles que WdfRegistryCreateKey, WdfRegistryOpenKey ou WdfRegistryQueryValue, l’accès au registre se fait via wdf01000.sys au lieu du binaire du pilote KMDF directement. Pour voir les violations causées par votre binaire de pilote KMDF, veuillez activer les vérifications d’isolation des pilotes sur wdf01000.sys en plus de votre binaire de pilote KMDF. Notez que lorsque vous faites cela, vous verrez des violations de tous les pilotes KMDF sur le système qui utilisent WDF pour leurs accès au registre.

ApiValidator

L’outil ApiValidator vérifie que les API appelées par vos binaires sont valides pour un pilote Windows. L’outil renvoie une erreur si vos binaires appellent une API qui est en dehors de l’ensemble des API valides pour les pilotes Windows. Cet outil fait partie du WDK pour Windows 10.

ApiValidator valide qu’un pilote prend en charge la superposition des API, l’une des exigences pour les pilotes Windows. Pour une liste complète des exigences, veuillez consulter la rubrique Prise en main des pilotes Windows.

Exécution d’ApiValidator dans Visual Studio

Si la propriété Plateforme cible de votre projet de pilote est définie sur Pilote Windows, Visual Studio exécute ApiValidator automatiquement en tant qu’étape post-génération.

Pour voir tous les messages affichés par ApiValidator, rendez-vous dans Outils->Options->Projets et solutions->Build and Run, et définissez Verbosité de la sortie de build du projet MSBuild sur Détaillé. Lors de la génération à partir de la ligne de commande, ajoutez l’option /v:detailed ou /v:diag à votre commande de génération pour augmenter la verbosité.

Pour l’échantillon de pilote umdf2_fx2, les erreurs de validation des API ressemblent à ceci :

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

Correction des erreurs de validation

  1. Si vous avez basculé un projet de pilote UMDF de bureau hérité vers un pilote Windows, vérifiez que vous incluez les bibliothèques correctes lors de la construction de vos binaires. Sélectionnez et maintenez (ou cliquez avec le bouton droit) sur le projet et choisissez propriétés. Rendez-vous dans Linker->Input. Les Dépendances supplémentaires devraient contenir :

    %AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib

    Pour examiner d’autres options de linker (éditeur de liens) pour cibler les SKU OneCore, veuillez consulter la rubrique Générer pour OneCore.

  2. Supprimez ou remplacez les appels d’API qui ne sont pas autorisés un par un et relancez l’outil jusqu’à ce qu’il n’y ait plus d’erreurs.

  3. Dans certains cas, vous pouvez remplacer ces appels par des DDI alternatifs répertoriés sur les pages de référence des DDI uniquement pour les ordinateurs de bureau. Vous devrez peut-être coder une solution alternative s’il n’y a pas de remplacement approprié. Si nécessaire, écrivez un nouveau pilote Windows en commençant par les modèles de pilote dans le WDK.

Si vous voyez des erreurs comme les suivantes, veuillez vous référer aux instructions dans Générer pour 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

Exécution d’ApiValidator à partir de l’invite de commandes

Vous pouvez également exécuter Apivalidator.exe à partir de l’invite de commandes. Dans votre installation WDK, rendez-vous dans C:\Program Files (x86)\Windows Kits\10\bin<arch> et C:\Program Files (x86)\Windows Kits\10\build\universalDDIs<arch>.

Remarques importantes :

  • ApiValidator nécessite les fichiers suivants : ApiValidator.exe, Aitstatic.exe, Microsoft.Kits.Drivers.ApiValidator.dll, et UniversalDDIs.xml.
  • Le fichier UniversalDDIs.xml doit correspondre à l’architecture binaire à valider, par exemple pour un pilote x64 utilisez le UniversalDDI.xml x64
  • ApiValidator teste une seule architecture à la fois
  • Veuillez consulter les Problèmes connus d’ApiValidator ci-dessous pour obtenir des informations supplémentaires

Utilisez la syntaxe suivante :

Apivalidator.exe -DriverPackagePath: <driver folder path> -SupportedApiXmlFiles: (path to XML files containing supported APIs for Windows drivers)

Par exemple, pour vérifier les API appelées par l’échantillon d’activité dans le WDK, d’abord construisez l’échantillon dans Visual Studio. Ensuite, ouvrez une invite de commandes et naviguez jusqu’au répertoire contenant l’outil, par exemple C:\Program Files (x86\Windows Kits\10\bin\x64. Entrez la commande suivante :

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"

La commande produit la sortie suivante :

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

Dépannage d’ApiValidator

Si ApiValidator.exe renvoie une erreur de format incorrect comme celle-ci :

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

Utilisez cette solution de contournement :

  1. Ouvrez les propriétés du projet, rendez-vous dans Général, et renommez Répertoire de sortie comme suit :

    $(SolutionDir)$(Platform)\$(ConfigurationName)\

  2. Recréez la solution.

Problèmes connus d’ApiValidator

  • ApiValidator ne s’exécute pas sur Arm64 car AitStatic ne fonctionne pas sur Arm64.
  • Les binaires Arm64 peuvent être testés sur des machines x64 mais pas sur une machine x86.
  • ApiValidator peut s’exécuter sur x86 pour tester les binaires x86 et Arm.
  • ApiValidator peut s’exécuter sur x64 pour tester les binaires x86, x64, Arm et Arm64.