Validation des pilotes Windows

Article
10/16/2024

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 du développement de 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 :

Respecte le principe déclaratif (D) des Principes de conception DCH
Est conforme à l’exigence d’isolation du package de pilotes de Prise en main du développement de pilotes 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 dans le registre et le système de fichiers qui ne sont pas autorisées pour les packages de pilotes isolés.

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

Pour activer les vérifications d’isolation des pilotes afin qu’elles soient signalées via le débogueur de noyau et le journal des événements système, mais pas par vérification d'erreur du système :

verifier /rc 33 36 /driver myDriver.sys [myDriver2.sys ...]

Pour configurer DV pour provoquer une vérification d'erreur en cas de violation de l'isolation d'un pilote, utilisez la syntaxe suivante :

verifier /onecheck /rc 33 36 /driver myDriver1.sys [myDriver2.sys ...]

Quelle que soit la méthode de surveillance que vous choisissez, vous devez 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, comme indiqué dans le débogueur de noyau :

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.

Remarque

DV ne souhaite pas inonder les utilisateurs avec un déluge de rapports portant sur la même violation, c'est pourquoi il dispose d’un mécanisme de limitation permettant de restreindre le nombre de rapports portant sur une même erreur. À compter de Windows 11 24H2, pour vous assurer que vous voyez l’ensemble complet des violations d’isolation des pilotes pour toute exécution donnée d’un test ou d’une série de tests, vous pouvez demander que la limitation des violations d’isolation des pilotes soit réinitialisée à l’aide de :

verifier /dif 33 /action 1

Si vous ne le faites pas avant d’exécuter un test, vous risquez de ne pas voir certaines violations pendant l’exécution de vos tests si ces violations se sont produites avant le démarrage du test.

Conformité au contrat WHCP

Actuellement, le Programme de compatibilité matérielle Windows (WHCP) n’impose pas l’isolation complète du package de pilotes. Toutefois, à partir de Windows 11 24H2, le programme WHCP commence à inclure les exigences liées à l’isolation des pilotes. Pour activer le même niveau de validation d’isolation du package de pilotes que le Hardware Lab Kit (HLK) dans le cadre de l’application des exigences WHCP, utilisez la syntaxe suivante :

Verifier /dif 33 /33 whcp /driver myDriver.sys [myDriver2.sys ...]

En utilisant cette syntaxe, toutes les violations d’isolation des pilotes sont systématiquement signalées, mais celles qui ne sont pas appliquées pour le HLK sont signalées comme avertissements au lieu d’erreurs. Celles qui sont signalées comme des avertissements ne provoquent pas d'échec du HLK et ne forcent pas le système à vérifier les erreurs si vous activez les vérifications d'isolation des pilotes avec /onecheck afin de générer une vérification d'erreur lorsqu'une violation se produit.

Lors de l’affichage d’événements avec un débogueur de noyau, ceux qui sont considérés comme des erreurs ont le préfixe DRIVER_ISOLATION_VIOLATION, tandis que ceux qui sont des avertissements ont le préfixe DRIVER_ISOLATION_WARNING.

Lorsque vous affichez des événements dans le journal des événements système, les événements avec un attribut ErrorLevel de 0 sont considérés comme des erreurs, tandis que les événements avec une autre valeur ErrorLevel ne sont pas considérés comme des erreurs. Pour plus d’informations, consultez la section « Affichage des violations dans le journal des événements système » ci-dessous.

Affichage des violations dans le journal des événements système

Les violations du vérificateur de pilote sont signalées dans le journal des événements système du fournisseur Microsoft-Windows-Kernel-XDV, avec l’ID d’événement « 4 ». Sur Windows 11 24H2 et versions ultérieures, les événements contiennent une valeur ErrorLevel. Les événements ayant une valeur ErrorLevel de 0 sont considérés comme des erreurs en fonction du mode d’isolation du pilote actif (conformité complète de l’isolation du pilote et conformité de l’isolation WHCP) lorsque la violation a été générée. Les événements ayant d’autres valeurs ErrorLevel ne sont pas considérés comme des erreurs. Par exemple, un événement avec ces attributs est considéré comme une erreur :

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should not use absolute paths. Detected opening of unisolated registry key \Registry\Machine\System\CurrentControlSet\Services\ExampleDriver\Parameters
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0x0

Alors qu'un événement avec ces attributs n'est pas considéré comme une erreur :

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should only use key handles returned from WDF or WDM APIs. Detected querying of value under unisolated registry key \REGISTRY\MACHINE\SYSTEM\ControlSet001\Control
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0xf4240

Si vous utilisez l’application Observateur d’événements pour afficher le journal des événements système, vous pouvez filtrer l’affichage à l’aide du menu situé à droite de l’application en cliquant sur « Filtrer le journal actuel ». Dans la boîte de dialogue qui s’affiche, si vous accédez à l’onglet XML et modifiez la requête manuellement, vous pouvez utiliser cette requête pour filtrer le journal des événements système afin de n'afficher que les violations de DV devant être considérées comme des erreurs :

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

Si vous souhaitez filtrer l’affichage du journal des événements afin d'afficher toutes les violations de DV devant être considérées comme des erreurs après un certain temps (par exemple, après le démarrage d’un test), voici ce que vous pouvez faire :

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime&gt;='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

Si vous préférez charger et afficher un fichier XML, vous pouvez utiliser wevtutil pour générer un tel fichier sur la base des mêmes requêtes :

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime>='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

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 du développement de 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

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.
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.
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 :

Ouvrez les propriétés du projet, rendez-vous dans Général, et renommez Répertoire de sortie comme suit :
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
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.

Partager via