Partager via

Tutoriel : Écrire un pilote Windows universel (KMDF) basé sur un modèle

Cette rubrique explique comment écrire un pilote Windows universel à l’aide de Kernel-Mode Driver Framework (KMDF). Vous allez commencer par un modèle Microsoft Visual Studio, puis déployer et installer votre pilote sur un ordinateur distinct.

Conditions préalables

  • Suivez les étapes pour installer le kit de pilotes Windows (WDK). Les outils de débogage pour Windows sont inclus lorsque vous installez le WDK.

  • Installez Visual Studio 2022. Lorsque vous installez Visual Studio 2022, sélectionnez la charge de travail Desktop development with C++, puis sous Individual Components, ajoutez :

    • MSVC v143 - VS 2022 C++ ARM64/ARM64EC librairies protégées contre Spectre (dernière version disponible)
    • Bibliothèques avec atténuations Spectre MSVC v143 – VS 2022 C++ x64/x86 (dernière version)
    • C++ ATL pour la dernière version de Build Tools v143 avec atténuations Spectre (ARM64/ARM64EC)
    • C++ ATL pour la dernière version de Build Tools v143 avec atténuations Spectre (x86 & x64)
    • C++ MFC pour la dernière version de Build Tools v143 avec atténuations Spectre (ARM64/ARM64EC)
    • C++ MFC pour la dernière version de Build Tools v143 avec atténuations Spectre (x86 & x64)
    • Kit de pilotes Windows

Créez et construisez un pilote

  1. Ouvrez Microsoft Visual Studio. Dans le menu Fichier, choisissez Nouveau> projet.

  2. Dans la boîte de dialogue Créer un projet, sélectionnez C++ dans la liste déroulante gauche, choisissez Windows au milieu de la liste déroulante, puis choisissez pilote dans la liste déroulante de droite.

  3. Sélectionnez Kernel Mode Driver (KMDF) dans la liste des types de projets. Sélectionnez Suivant.

    Capture d’écran de la boîte de dialogue

    Conseil

    Si vous ne trouvez pas de modèles de projet de pilote dans Visual Studio, l’extension WDK Visual Studio n’a pas été correctement installée. Pour résoudre ce problème, lancez Visual Studio Installer, sélectionnez Modifier, ajoutez Kits de pilotes Windows sous l’onglet composant individuel, puis sélectionnez Modifier.

  4. Dans la boîte de dialogue Configurer votre nouveau projet, entrez « KmdfDriver » dans le champ nom du projet.

    Note

    Lorsque vous créez un pilote KMDF ou UMDF, vous devez sélectionner un nom de pilote qui comporte 32 caractères ou moins. Cette limite de longueur est définie dans wdfglobals.h.  

  5. Dans le champ Emplacement, entrez le répertoire dans lequel vous souhaitez créer le projet.

  6. Vérifiez Placez la solution et le projet dans le même répertoire, puis sélectionnez Créer.

    capture d’écran de la boîte de dialogue de configuration du projet.

    Visual Studio crée un projet et une solution. Vous pouvez les voir dans la fenêtre de l’Explorateur de solutions. (Si la fenêtre de l’Explorateur de solutions n’est pas visible, choisissez Explorateur de solutions dans le menu Affichage.) La solution a un projet de pilote nommé KmdfDriver. Pour voir le code source du pilote, ouvrez n'importe quel fichier sous Fichiers source. Driver.c et Device.c sont de bons endroits pour démarrer.

    Capture d’écran de l’Explorateur de solutions montrant les fichiers dans le projet de pilote.

  7. Dans la fenêtre de l’Explorateur de solutions, sélectionnez et maintenez la touche enfoncée (ou cliquez avec le bouton droit) KmdfDriver, puis choisissez Propriétés. Naviguez jusqu'à Propriétés de la configuration> Paramètres du pilote > Général, et notez que la plateforme cible est par défaut Universal.

  8. Pour construire votre pilote, choisissez Build Solution dans le menu Build. Microsoft Visual Studio affiche la progression de la génération dans la fenêtre Sortie. (Si la fenêtre Sortie n’est pas visible, choisissez Sortie dans le menu Affichage.)

    Vérifiez que la sortie de build inclut :

    >    Driver is 'Universal'.

    Lorsque vous avez vérifié que la solution a été générée avec succès, vous pouvez fermer Visual Studio.

  9. Pour afficher le pilote généré, dans l’Explorateur de fichiers, accédez à votre dossier KmdfDriver, puis à x64\Debug\KmdfDriver. Le répertoire inclut les fichiers suivants :

    • KmdfDriver.sys :- le fichier de pilote en mode noyau
    • KmdfDriver.inf : fichier d’informations que Windows utilise lorsque vous installez le pilote

Déployer le pilote

En règle générale, lorsque vous testez et déboguez un pilote, le débogueur et le pilote s’exécutent sur des ordinateurs distincts. L’ordinateur qui exécute le débogueur est appelé 'ordinateur hôte, et l’ordinateur qui exécute le pilote est appelé ordinateur cible. L’ordinateur cible est également appelé ordinateur de test. Pour obtenir plus d'informations sur le débogage des pilotes, consultez Outils de débogage pour Windows.

Jusqu’à présent, vous avez utilisé Visual Studio pour générer un pilote sur l’ordinateur hôte. Vous devez maintenant configurer un ordinateur cible.

  1. Suivez les instructions de Configurer un ordinateur pour le déploiement et les tests des pilotes (WDK 10).

    Conseil

    Lorsque vous suivez les étapes permettant de provisionner automatiquement l’ordinateur cible à l’aide d’un câble réseau, notez le port et la clé. Vous les utiliserez ultérieurement à l’étape de débogage. Dans cet exemple, nous allons utiliser 50000 comme port et 1.2.3.4 comme clé.

    Dans les scénarios de débogage de pilotes réels, nous vous recommandons d’utiliser une clé générée par KDNET. Pour plus d’informations sur l’utilisation de KDNET pour générer une clé aléatoire, consultez la rubrique Debug Drivers - Step by Step Lab (Mode noyau Sysvad).

  2. Sur l’ordinateur hôte, ouvrez votre solution dans Visual Studio. Vous pouvez double-cliquer sur le fichier de solution, KmdfDriver.sln, dans votre dossier KmdfDriver.

  3. Dans la fenêtre de l’Explorateur de solutions, sélectionnez et maintenez la touche enfoncée (ou cliquez avec le bouton droit) sur le projet KmdfDriver, puis choisissez Propriétés.

  4. Dans la fenêtre Pages de propriétés du package KmdfDriver, dans le volet de gauche, allez à Propriétés de la configuration> Installation du pilote > Déploiement.

  5. Cochez Supprimer les versions précédentes du pilote avant le déploiement.

  6. Pour Nom de l’ordinateur distant, sélectionnez le nom de l’ordinateur que vous avez configuré pour les tests et le débogage. Dans cet exercice, nous utilisons un ordinateur nommé MyTestComputer.

  7. Sélectionnez Mise à jour du pilote via l’ID matériel, et entrez l’ID matériel pour votre pilote. Dans cet exercice, l’ID matériel est Root\KmdfDriver. Sélectionnez OK.

    capture d’écran de la fenêtre de propriétés du package kmdfdriver, montrant l’installation du pilote de déploiement sélectionnée

    Note

    Dans cet exercice, l’ID matériel n’identifie pas un élément matériel réel. Il identifie un appareil imaginaire qui se verra attribuer une place dans l'arborescence des périphériques en tant que descendant du nœud racine. Pour le matériel réel, ne sélectionnez pas Mise à jour du pilote ID matériel ; sélectionnez plutôt Installation et vérification. L'ID du matériel figure dans le fichier d'information du pilote (INF). Dans la fenêtre de l’Explorateur de solutions, accédez à KmdfDriver > Fichiers de pilotes et double-cliquez sur KmdfDriver.inf. L’ID matériel se trouve sous [Standard.NT$ARCH$].

    [Standard.NT$ARCH$]
%KmdfDriver.DeviceDesc%=KmdfDriver_Device, Root\KmdfDriver

  8. Dans le menu Build, choisissez Déployer la solution. Visual Studio copie automatiquement les fichiers requis pour installer et exécuter le pilote sur l’ordinateur cible. Cela peut prendre une minute ou deux.

    Lorsque vous déployez un pilote, les fichiers du pilote sont copiés dans le dossier %Systemdrive%\drivertest\drivers sur l’ordinateur de test. Si un problème se produit pendant le déploiement, vous pouvez vérifier si les fichiers sont copiés sur l’ordinateur de test. Vérifiez que les fichiers .inf, .cat, test cert et .sys, et tous les autres fichiers nécessaires, sont présents dans le dossier %systemdrive%\drivertest\drivers.

    Pour plus d’informations sur le déploiement de pilotes, consultez Déploiement d’un pilote sur un ordinateur de test.

Installer le pilote

Avec votre pilote KMDF déployé sur l’ordinateur cible, vous allez maintenant installer le pilote. Lorsque vous avez précédemment approvisionné l’ordinateur cible avec Visual Studio à l’aide de l’option automatique , Visual Studio a configuré l’ordinateur cible pour exécuter des pilotes signés de test comme partie du processus d’approvisionnement. Vous devez maintenant installer le pilote à l’aide de l’outil DevCon.

  1. Sur l’ordinateur hôte, accédez au dossier Outils de votre installation WDK et recherchez l’outil DevCon. Par exemple, recherchez dans le dossier suivant :

    C:\Program Files (x86)\Windows Kits\10\Tools\x64\devcon.exe

    Copiez l’outil DevCon sur votre ordinateur distant.

  2. Sur l’ordinateur cible, installez le pilote en accédant au dossier contenant les fichiers du pilote, puis en exécutant l’outil DevCon.

    1. Voici la syntaxe générale de l’outil devcon que vous allez utiliser pour installer le pilote :

      Fichier INF< de ><devcon installI>dentification du matériel

      Le fichier INF requis pour l’installation de ce pilote est KmdfDriver.inf. Le fichier INF contient l'ID du matériel pour l'installation du pilote binaire, KmdfDriver.sys. Rappelez-vous que l’ID matériel, situé dans le fichier INF, est Root\KmdfDriver.

    2. Ouvrez une fenêtre d’invite de commande en tant qu’Administrateur. Accédez à votre dossier de package de pilotes, puis entrez cette commande :

      devcon install kmdfdriver.inf root\kmdfdriver

      Si vous recevez un message d’erreur indiquant que devcon n'est pas reconnu, essayez d’ajouter le chemin à l’outil devcon. Par exemple, si vous l’avez copiée dans un dossier sur l’ordinateur cible appelé C :\Tools, essayez d’utiliser la commande suivante :

      c:\tools\devcon install kmdfdriver.inf root\kmdfdriver

      Une boîte de dialogue s’affiche indiquant que le pilote de test est un pilote non signé. Sélectionnez Installer ce pilote quand même pour continuer.

      capture d’écran de l’avertissement d’installation du pilote.

Déboguez le pilote

Maintenant que vous avez installé votre pilote KMDF sur l’ordinateur cible, vous attacherez un débogueur à distance à partir de l’ordinateur hôte.

  1. Sur l’ordinateur hôte, ouvrez une fenêtre d’invite de commandes en tant qu’administrateur. Accédez au répertoire WinDbg.exe. Nous allons utiliser la version x64 de WinDbg.exe à partir du Kit de pilotes Windows (WDK) qui a été installé dans le cadre de l’installation du kit Windows. Voici le chemin d’accès par défaut à WinDbg.exe:

    C :\Program Files (x86)\Windows Kits\10\Debuggers\x64

  2. Lancez WinDbg pour vous connecter à une session de débogage du noyau sur l’ordinateur cible à l’aide de la commande suivante. La valeur du port et de la clé doit être identique à celle que vous avez utilisée pour approvisionner l’ordinateur cible. Nous allons utiliser 5 0000 pour le port et 1.2.3.4 pour la clé, les valeurs que nous avons utilisées pendant l’étape de déploiement. L’indicateur k indique qu’il s’agit d’une session de débogage du noyau.

    WinDbg -k net:port=50000,key=1.2.3.4

  3. Dans le menu Debug, choisissez Break. Le débogueur de l'ordinateur hôte se connecte à l'ordinateur cible. Dans la fenêtre de commande du débogueur, vous pouvez voir la requête de commande de débogage du noyau : kd>.

  4. À ce stade, vous pouvez expérimenter le débogueur en entrant des commandes à la requête kd>. Par exemple, vous pouvez essayer ces commandes :

  5. Pour laisser réexécuter l’ordinateur cible, choisissez Go dans le menu Déboguer ou appuyez sur « g », puis appuyez sur « Entrée ».

  6. Pour arrêter la session de débogage, choisissez Detach Debuggee dans le menu Debug

    Importante

    Veillez à utiliser la commande « go » pour laisser l’ordinateur cible s’exécuter à nouveau avant de quitter le débogueur, ou l’ordinateur cible ne répond pas à votre souris et à l’entrée du clavier, car il parle toujours au débogueur.

Pour une procédure pas-à-pas détaillée du processus de débogage des pilotes, voir Déboguer les pilotes universels - Labo étape par étape (Mode noyau Echo).

Pour plus d’informations sur le débogage à distance, consultez Débogage à distance à l’aide de WinDbg.

Utilisation du cadre de module de pilote (DMF)

Le Driver Module Framework (DMF) est une extension de WDF qui offre des fonctionnalités supplémentaires aux développeurs de pilotes WDF. Il aide les développeurs à écrire n’importe quel type de pilote WDF mieux et plus rapidement.

DMF en tant que framework permet la création d’objets WDF appelés modules DMF. Le code de ces modules DMF peut être partagé entre différents pilotes. De plus, DMF regroupe une bibliothèque de modules DMF que nous avons développées pour nos pilotes et que nous pensons fournir de la valeur à d’autres développeurs de pilotes.

DMF ne remplace pas WDF. DMF est un deuxième framework utilisé avec WDF. Le développeur tirant parti de DMF utilise toujours WDF et toutes ses primitives pour écrire des pilotes de périphérique.

Pour plus d’informations, consultez Driver Module Framework (DMF).