Partager via

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

  • Article

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

Avant de continuer, vous devez suivre les étapes d’installation répertoriées dans Télécharger le Kit de pilotes Windows (WDK).

Les outils de débogage pour Windows sont inclus lorsque vous installez le WDK.

Créer et générer 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 de gauche, choisissez Windows dans la liste déroulante du milieu, puis choisissez Pilote dans la liste déroulante de droite.

  3. Sélectionnez Pilote en mode noyau (KMDF) dans la liste des types de projets. Sélectionnez Suivant.

    Capture d’écran de la boîte de dialogue nouveau projet, montrant le pilote en mode noyau sélectionné.

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

    Notes

    Lorsque vous créez un pilote KMDF ou UMDF, vous devez sélectionner un nom de pilote comportant 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 nouveau projet.

  6. Cochez Placer 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. Ceux-ci sont visibles dans la fenêtre Explorateur de solutions. (Si la fenêtre 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 afficher le code source du pilote, ouvrez l’un des fichiers sous Fichiers sources. Driver.c et Device.c sont de bons points de départ.

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

  7. Dans la fenêtre Explorateur de solutions, sélectionnez KmdfDriver et maintenez-le enfoncé (ou cliquez avec le bouton droit) et choisissez Propriétés. Accédez à Propriétés de configuration > Paramètres > du pilote Général et notez que la plateforme cible par défaut est Universelle.

  8. Pour générer votre pilote, choisissez Générer une solution dans le menu Générer . Microsoft Visual Studio affiche la progression de la build 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'.

    Une fois que vous avez vérifié que la solution a été correctement générée, vous pouvez fermer Visual Studio.

  9. Pour voir le pilote généré, dans Explorateur de fichiers, accédez à votre dossier KmdfDriver, puis à x64\Debug\KmdfDriver. Le répertoire comprend 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 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 créer un pilote sur l’ordinateur hôte. Vous devez maintenant configurer un ordinateur cible.

  1. Suivez les instructions fournies dans Provisionner un ordinateur pour le déploiement et le test de pilotes (WDK 10).

    Conseil

    Lorsque vous suivez les étapes pour approvisionner automatiquement l’ordinateur cible à l’aide d’un câble réseau, notez le port et la clé. Vous les utiliserez plus loin dans 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 (Sysvad Kernel Mode).

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

  3. Dans la fenêtre Explorateur de solutions, sélectionnez le projet KmdfDriver de façon enfoncée (ou cliquez avec le bouton droit), puis choisissez Propriétés.

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

  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 le test et le débogage. Dans cet exercice, nous utilisons un ordinateur nommé MyTestComputer.

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

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

    Notes

    Dans cet exercice, l’ID matériel n’identifie pas un élément matériel réel. Il identifie un appareil imaginaire qui recevra une place dans l’arborescence de l’appareil en tant qu’enfant du nœud racine. Pour le matériel réel, ne sélectionnez pas Mise à jour du pilote d’ID matériel ; à la place, sélectionnez Installer et vérifier. Vous verrez l’ID matériel dans le fichier d’informations de votre pilote (INF). Dans la fenêtre Explorateur de solutions, accédez à Fichiers du pilote KmdfDriver > 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 Générer , choisissez Déployer la solution. Visual Studio copie automatiquement les fichiers nécessaires pour installer et exécuter le pilote sur l’ordinateur cible. Cela peut prendre une à deux minutes.

    Lorsque vous déployez un pilote, les fichiers de pilotes 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 case activée pour voir si les fichiers sont copiés sur l’ordinateur de test. Vérifiez que les fichiers .inf, .cat, test cert et .sys, ainsi que 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

Une fois 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 dans le cadre du processus d’approvisionnement. Il vous suffit maintenant d’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 :

      ID matériel du fichier><INF d’installation <devcon>

      Le fichier INF requis pour l’installation de ce pilote est KmdfDriver.inf. Le fichier INF contient l’ID matériel pour l’installation du fichier binaire du pilote ,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 commandes en tant qu’administrateur. Accédez au dossier de votre package de pilotes, puis entrez cette commande :

      devcon installer kmdfdriver.inf root\kmdfdriver

      Si vous recevez un message d’erreur indiquant que devcon n’est pas reconnu, essayez d’ajouter le chemin d’accès à 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éboguer le pilote

Maintenant que vous avez installé votre pilote KMDF sur l’ordinateur cible, vous allez attacher 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 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 la même que celle que vous avez utilisée pour approvisionner l’ordinateur cible. Nous allons utiliser 50000 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 Déboguer , choisissez Arrêter. Le débogueur sur l’ordinateur hôte s’arrête sur l’ordinateur cible. Dans la fenêtre Commande du débogueur , vous pouvez voir l’invite de commandes de débogage du noyau : kd>.

  4. À ce stade, vous pouvez tester le débogueur en entrant des commandes à l’invite kd> . Par exemple, vous pouvez essayer les commandes suivantes :

  5. Pour permettre à l’ordinateur cible de s’exécuter à nouveau, 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 Détacher le débogage dans le menu Déboguer .

    Important

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

Pour obtenir une procédure pas à pas détaillée du processus de débogage du pilote, consultez Déboguer des pilotes universels - Labo pas à pas (Echo Kernel-Mode) .

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

Utilisation de l’infrastructure de module de pilote (DMF)

L’infrastructure de module de pilote (DMF) est une extension de WDF qui offre des fonctionnalités supplémentaires pour un développeur 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. En outre, DMF regroupe une bibliothèque de modules DMF que nous avons développés pour nos pilotes et qui, selon nous, fournirait 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).