Configuration du débogage en mode noyau USB KDNET (KDNET-USB)

Article
10/31/2024

Les outils de débogage pour Windows prennent en charge le débogage en mode noyau sur un câble USB 3.0 à l’aide de KDNET sur USB. Cet article explique comment configurer cette option de transport.

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

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

Sur l’ordinateur hôte, un contrôleur hôte USB 3.0+ xHCI et un port USB3.
Sur l’ordinateur cible, un contrôleur hôte USB 3.0+ xHCI et un port USB3 prenant en charge le débogage (DBC)
Le contrôleur hôte USB de l’ordinateur cible doit prendre en charge l’interface de fonctionnalité de débogage Intel xHCI (DBC). Pour plus d’informations, reportez-vous à la spécification xHCI disponible sur le site Web Intel.

Fichiers de transport binaires

Le pilote kdstub.dll et kdnic.sys sont utilisés pour prendre en charge le transport du débogueur KDNET-USB.

Configuration requise pour les câbles

Un câble de débogage USB Microsoft orange, qui est un câble croisé A-A qui a deux plugs de type A mâle et aucune connexion Vbus. Ce câble est disponible auprès des fournisseurs tels que DataPro - USB 3.0 Super-Speed A/A Debugging Cable.
Un adaptateur USB 3.0 type C standard à type A est requis pour connecter le port A de type hôte au port C de type cible.

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

Configurez l’ordinateur cible

Sur l’ordinateur cible, recherchez et lancez l’outil UsbView . L’outil UsbView est inclus dans les outils de débogage pour Windows. Pour un système x64, UsbView se trouve dans C :\Program Files (x86)\Windows Kits\10\Tools\KitVersion\x64\usbview.exe.
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 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 numéros. 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
```
Si vous devez confirmer les paramètres de bus, utilisez Gestionnaire de périphériques. 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 sont affichés. b, d et f sont les numéros de bus, d’appareil et de fonction pour le contrôleur hôte USB3. Les numéros de bus, d’appareilet de fonction doivent être au format décimal.

Vous pouvez également utiliser kdnet.exe pour collecter des informations sur le contrôleur USB.

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

Network debugging is supported on the following USB controllers:
busparams=0.20.0, Intel(R) USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)

This Microsoft hypervisor supports using KDNET in guest VMs.

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 dans n’importe quel connecteur USB sur l’ordinateur cible. Actualisez UsbView pour voir où se trouve votre appareil. Si UsbView affiche votre appareil connecté à votre 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 ou de kdnet.exe 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é lorsque les tests sont terminés et gérez de manière appropriée le PC de test lorsque les fonctionnalités de sécurité sont désactivées.

Choisissez une <port address> paire unique pour chaque paire cible/hôte avec laquelle vous travaillez, dans la plage recommandée de 5 0000 à 50039. 50005 est illustré dans les exemples ci-dessous.
Recherchez l’utilitaire KDNet.exe dans le répertoire du débogueur WDK correspondant à votre type d’UC, par exemple x64.
Sur l’ordinateur cible, ouvrez une fenêtre d’invite de commandes en tant qu’administrateur et entrez cette commande pour activer le débogage du noyau avec -k l’option. Les applications système -w, -w, -b et -h activent le débogage du noyau pour les applications système winload, bootmgr et hyperviseur. Pour plus d’informations sur les options WinDbg, consultez les options de démarrage de la ligne de commande.
```
kdnet.exe 169.254.255.255 50005 -k
```
- 169.254.255.255 l’adresse IP statique statique non routable doit être utilisée pour KDNET sur USB3.
- kdnet.exe retourne une clé w.x.y.z qui sera utilisée par WinDbg pour se connecter à l’appareil cible.
Pour utiliser un port USB spécifique, utilisez le paramètre -busparams .
```
kdnet.exe -busparams 0.13.0 169.254.255.255 50005 -k
```
L’utilisation de l’utilitaire KDNET est recommandée. Cet outil définit des options plus complexes à définir à l’aide de bcdedit, ainsi que la vérification et la définition des valeurs de Registre prenant en charge les valeurs de Registre pour la gestion de l’alimentation et pci.
```
bcdedit /dbgsettings NET hostip:169.254.255.255 port:50001 key:1.2.3.4 busparams:0.20.0 noDhcp
```

Désactiver la gestion de l’alimentation

Dans certains cas, les transitions d’alimentation peuvent interférer avec le débogage via 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ésactivez la case Autoriser l’ordinateur à désactiver cet appareil pour enregistrer 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 l’onglet et désactivez l’option Autoriser l’ordinateur à désactiver cet appareil pour enregistrer l’alimentation .

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 à l’aide de WinDbg

Connectez un câble de débogage USB 3.0 aux ports USB 3.0 identifiés que vous avez choisis pour le débogage sur les ordinateurs hôtes et cibles.
Sur l’ordinateur hôte, ouvrez une version de WinDbg (en tant qu’administrateur) qui correspond au bit 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 Attacher au noyau. Dans la boîte de dialogue Débogage du noyau, ouvrez l’onglet Net . Entrez les informations suivantes, puis cliquez sur OK.
- Unique <port address> pour chaque paire cible/hôte, et qui se trouve dans la plage recommandée de 50000 à 50039, a été fournie comme entrée lorsque kdnet.exe a été exécuté.
- <session key> W.x.y.z qui a été généré lorsque kdnet.exe a été exécuté et sa valeur a été affichée dans la sortie de commande.

Session de ligne de commande avec WinDbg

Vous pouvez également démarrer une session avec WinDbg en entrant cette commande dans une fenêtre d’invite de commandes.

Windbg /k NET:port=<port address>,key=<session key>

Redémarrez l’ordinateur cible

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

Après le redémarrage de l’ordinateur cible, le débogueur devrait 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 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 USB sur la cible.

Pour plus d’informations et des descriptions de modèles de processeur, consultez Ice Lake (microprocesseur) et Tiger Lake (microprocesseur). Pour rechercher le modèle de processeur de l’ordinateur cible, ouvrez l’application Paramètres, puis accédez au système, puis à propos. Le processeur est répertorié dans les spécifications de l’appareil.

Pour vérifier ce problème, ouvrez Gestionnaire de périphériques et recherchez l’appareil de connexion de débogage USB sous contrôleurs de bus série universel. Si cet appareil est introuvable, recherchez un appareil inconnu sous Autres appareils. Cliquez avec le bouton droit sur l’appareil pour ouvrir sa page de propriétés. La zone de texte d’état de l’appareil aura le texte que 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 d’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

Soyez prudent lorsque vous modifiez directement le Registre, car les modifications incorrectes peuvent entraîner une instabilité du système.

La connexion retente les messages sur les fenêtres de la console du débogueur et ne peut pas entrer dans la cible - SkipPciProbeDebugDevice

Si vous rencontrez le message suivant dans la console du débogueur KDNET, ne peut pas lancer d’arrêt dans la cible ou rencontrer des problèmes avec certaines commandes (par exemple, kdfiles), il peut être dû à KDNET recevant un paquet ping hors séquence.

... Retry sending the same data packet for 128 times.

The transport connection between host kernel debugger and target Windows seems lost.
please try resync with target, recycle the host debugger, or reboot the target Windows.

Ce problème peut se produire, car le pilote pci.sys sonde l’appareil de débogage. Pour éliminer ces messages d’erreur, créez l’entrée de Registre suivante sur l’appareil TARGET à l’invite de commandes administrateur.

Ce paramètre peut également autoriser le débogueur à se connecter si le transport KD initial n’a pas pu se connecter au démarrage, pour une autre raison, par exemple si l’appareil de débogage n’a pas pu être configuré au démarrage.

reg add HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\SERVICES\kdnet /v SkipPciProbeDebugDevice /t REG_DWORD /d 1 /f

Redémarrez ensuite l’ordinateur cible.

shutdown /r /t 0

Une fois l’appareil redémarré, les erreurs doivent disparaître, et les commandes doivent fonctionner comme prévu.

NO_KDNIC paramètre pour améliorer les performances et la fiabilité

Si une carte réseau Ethernet est installée sur le PC cible, des améliorations supplémentaires de fiabilité et de performances peuvent être obtenues en définissant l’option NO_KDNIC .

bcdedit /set {current} loadoptions NO_KDNIC

L’ajout NO_KDNIC est facultatif et ne peut être utilisé que si la cible dispose d’une carte réseau supplémentaire, wi-fi ou port USB pour connecter une carte USB-Ethernet pour fournir un accès réseau à Windows.

L’ajout NO_KDNIC empêche le pilote kdnic.sys (pilote basé sur un minuteur de miniport) de s’exécuter sur KDNET, ce qui signifie que le trafic TCP/IP Windows ne sera pas routé via le transport KDNET. Le transport KDNET peut ensuite être utilisé uniquement pour router les paquets liés au débogage entre le KDNET cible et le débogueur hôte.

Cela peut aider à améliorer les performances réseau qui peuvent être affectées lorsque kdnic.sys pilote s’exécute sur kdnet. Dans ce cas, la cible ne sera jamais mise en veille, empêchant les tests d’alimentation ou les retards se produisent lors de l’accès à la cible via RDP. Cela est dû au fait que l’interface KDNET doit acheminer les paquets du débogueur et les paquets réseau TCP/IP Windows lorsque kdnic.sys est en cours d’exécution.