Configuration manuelle du débogage Kernel-Mode sur un câble USB 2.0

Article
04/14/2023

Outils de débogage pour Windows prend en charge le débogage du noyau sur un câble USB 2.0. Cette rubrique explique comment configurer manuellement le débogage USB 2.0.

L’ordinateur qui exécute le débogueur est appelé ordinateur hôte, et l’ordinateur en cours de débogage est appelé ordinateur cible.

Le débogage sur un câble USB 2.0 nécessite le matériel suivant :

Un câble de débogage USB 2.0. Ce câble n’est pas un câble USB 2.0 standard, car il dispose d’un composant matériel supplémentaire qui le rend compatible avec la spécification fonctionnelle de l’appareil de débogage USB2. Vous pouvez trouver ces câbles avec une recherche Internet pour le terme câble de débogage USB 2.0.
Sur l’ordinateur hôte, un contrôleur hôte EHCI (USB 2.0)
Sur l’ordinateur cible, un contrôleur hôte EHCI (USB 2.0) qui prend en charge le débogage

Pour simplifier la résolution des problèmes, connectez le câble directement entre l’ordinateur cible et l’ordinateur hôte, en évitant les hubs ou les stations d’accueil.

Configuration de l’ordinateur cible

Sur l’ordinateur cible, lancez l’outil UsbView. L’outil UsbView est inclus dans Outils de débogage pour Windows.
Dans UsbView, recherchez tous les contrôleurs hôtes compatibles avec la spécification EHCI. Par exemple, vous pouvez rechercher des contrôleurs répertoriés comme améliorés.
Dans UsbView, développez les nœuds des contrôleurs hôtes EHCI. Recherchez une indication indiquant qu’un contrôleur hôte prend en charge le débogage et recherchez le numéro du port de débogage. Par exemple, UsbView affiche cette sortie pour un contrôleur hôte EHCI qui prend en charge le débogage sur le port 1.
```
Xxx xxx xxx USB2 Enhanced Host Controller - 293A
...
Debug Port Number:  1
Bus.Device.Function (in decimal): 0.29.7
```
Note De nombreux contrôleurs hôtes EHCI prennent en charge le débogage sur le port 1, mais certains contrôleurs hôtes EHCI prennent en charge le débogage sur le port 2.
Notez les numéros de bus, d’appareil et de fonction du contrôleur EHCI que vous envisagez d’utiliser pour le débogage. UsbView affiche ces nombres. Dans l’exemple précédent, le numéro de bus est 0, le numéro d’appareil est 29 et le numéro de fonction est 7.
Une fois que vous avez identifié le contrôleur EHCI et le numéro de port qui prend en charge le débogage, l’étape suivante consiste à localiser le connecteur USB physique associé au numéro de port correct. Pour trouver le connecteur physique, connectez n’importe quel appareil USB 2.0 à n’importe quel connecteur USB de l’ordinateur cible. Actualisez UsbView pour voir où se trouve votre appareil. Si UsbView montre votre appareil connecté au port et au contrôleur hôte EHCI que vous avez identifiés comme port de débogage, vous avez trouvé un connecteur USB physique que vous pouvez utiliser pour le débogage. Il se peut qu’il n’existe aucun connecteur USB physique externe associé à un port de débogage sur un contrôleur EHCI. Dans ce cas, vous pouvez rechercher un connecteur USB physique à l’intérieur de l’ordinateur. Effectuez les mêmes étapes pour déterminer si le connecteur USB interne convient au débogage du noyau. Si vous ne trouvez pas de connecteur USB physique (externe ou interne) associé à un port de débogage, vous ne pouvez pas utiliser l’ordinateur comme cible pour le débogage sur un câble USB 2.0.

Note Pour obtenir une exception, consultez cette remarque .

Important

Avant d’utiliser bcdedit pour modifier les informations de démarrage, vous devrez peut-être suspendre temporairement les fonctionnalités de sécurité Windows telles que BitLocker et le démarrage sécurisé sur le PC de test. Vous pouvez réactiver le démarrage sécurisé une fois que vous avez terminé le débogage et que vous avez désactivé le débogage du noyau.

Sur l’ordinateur cible, ouvrez une fenêtre d’invite de commandes en tant qu’administrateur, puis entrez les commandes suivantes :
- bcdedit /debug on
- bcdedit /dbgsettings usb targetname :TargetName
où TargetName est un nom que vous créez pour l’ordinateur cible. Notez que TargetName n’a pas besoin d’être le nom officiel de l’ordinateur cible ; il peut s’agir de n’importe quelle chaîne que vous créez tant qu’elle respecte les restrictions suivantes :
- La chaîne ne doit pas contenir « debug » n’importe où dans targetName dans une combinaison de majuscules ou minuscules. Par exemple, si vous utilisez « DeBuG » ou « DEBUG » n’importe où dans votre nom cible, le débogage ne fonctionnera pas correctement.
- Les seuls caractères de la chaîne sont le trait d’union (-), le trait de soulignement(_), les chiffres 0 à 9 et les lettres A à Z (majuscules ou minuscules).
- La longueur maximale de la chaîne est de 24 caractères.
Dans Gestionnaire de périphériques recherchez le contrôleur USB que vous envisagez d’utiliser pour le débogage. Sous Emplacement sous l’onglet Général , les numéros de bus, d’appareil et de fonction s’affichent. Entrez cette commande :

bcdedit /set « {dbgsettings} » busparamsb.d.f

où b, d et f sont les numéros de bus, d’appareil et de fonction du contrôleur hôte. Les numéros de bus, d’appareil et de fonction doivent être au format décimal (par exemple, busparams 0.29.7).

Redémarrez l’ordinateur cible.

Configuration de l’ordinateur hôte

Vérifiez que l’ordinateur hôte n’est pas configuré pour être la cible du débogage USB. (Si nécessaire, ouvrez une fenêtre d’invite de commandes en tant qu’administrateur, entrez bcdedit /debug off, puis redémarrez.)
Sur l’ordinateur hôte, utilisez UsbView pour rechercher les ports et les contrôleurs hôtes EHCI qui prennent en charge le débogage. Si possible, branchez une extrémité du câble de débogage USB 2.0 à un port EHCI (sur l’ordinateur hôte) qui ne prend pas en charge le débogage. Sinon, branchez le câble à n’importe quel port EHCI sur l’ordinateur hôte.
Branchez l’autre extrémité du câble de débogage USB 2.0 au connecteur que vous avez identifié précédemment sur l’ordinateur cible.

Démarrage d’une session de débogage pour la première fois

Déterminez le bit (32 bits ou 64 bits) de Windows en cours d’exécution sur l’ordinateur hôte.
Sur l’ordinateur hôte, ouvrez une version de WinDbg (en tant qu’administrateur) qui correspond au bitness de Windows en cours d’exécution sur l’ordinateur hôte. Par exemple, si l’ordinateur hôte exécute une version 64 bits de Windows, ouvrez la version 64 bits de WinDbg en tant qu’administrateur.
Dans le menu Fichier , choisissez Débogage du noyau. Dans la boîte de dialogue Débogage du noyau, ouvrez l’onglet USB . Entrez le nom cible que vous avez créé lorsque vous configurez l’ordinateur cible. Cliquez sur OK.

À ce stade, le pilote de débogage USB est installé sur l’ordinateur hôte. C’est pourquoi il est important de faire correspondre le bitness de WinDbg à celui de Windows. Une fois le pilote de débogage USB installé, vous pouvez utiliser la version 32 bits ou 64 bits de WinDbg pour les sessions de débogage suivantes.

Note Le câble de débogage USB 2.0 est en fait deux câbles avec un dongle au milieu. La direction du dongle est importante ; un côté alimente l’appareil, et l’autre pas. Si le débogage USB ne fonctionne pas, essayez d’échanger le sens du dongle. Autrement dit, débranchez les deux câbles du dongle et échangez les côtés auxquels les câbles sont connectés.

Démarrage d’une session de débogage

Utilisation de WinDbg

Sur l’ordinateur hôte, ouvrez WinDbg. Dans le menu Fichier , choisissez Débogage du noyau. Dans la boîte de dialogue Débogage du noyau, ouvrez l’onglet USB . Entrez le nom cible que vous avez créé lorsque vous configurez l’ordinateur cible. Cliquez sur OK.

Vous pouvez également démarrer une session avec WinDbg en entrant la commande suivante dans une fenêtre d’invite de commandes, où TargetName est le nom cible que vous avez créé lorsque vous configurez l’ordinateur cible :

windbg /k usb :targetname=TargetName

Utilisation de KD

Sur l’ordinateur hôte, ouvrez une fenêtre d’invite de commandes et entrez la commande suivante, où TargetName est le nom cible que vous avez créé lorsque vous configurez l’ordinateur cible :

kd /k usb :targetname=TargetName

Que se passe-t-il si USBView affiche un port compatible avec le débogage, mais qu’il n’affiche pas le port mappé à un connecteur physique ?

Sur certains ordinateurs, USBView affiche un port compatible avec le débogage, mais n’affiche pas le port mappé à un connecteur USB physique. Par exemple, USBView peut afficher le port 2 comme numéro de port de débogage pour un contrôleur eHCI.

... USB Enhanced Host Controller ...
...
Debug Port Number:  2
Bus.Device.Function (in decimal): 0.29.0

En outre, lorsque vous utilisez USBView pour examiner le port individuel, il est répertorié comme compatible avec le débogage.

[Port 2]
Is Port User Connectiable: Yes
Is Port Debug Capable: Yes
...
Protocols Supported
  USB 1.1      yes
  USB 2.0      yes
  USB 3.0      no

Mais lorsque vous branchez un appareil USB 2.0 (comme un lecteur flash) à tous les connecteurs USB de l’ordinateur, USBView n’affiche jamais votre appareil connecté au port compatible avec le débogage (port 2 dans cet exemple). USBView peut afficher le connecteur externe mappé à un port d’un contrôleur xHCI quand, en fait, le connecteur externe est mappé au port compatible avec le débogage du contrôleur eHCI.

Capture d’écran des contrôleurs xHCI et EHCI dans USBView.

Dans un cas comme celui-ci, vous pouvez toujours établir un débogage en mode noyau via un câble USB 2.0. Dans l’exemple donné ici, vous devez connecter votre câble de débogage USB 2.0 au connecteur qui apparaît comme étant mappé au port 2 du contrôleur xHCI. Ensuite, vous devez définir vos paramètres de bus sur les numéros de bus, d’appareil et de fonction du contrôleur eHCI (dans cet exemple, 0.29.0).

bcdedit /set "{dbgsettings}" busparams 0.29.0

Support supplémentaire

Pour obtenir des conseils de résolution des problèmes et d’autres informations, consultez le blog Microsoft USB.

Voir aussi

Configuration manuelle du débogage Kernel-Mode