Configurer le débogage en mode noyau sur un câble USB 3.0

Article
02/06/2024

Outils de débogage pour Windows prend en charge le débogage en mode noyau sur un câble USB 3.0. Cet article explique comment configurer manuellement le débogage USB 3.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 3.0 nécessite le matériel suivant :

Un câble de débogage USB 3.0, qui est un câble croisé A-A qui a deux fiches mâle de type A et aucune connexion Vbus
Sur l’ordinateur hôte, un contrôleur hôte xHCI (USB 3.0)
Sur l’ordinateur cible, un contrôleur hôte xHCI (USB 3.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.

Configurer 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 xHCI.

Dans UsbView, développez les nœuds des contrôleurs hôtes xHCI. Recherchez une indication indiquant qu’un port sur le contrôleur hôte prend en charge le débogage.

[Port1]

Is Port User Connectable:         yes
Is Port Debug Capable:            yes
Companion Port Number:            3
Companion Hub Symbolic Link Name: USB#ROOT_HUB30#5&32bab638&0&0#{...}
Protocols Supported:
 USB 1.1:                         no
 USB 2.0:                         no
 USB 3.0:                         yes

Notez les numéros de bus, d’appareil et de fonction du contrôleur xHCI que vous envisagez d’utiliser pour le débogage. UsbView affiche ces nombres. Dans l’exemple suivant, le numéro de bus est 48, le numéro d’appareil est 0 et le numéro de fonction est 0.
```
USB xHCI Compliant Host Controller
...
DriverKey: {36fc9e60-c465-11cf-8056-444553540000}\0020
...
Bus.Device.Function (in decimal): 48.0.0
```
Après avoir identifié un contrôleur xHCI qui prend en charge le débogage, l’étape suivante consiste à localiser le connecteur USB physique associé à un port sur le contrôleur xHCI. Pour trouver le connecteur physique, branchez n’importe quel périphérique USB 3.0 sur n’importe quel connecteur USB de l’ordinateur cible. Actualisez UsbView pour voir où se trouve votre appareil. Si UsbView affiche votre appareil connecté au contrôleur hôte xHCI choisi, vous avez trouvé un connecteur USB physique que vous pouvez utiliser pour le débogage USB 3.0.

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. Réactivez ces fonctionnalités de sécurité une fois le test terminé et gérez correctement le PC de test lorsque les fonctionnalités de sécurité sont désactivées.

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>
```
TargetName est un nom que vous créez pour l’ordinateur cible. Notez que TargetName ne doit pas ê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 ces restrictions :
- 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 de cible, le débogage ne fonctionne 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}" busparams <b.d.f>
```
B, d et f sont les numéros de bus, d’appareil et de fonction du contrôleur hôte USB. Les numéros de bus, d’appareil et de fonction doivent être au format décimal.

Exemple :
```
bcdedit /set "{dbgsettings}" busparams 48.0.0
```
Redémarrez l’ordinateur cible.

Désactiver la gestion de l’alimentation

Dans certains cas, les transitions d’alimentation peuvent interférer avec le débogage sur USB 3.0. Pour éviter ces problèmes, désactivez l’interruption sélective pour le contrôleur hôte xHCI et son hub racine que vous utilisez pour le débogage.

Dans Gestionnaire de périphériques, accédez au nœud du contrôleur hôte xHCI. Cliquez avec le bouton droit sur le nœud, puis choisissez Propriétés. S’il existe un onglet Gestion de l’alimentation, ouvrez l’onglet et décochez la case Autoriser l’ordinateur à désactiver cet appareil pour économiser l’alimentation .
Dans Gestionnaire de périphériques, accédez au nœud du hub racine du contrôleur hôte xHCI. Cliquez avec le bouton droit sur le nœud, puis choisissez Propriétés. S’il existe un onglet Gestion de l’alimentation, ouvrez-le et désactivez la zone Autoriser l’ordinateur à éteindre cet appareil pour économiser l’alimentation case activée.

Lorsque vous avez terminé d’utiliser le contrôleur hôte xHCI pour le débogage, réactivez la suspension sélective pour le contrôleur hôte xHCI.

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

Connectez un câble de débogage USB 3.0 aux ports USB 3.0 que vous avez choisis pour le débogage sur les ordinateurs hôtes et cibles.
Déterminez le nombre de bits (32 bits ou 64 bits) de Windows exécuté sur l’ordinateur hôte.
Sur l’ordinateur hôte, ouvrez une version de WinDbg (en tant qu’administrateur) qui correspond au nombre de bits 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 Noyau Déboguer. Dans la boîte de dialogue Débogage du noyau, ouvrez l’onglet USB . Entrez le nom de la cible que vous avez créé lors de la configuration de 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 nombre de bits 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.

Démarrer une session de débogage

Utilisation de WinDbg

Sur l’ordinateur hôte, ouvrez WinDbg. Dans le menu Fichier , choisissez Noyau Déboguer. Dans la boîte de dialogue Débogage du noyau, ouvrez l’onglet USB . Entrez le nom de la cible que vous avez créé lors de la configuration de l’ordinateur cible. Sélectionnez 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 de la cible que vous avez créé lorsque vous configurez l’ordinateur cible :

kd /k usb:targetname=<TargetName>

Redémarrer l’ordinateur cible

Une fois le débogueur connecté, redémarrez l’ordinateur cible. Une façon de redémarrer le PC consiste à utiliser la commande à partir de l’invite shutdown -r -t 0 de commandes d’un administrateur.

Une fois le PC cible redémarré, le débogueur doit se connecter automatiquement.

Dépannage

Périphérique USB non reconnu

Si une notification Windows s’affiche sur l’hôte avec le périphérique USB de texte non reconnu lorsque vous insérez le câble de débogage, il est possible qu’un problème de compatibilité USB 3.1-3.1 connu soit atteint. Ce problème affecte les configurations de débogage lorsque le câble de débogage est connecté à un contrôleur USB 3.1 sur l’hôte et à un contrôleur USB Intel (Ice Lake ou Tiger Lake) 3.1 sur la cible.

Pour plus d’informations et la liste des modèles de processeur, consultez Ice Lake (microprocesseur) et ou Tiger Lake (microprocesseur). Pour rechercher le modèle de processeur de l’ordinateur cible, ouvrez l’application Paramètres et accédez à Système , puis À propos de. Le processeur est répertorié sous Spécifications de l’appareil.

Pour vérifier ce problème, ouvrez Gestionnaire de périphériques et recherchez Périphérique de connexion de débogage USB sous Contrôleurs Universal Serial Bus. Si cet appareil est introuvable, case activée pour un appareil inconnu sous Autres appareils. Cliquez avec le bouton droit sur l’appareil pour ouvrir sa page de propriétés. L’appareil status zone de texte contient le texte Windows a arrêté cet appareil, car il a signalé des problèmes (code 43) et le périphérique USB a retourné un descripteur USB BOS non valide.

Pour contourner ce problème, exécutez ces commandes à partir d’une invite de commandes administrateur pour apporter des modifications au Registre :

reg add HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\usbflags\349500E00000 /v SkipBOSDescriptorQuery /t REG_DWORD /d 1 /f
reg add HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\usbflags\045E06560000 /v SkipBOSDescriptorQuery /t REG_DWORD /d 1 /f

Ensuite, retirez et réinsérez le câble de débogage.

Voir aussi

Configurer manuellement le débogage en mode noyau