Partager via

Comment écrire votre premier pilote client USB (KMDF)

  • Article

Dans cet article, vous utiliserez le modèle de pilote USB en mode noyau fourni avec Microsoft Visual Studio pour écrire un simple pilote client basé sur le framework de pilotes en mode noyau (KMDF). Après avoir compilé et installé le pilote client, vous visualiserez le pilote client dans le Gestionnaire de périphériques et afficherez la sortie du pilote dans un débogueur.

Pour une explication sur le code source généré par le modèle, veuillez consulter la section Comprendre le code du modèle KMDF pour un pilote client USB.

Prérequis

Pour développer, déboguer et installer un pilote en mode noyau, vous avez besoin de deux ordinateurs :

  • Un ordinateur hôte exécutant Windows 7 ou une version ultérieure du système d’exploitation Windows. L’ordinateur hôte est votre environnement de développement, où vous écrivez et déboguez votre pilote.
  • Un ordinateur cible exécutant Windows Vista ou une version ultérieure de Windows. L’ordinateur cible a le pilote en mode noyau que vous souhaitez déboguer.

Avant de commencer, assurez-vous de respecter les prérequis suivants :

Configuration logicielle requise

  • Votre ordinateur hôte héberge votre environnement de développement et dispose de Visual Studio.
  • Votre ordinateur hôte dispose de la dernière version du Windows Driver Kit (WDK). Le kit inclut des en-têtes, des bibliothèques, des outils, de la documentation et les outils de débogage nécessaires pour développer, compiler et déboguer un pilote KMDF. Pour obtenir la dernière version du WDK, veuillez consulter la section Télécharger le Windows Driver Kit (WDK).
  • Votre ordinateur hôte dispose de la dernière version des outils de débogage pour Windows. Vous pouvez obtenir la dernière version via le WDK ou en consultant la section Télécharger et installer les outils de débogage pour Windows.
  • Votre ordinateur cible exécute Windows Vista ou une version ultérieure de Windows.
  • Vos ordinateurs hôte et cible sont configurés pour le débogage en mode noyau. Pour plus d’informations, veuillez consulter la section Configurer une connexion réseau dans Visual Studio.

Configuration matérielle requise

Procurez-vous un périphérique USB pour lequel vous allez écrire le pilote client. Dans la plupart des cas, un périphérique USB et sa spécification matérielle vous sont fournis. La spécification décrit les capacités du périphérique et les commandes du fabricant prises en charge. Utilisez la spécification pour déterminer les fonctionnalités du pilote USB et les décisions de conception associées.

Si vous êtes novice dans le développement de pilotes USB, utilisez le kit d’apprentissage OSR USB FX2 pour étudier les exemples USB inclus dans le WDK. Vous pouvez obtenir le kit d’apprentissage sur OSR Online. Il contient le périphérique USB FX2 et toutes les spécifications matérielles requises pour implémenter un pilote client.

Vous pouvez également obtenir des périphériques Microsoft USB Test Tool (MUTT). Le matériel MUTT peut être acheté chez JJG Technologies. Le périphérique n’a pas de firmware installé. Pour installer le firmware, téléchargez le package logiciel MUTT depuis ce site Web et exécutez MUTTUtil.exe. Pour plus d’informations, consultez la documentation incluse dans le package.

Étape 1 : Générer le code du pilote KMDF en utilisant le modèle de pilote USB de Visual Studio

Pour obtenir des instructions sur la génération du code du pilote KMDF, consultez les étapes de la section Écriture d’un pilote KMDF basé sur un modèle.

Pour le code spécifique à l’USB, sélectionnez les options suivantes dans Visual Studio :

  1. Dans la boîte de dialogue Nouveau projet, dans la zone de recherche en haut, tapez USB.
  2. Dans le volet central, sélectionnez Pilote en mode noyau, USB (KMDF).
  3. Cliquez sur Suivant.
  4. Entrez un nom de projet, choisissez un emplacement d’enregistrement et sélectionnez Créer.

Les captures d’écran suivantes montrent la boîte de dialogue Nouveau projet pour le modèle de Pilote USB en mode noyau.

options de nouveau projet visual studio.

options de nouveau projet visual studio deuxième écran.

Cet article suppose que le nom du projet Visual Studio est « MyUSBDriver_ ». Il contient les fichiers suivants :

Fichiers Description
Public.h Fournit des déclarations communes partagées par le pilote client et les applications utilisateur qui communiquent avec le périphérique USB.
<Nom du projet>.inf Contient les informations nécessaires pour installer le pilote client sur l’ordinateur cible.
Trace.h Déclare les fonctions de traçage et les macros.
Driver.h; Driver.c Déclare et définit les points d’entrée du pilote et les routines de rappel d’événements.
Device.h; Device.c Déclare et définit la routine de rappel d’événement pour l’événement de préparation du matériel.
Queue.h; Queue.c Déclare et définit une routine de rappel d’événement pour l’événement déclenché par l’objet file d’attente du framework.

Étape 2 : Modifier le fichier INF pour ajouter des informations sur votre périphérique

Avant de compiler le pilote, vous devez modifier le fichier INF du modèle avec des informations sur votre périphérique, en particulier la chaîne d’identification du matériel.

Dans l’Explorateur de solutions, sous Fichiers du pilote, double-cliquez sur le fichier INF.

Dans le fichier INF, vous pouvez fournir des informations telles que le nom du fabricant et du fournisseur, la classe de configuration du périphérique, etc. Une information que vous devez fournir est l’identifiant matériel de votre périphérique.

Pour fournir la chaîne d’identification du matériel :

  1. Connectez votre périphérique USB à votre ordinateur hôte et laissez Windows énumérer le périphérique.

  2. Ouvrez le Gestionnaire de périphériques et ouvrez les propriétés de votre périphérique.

  3. Dans l’onglet Détails, sélectionnez Identifiants matériels sous Propriété.

    L’identifiant matériel du périphérique s’affiche dans la zone de liste. Sélectionnez et maintenez (ou faites un clic droit) et copiez la chaîne d’identification du matériel.

  4. Remplacez USB\VID_vvvv&PID_pppp dans la ligne suivante par votre chaîne d’identification du matériel.

    [Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp

Étape 3 : Compiler le code du pilote client USB

Pour compiler votre pilote :

  1. Ouvrez le projet ou la solution du pilote dans Visual Studio
  2. Sélectionnez et maintenez (ou faites un clic droit) sur la solution dans Explorateur de solutions et sélectionnez Gestionnaire de configuration.
  3. Dans le Gestionnaire de configuration, sélectionnez la Configuration active de la solution (par exemple, Débogage ou Release) et la Plateforme active de la solution (par exemple, Win32) correspondant au type de build qui vous intéresse.
  4. Dans le menu Générer, sélectionnez Générer la solution.

Pour plus d’informations, veuillez consulter la section Compilation d’un pilote.

Étape 4 : Configurer un ordinateur pour les tests et le débogage

Pour tester et déboguer un pilote, vous exécutez le débogueur sur l’ordinateur hôte et le pilote sur l’ordinateur cible. Jusqu’à présent, vous avez utilisé Visual Studio sur l’ordinateur hôte pour compiler un pilote. Ensuite, vous devez configurer un ordinateur cible. Pour configurer un ordinateur cible, suivez les instructions de la section Approvisionnement d’un ordinateur pour le déploiement et le test de pilotes.

Étape 5 : Activer le traçage pour le débogage en mode noyau

Le code du modèle contient plusieurs messages de traçage (TraceEvents) qui peuvent vous aider à suivre les appels de fonction. Toutes les fonctions du code source contiennent des messages de traçage qui marquent l’entrée et la sortie d’une routine. En cas d’erreurs, le message de traçage contient le code d’erreur et une chaîne significative. Étant donné que le traçage WPP est activé pour votre projet de pilote, le fichier symbole PDB créé pendant le processus de compilation contient des instructions de formatage des messages de traçage. Si vous configurez les ordinateurs hôte et cible pour le traçage WPP, votre pilote peut envoyer des messages de traçage vers un fichier ou le débogueur.

Pour configurer votre ordinateur hôte pour le traçage WPP :

  1. Créez des fichiers de format de message de traçage (TMF) en extrayant les instructions de formatage des messages de traçage à partir du fichier symbole PDB.

    Vous pouvez utiliser Tracepdb.exe pour créer des fichiers TMF. L’outil est situé dans le <dossier d’installation>Windows Kits\10.0\bin\<architecture> du WDK. La commande suivante crée des fichiers TMF pour le projet de pilote.

    tracepdb -f <PDBFiles> -p <TMFDirectory>

    L’option -f spécifie l’emplacement et le nom du fichier symbole PDB. L’option -p spécifie l’emplacement des fichiers TMF créés par Tracepdb. Pour plus d’informations, veuillez consulter la section Commandes Tracepdb.

    À l’emplacement spécifié, vous verrez trois fichiers (un par fichier .c du projet). Ils portent des noms de fichiers GUID.

  2. Dans le débogueur, tapez les commandes suivantes :

    1. .load Wmitrace

      Charge l’extension Wmitrace.dll.

    2. .chain

      Vérifiez que l’extension du débogueur est chargée.

    3. !wmitrace.searchpath +<TMF file location>

      Ajoutez l’emplacement des fichiers TMF au chemin de recherche de l’extension du débogueur.

      La sortie ressemble à ceci :

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

Pour configurer votre ordinateur cible pour le traçage WPP :

  1. Assurez-vous que vous disposez de l’outil Tracelog sur votre ordinateur cible. L’outil est situé dans le <dossier d’installation>Windows Kits\8.0\Tools\<arch> du WDK. Pour plus d’informations, veuillez consulter la section Syntaxe des commandes Tracelog.

  2. Ouvrez une Fenêtre de commande et exécutez en tant qu’administrateur.

  3. Tapez la commande suivante :

    tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

    La commande démarre une session de traçage nommée MyTrace.

    L’argument guid spécifie le GUID du fournisseur de traçage, qui est le pilote client. Vous pouvez obtenir le GUID à partir du fichier Trace.h dans le projet Visual Studio Professional 2019. Comme autre option, vous pouvez taper la commande suivante et spécifier le GUID dans un fichier .guid. Le fichier contient le GUID au format avec tirets :

    tracelog -start MyTrace -guid c:\drivers\Provider.guid -flag 0xFFFF -level 7-rt -kd

    Vous pouvez arrêter la session de traçage en tapant la commande suivante :

    tracelog -stop MyTrace

Étape 6 : Déployer le pilote sur l’ordinateur cible

  1. Dans la fenêtre Explorateur de solutions, sélectionnez et maintenez (ou faites un clic droit) sur le *<nom du projet>*Package, et choisissez Propriétés.
  2. Dans le volet de gauche, accédez à Propriétés de la configuration > Installation du pilote > Déploiement.
  3. Cochez Activer le déploiement, et cochez Importer dans le magasin de pilotes.
  4. Pour Nom de l’ordinateur distant, spécifiez le nom de l’ordinateur cible.
  5. Sélectionnez Installer et vérifier.
  6. Sélectionnez OK.
  7. Dans le menu Déboguer, choisissez Démarrer le débogage, ou appuyez sur F5 sur le clavier.

Remarque

Ne spécifiez pas l’identifiant matériel de votre périphérique sous Mise à jour du pilote par ID matériel. L’identifiant matériel doit être spécifié uniquement dans les informations (fichier INF) de votre pilote.

Pour plus d’informations sur le déploiement du pilote sur le système cible dans Visual Studio, veuillez consulter la section Déploiement d’un pilote sur un ordinateur de test.

Vous pouvez également installer manuellement le pilote sur l’ordinateur cible en utilisant le Gestionnaire de périphériques. Si vous souhaitez installer le pilote depuis une invite de commande, ces utilitaires sont disponibles :

  • PnPUtil

    Cet outil est fourni avec Windows. Il se trouve dans Windows\System32. Vous pouvez utiliser cet utilitaire pour ajouter le pilote au magasin de pilotes.

    C:\>pnputil /a m:\MyDriver_.inf
Microsoft PnP Utility

Processing inf : MyDriver_.inf
Driver package added successfully.
Published name : oem22.inf

    Pour plus d’informations, veuillez consulter la section Exemples PnPUtil.

  • DevCon Update

    Cet outil est fourni avec le WDK. Vous pouvez l’utiliser pour installer et mettre à jour des pilotes.

    devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6

Étape 7 : Visualiser le pilote dans le Gestionnaire de périphériques

  1. Entrez la commande suivante pour ouvrir le Gestionnaire de périphériques :

    devmgmt

  2. Vérifiez que le Gestionnaire de périphériques affiche un nœud pour le nœud suivant :

    Exemples

    MyUSBDriver_Device

Étape 8 : Visualiser la sortie dans le débogueur

Visual Studio affiche d’abord la progression dans la fenêtre Sortie. Ensuite, il ouvre la Fenêtre immédiate du débogueur. Vérifiez que les messages de traçage apparaissent dans le débogueur sur l’ordinateur hôte. La sortie devrait ressembler à ceci, où « MyUSBDriver_ » est le nom du module du pilote :

[3]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverContextCleanup Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Exit
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Entry
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Exit