Configuration du débogage du noyau en mode 2PF avec KDNET
Les outils de débogage pour Windows prennent en charge le débogage du noyau via un câble réseau en utilisant plusieurs Fonctions Physiques (PF) sur les NICs pris en charge en partitionnant l’espace de configuration PCI.
Avec le débogage 2PF, chaque PF peut être connecté à un seul port réseau, permettant ainsi la fonctionnalité de débogage du noyau d’être connectée à un PF tandis que la pile réseau standard communique avec l’autre PF. De ce fait, KDNIC n’a pas besoin de router le trafic réseau Windows via KDNET, et KDNET sera uniquement responsable du routage du trafic du débogueur du noyau hôte. Cela résulte en une augmentation significative des performances.
Ce sujet décrit comment configurer le débogage 2PF à l’aide de l’utilitaire kdnet.exe.
Les fournisseurs de cartes réseau sont encouragés à activer la prise en charge de cette fonctionnalité. Pour plus d’informations, consultez le support du pilote réseau miniport KDNET 2PF du débogueur.
Exigences de l’appareil 2PF en mode noyau
Le pilote de boîte de réception Windows s’enfuit du port réseau principal à bus.dev.fun0.0 emplacement PCI.
Le module KDNET-Ext. va manquer du PF ajouté à bus.dev.fun0.1 Cette technique garantit que le pilote de carte réseau de boîte de réception Windows n’est pas affecté par le partage de la carte réseau avec KDNET.
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.
Configuration requise pour l’appareil 2PF en mode noyau
Ce qui suit est nécessaire :
Sur l’ordinateur cible, une carte réseau 2PF prise en charge.
Sur l’ordinateur hôte, une carte réseau.
Une connexion réseau entre la cible et l’hôte.
Windows 10 Build 21313 et ultérieur.
Cartes réseau 2PF prises en charge
Des fournisseurs comme NVIDIA Mellanox et Cisco fournissent des NICs qui prennent en charge le débogage réseau 2PF. Vérifiez auprès du fournisseur de la carte réseau pour voir quels modèles de carte réseau sont pris en charge. Notez que certains fournisseurs supportent le 2PF sur un sous-ensemble de cartes réseau qui partagent le même ID PnP.
Utilisez kdnet.exe pour confirmer le support de l’appareil et voir la valeur des busparams.
Utilisez l’utilitaire kdnet.exe pour afficher les informations de paramètre pour les contrôleurs qui prennent en charge le débogage de transport KDNET 2PF.
Confirmez que les outils de débogage Windows sont installés sur le système hôte. Pour des informations sur le téléchargement et l’installation des outils de débogage, consultez la rubrique Outils de débogage pour Windows.
Localisez les fichiers kdnet.exe et VerifiedNICList.xml. Par défaut, ils se trouvent ici.
C:\Program Files (x86)\Windows Kits\10\Debuggers\x64Sur l’ordinateur hôte, copiez les deux fichiers sur un partage réseau ou une clé USB, afin qu’ils soient disponibles sur l’ordinateur cible.
Sur l’ordinateur cible, créez un répertoire
C:\KDNETet copiez les fichiers kdnet.exe et VerifiedNICList.xml dans ce répertoire.Sur l’ordinateur cible, ouvrez une fenêtre d’invite de commande en tant qu’administrateur. Saisissez cette commande pour vérifier que l’ordinateur cible dispose d’un adaptateur réseau pris en charge et pour voir la valeur des busparams.
C:\KDNET>kdnet.exe Network debugging is supported on the following NICs: busparams=141.0.0, Mellanox ConnectX-4 Lx Ethernet Adapter #2, Plugged in, Primary function, multiple physical functions are supported. Network debugging is supported on the following USB controllers: busparams=128.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft) busparams=0.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft) busparams=128.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft) busparams=0.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)Comme la sortie ci-dessus n’inclut pas « KDNET fonctionne sur cette NIC. », cela indique que le débogage KDNET traditionnel n’est pas activé sur aucun des adaptateurs.
Si la NIC ne prend pas en charge la fonction PF multiple, alors la notification d’état PF de « plusieurs fonctions physiques sont prises en charge » sera omise (vide) des informations affichées.
Si la NIC prend en charge plusieurs PF, alors les informations affichées dépendront de la combinaison du port réseau (port racine/PF ajouté), ainsi que du statut du câble connecté/déconnecté au port physique de la NIC.
Ce tableau résume les différentes notifications PF pour la NIC principale.
Le bus de l’adaptateur NIC.dev.fun correspond à État du câble État PF original (principal) Câble PF connecté Fonction principale, plusieurs fonctions physiques sont activées original (principal) Câble PF déconnecté Fonction principale, plusieurs fonctions physiques sont prises en charge Ce tableau résume les différentes notifications PF pour la NIC secondaire.
Le bus de l’adaptateur NIC.dev.fun correspond à État du câble État PF nouveau port PF (secondaire) Kdnet est en cours d’exécution Fonction secondaire nouveau port PF (secondaire) câble déconnecté ou état inconnu Fonction principale, plusieurs fonctions physiques sont activées, mais la fonction secondaire n’est pas utilisée Si la sortie de kdnet.exe indique qu’un contrôleur NIC pris en charge est disponible, nous pouvons poursuivre.
Configuration de l’ordinateur cible pour le 2PF
Utilisez l’utilitaire kdnet.exe pour configurer les paramètres du débogueur sur le PC cible pour le 2PF, en suivant cette procédure.
Important
Avant d’utiliser bcdedit pour modifier les informations de démarrage, vous devrez peut-être suspendre temporairement les fonctionnalités de sécurité de Windows telles que BitLocker et Secure Boot sur le PC de test. Vous pouvez réactiver BitLocker et Secure Boot une fois que vous avez fini d’utiliser BCDEdit pour mettre à jour les informations de démarrage. Gérez correctement le PC de test, lorsque les fonctionnalités de sécurité sont désactivées.
Ce processus ajoutera une nouvelle fonction physique (PF) à la NIC, spécifiée par bus.device.function. Le nouveau PF ne peut être utilisé que par KDNET puisque le pilote NIC inbox Windows est configuré pour ne pas fonctionner sur un PF secondaire ajouté. Suivez ces étapes pour ajouter un nouveau PF qui sera utilisé par le dispositif de débogage.
Confirmez que le débogage est désactivé avant d’ajouter la nouvelle fonction physique
- Utilisez la commande BCDEdit pour confirmer que le KD est désactivé sur la cible avant d’ajouter un nouveau PF sur la NIC. Cela est nécessaire pour s’assurer que le pilote NIC standard du fournisseur est chargé afin qu’il puisse être utilisé pour ajouter le nouveau PF.
C:\> bcdedit /enum
...
debug No
En alternative, utilisez kdnet.exe sans paramètres pour voir si le débogage est activé. La sortie ci-dessous montre KDNET fonctionnant sur un système avec le débogage activé sur une NIC. Il s’agit de la configuration héritée de moindre performance.
c:\Debuggers>kdnet
Network debugging is supported on the following NICs:
busparams=141.0.0, Mellanox ConnectX-4 Lx Ethernet Adapter #2, KDNET is running on this NIC.
Network debugging is supported on the following USB controllers:
busparams=128.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=128.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
- Si la valeur de débogage est définie sur Oui, utilisez la commande set pour désactiver le débogage.
C:\> bcdedit.exe /debug off
C:\> bcdedit.exe /set {default} bootdebug off
C:\> bcdedit.exe /set {bootmgr} bootdebug off
- Utilisez la commande
shutdown -r -t 0à partir d’une invite de commande d’administrateur pour redémarrer.
Après le redémarrage du PC cible, et le débogage désactivé, nous pouvons ajouter la nouvelle fonction physique.
Ajouter la nouvelle fonction physique
- Ouvrez une invite de commande élevée et exécutez la commande suivante pour ajouter un second PF. Toutes les valeurs sont fournies en valeurs décimales.
C:\KDNET> kdnet -addpf 141.0.0 198.51.100.1 50001
Succeeded adding a Pci PF on :141.0.1. Please power off or reboot the machine.
Enabling network debugging on Mellanox ConnectX-4 Lx Ethernet Adapter #2.
Manage-bde.exe not present. Bitlocker presumed disabled.
To debug this machine, run the following command on your debugger host machine.
windbg -k net:port=50001,key=2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
Then reboot this machine by running shutdown -r -t 0 from this command prompt.
bus.dev.fun est le port de localisation PCI de l’adaptateur NIC qui prend en charge la fonctionnalité PF multiple, donc le nouveau PF sera ajouté/attaché à ce dispositif réseau.
L’option -addpf active automatiquement le débogage du noyau sur le transport KDNET sur le port PF ajouté.
[host name/host ip address] est l’adresse TCP/IP de l’ordinateur hôte. Utilisez la commande ipconfig sur l’ordinateur hôte pour déterminer cette adresse.
[port number] est le numéro de port TCP/IP. Vous pouvez choisir n’importe quel numéro de port de 49152 à 65535. La plage recommandée est comprise entre 50000 et 50039. Le port que vous choisirez sera ouvert pour un accès exclusif par le débogueur fonctionnant sur l’ordinateur hôte. Choisissez une adresse de port unique pour chaque paire cible/hôte avec laquelle vous travaillez, dans la plage recommandée de 50000 à 50039. 50005 est montré dans l’exemple.
Notez que -addpf ajoutera également l’attribut NO_KDNIC à l’OS d’installation {default} dans les options de démarrage. Cela est dû au fait que KDNIC n’est plus nécessaire pour fonctionner sur KDNET.
Les options de démarrage = NO_KDNIC sont ajoutées au tag OS {default} pour garantir que kdnic.sys ne fonctionnera pas à partir du nouveau PF ajouté (141.0.1).
Utilisez la commande bcdedit pour confirmer que NO_KDNIC a été défini.
C:\KDNET> bcdedit /enum {default}
Windows Boot Loader
-------------------
identifier {current}
device partition=C:
path \Windows\system32\winload.efi
description Windows Server
locale en-US
loadoptions NO_KDNIC
inherit {bootloadersettings}
recoverysequence {c23c4005d-12ae-11eb-9399-ac9840c152e7}
displaymessageoverride Recovery
recoveryenabled Yes
bootdebug No
testsigning Yes
isolatedcontext Yes
flightsigning Yes
allowedinmemorysettings 0x15000075
osdevice partition=C:
systemroot \Windows
resumeobject {c23c4005d-12ae-11eb-9399-ac9840c152e7}
nx OptOut
debug Yes
hypervisordebug No
2. Run the bcdedit /enum command to display the generated key.
```console
C:\KDNET> bcdedit /dbgsettings
busparams 141.0.1
key 2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
debugtype NET
hostip 198.51.100.1
port 50001
dhcp Yes
The operation completed successfully.
Copiez la clé retournée dans un fichier .txt du bloc-notes. Dans l’exemple montré, la clé générée a une valeur de :
2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874pUtilisez kdnet.exe pour confirmer que les multiples fonctions physiques sont activées.
C:\KDNET> kdnet.exe
Network debugging is supported on the following NICs:
busparams=141.0.0, Mellanox ConnectX-4 Lx Ethernet Adapter #2, Plugged in, Primary function, multiple physical functions are enabled.
busparams=141.0.1, Mellanox ConnectX-4 Lx Ethernet Adapter, KDNET is running on this NIC, Secondary function.
Network debugging is supported on the following USB controllers:
busparams=128.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=128.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
Désactivez le pare-feu sur l’hôte
Sur l’hôte, désactivez le pare-feu pour le port du débogueur.
Connexion de WinDbg à la cible pour le débogage du noyau
Sur l’ordinateur hôte, ouvrez WinDbg. Dans le menu Fichier, choisissez Débogage du noyau. Dans la boîte de dialogue de débogage du noyau, ouvrez l’onglet Net. Collez votre numéro de port et la clé que vous avez enregistrée dans le fichier .txt du bloc-notes plus tôt. Cliquez sur OK.
Vous pouvez également démarrer une session WinDbg en ouvrant une fenêtre d’invite de commande et en entrant la commande suivante, où est le port que vous avez sélectionné ci-dessus, et est la clé retournée par kdnet.exe ci-dessus. Collez la clé que vous avez enregistrée dans le fichier .txt du bloc-notes plus tôt.
windbg -k -d net:port=<YourDebugPort>,key=<YourKey>
Redémarrez l’ordinateur cible
Une fois le débogueur connecté, redémarrez l’ordinateur cible. Un moyen de redémarrer le PC est d’utiliser la commande shutdown -r -t 0 à partir d’une invite de commande d’administrateur.
Après le redémarrage de l’ordinateur cible, le débogueur devrait se connecter automatiquement.
Une fois la machine redémarrée, le firmware NIC attribuera une nouvelle adresse MAC au nouveau PF KDNET ajouté, et dbgsettings::busparams pointeront vers le nouveau PF ajouté.
Trouver l’adresse MAC pour l’adaptateur 2PF
Puisque le nouveau PF ajouté est un port configuré par le bus PCI, une nouvelle valeur d’adresse MAC sera attribuée au nouveau PF ajouté par le firmware NIC. L’outil kdnet.exe ne prend actuellement pas en charge l’affichage de l’adresse MAC pour le 2PF ajouté.
Il existe deux manières de trouver la nouvelle adresse MAC :
Utilisez WinDbg/KD avec une session KD locale
Exécutez le débogueur du noyau local windbg.exe -kl sur la cible.
Assurez-vous d’avoir accès au fichier de symboles kdnet.pdb en exécutant .reload /f kdnet.dll
Exécutez la commande .kdtargetmac pour obtenir l’adresse MAC.
kd> .kdtargetmac
Force unload of kdnet.dll
ModLoad: fffff800`18510000 fffff800`18557000 kdnet.dll
Loading symbols for fffff800`18510000 kdnet.dll -> kdnet.dll
The target machine MAC address in open-device format is: DC9840C151E8
Exécutez les outils de firmware fournis par le fournisseur
Une façon de localiser l’adresse MAC est d’exécuter les outils de firmware fournis par le fournisseur. Reportez-vous au fournisseur NIC pour des informations sur le téléchargement, l’installation et l’utilisation des outils du fournisseur.
...
Base MAC: 98039baa757c 4
Trouvez le champ d’adresse MAC. Calculez la valeur de l’adresse MAC KDNET 2PF en ajoutant séquentiellement un au dernier chiffre du dispositif MAC racine. Ainsi, pour le dispositif racine avec une adresse de 98039baa757c, le dispositif KDNET 2PF aurait une adresse de 98039baa757d.
Restauration de l’état de configuration précédent - Suppression du second PF PCI
Vous pouvez retirer le PF précédemment ajouté d’un dispositif en utilisant l’option kdnet -removepf et la valeur originale bus.device.function. Le PF sera détaché de la NIC et la ressource attribuée au PF sera libérée par le firmware NIC.
Pour retirer le PF KDNET du dispositif, ouvrez une invite de commande élevée et exécutez la commande suivante.
kdnet -removepf [bus.dev.fun] [host name/host ip address] [port number]
Où bus.dev.fun est le port de localisation PCI de l’adaptateur NIC où le PF était initialement attaché. C’est la même localisation PCI initialement passée à kdnet -addpf.
L’utilisation de l’option -removepf réactive également le débogage du noyau sur KDNET sur le bus.dev.fun original.
C:\KDNET> kdnet -removepf 141.0.0 198.51.100.1 50001
Succeeded removing a Pci PF on :141.0.0. Please power off or reboot the machine.
Enabling network debugging on Mellanox ConnectX-4 Lx Ethernet Adapter #2.
Manage-bde.exe not present. Bitlocker presumed disabled.
La commande kdnet.exe -removepf supprimera également l’attribut NO_KDNIC des options de démarrage de l’installation OS {default}, puisque KDNET sera activé sur le bus.dev.fun original, c’est-à-dire que dbgsettings::busparams pointeront vers le port réseau original. Cela causera à KDNIC d’être utilisé à nouveau, fournissant à nouveau une connexion réseau sur KDNET.
Une fois le PF retiré, la machine doit être redémarrée pour que les changements BCD soient appliqués.
shutdown -r -t 0
Dépannage de la configuration de l’adaptateur
hôte Vérifiez que l’adaptateur 2PF est présent dans le gestionnaire de périphériques
Vous pouvez vérifier que le PF KDNET a été ajouté avec succès en vérifiant le nouvel adaptateur NIC a un nouveau port bus.dev.fun sur la liste des adaptateurs du gestionnaire de périphériques Windows.
Ce diagramme montre trois adaptateurs différents, avec l’adaptateur n°2 réservé à l’utilisation par le débogueur du noyau.
Messages d’erreur courants - ajout d’un nouveau PF
C:\KDNET> kdnet -addpf 28.0.0 192.168.137.1 50005
Device Name:\\.\Mlx5Util
Pci Bus:28.0.0
Le PF PCI est déjà configuré sur ce port : Erreur=(0x80004004) Opération PF échouée sur le dispositif de débogage. Le dispositif de débogage n’est pas configuré pour KDNET.
- Ne pas ajouter/retirer un PF sur le port racine où il est déjà ajouté en tant que PF.
Messages d’erreur courants - retrait d’un PF
C:\KDNET> kdnet -removepf 28.0.1 192.168.137.1 50005
Adapter is not active: Error=(0x80070002)
Device Name:\\.\Mlx5Util
Pci Bus:28.0.1
L’adaptateur n’est pas actif : Erreur=(0x80070002) Opération PF échouée sur le dispositif de débogage. Le dispositif de débogage n’est pas configuré pour KDNET
- N’utilisez pas un port PF ajouté avec le paramètre de ligne de commande « -removepf/-addpf », car toute opération sur le port PF ajouté entraînera un échec (erreur : l’adaptateur n’est pas actif sur le port), puisque le pilote NIC inbox du fournisseur est configuré pour expressément ne pas fonctionner sur un PF ajouté.
- Les deux options de ligne de commande (-addpf/-removepf) doivent être utilisées uniquement sur le dispositif PCI racine.
C:\KDNET> kdnet -removepf 28.0.0 192.168.137.1 50005
Device Name:\\.\Mlx5Util
Pci Bus:28.0.0
Il n’y a pas de PF PCI à retirer sur ce port : Erreur=(0x80004005) Opération PF échouée sur le dispositif de débogage. Le dispositif de débogage n’est pas configuré pour KDNET
- Si vous ajoutez un nouveau PF puis décidez de le retirer sans redémarrer, cela entraînera un échec, car le firmware NIC du fournisseur nécessite le redémarrage/la réinitialisation du matériel NIC avant de pouvoir reconnaître le nouveau PF ajouté.
Messages d’erreur courants - BCDEdit
NO_KDNIC n’est pas présent dans l’installation OS BCD {default}.
- Il n’est pas recommandé d’utiliser bcdedit.exe pour modifier/changer le dispositif de débogage (dbgsettings) après l’ajout d’un nouveau PF. Les options de ligne de commande kdnet -addpf/removepf configureront le dispositif de débogage et ajouteront/supprimeront également automatiquement le
NO_KDNICjeton de/vers le{default}::loadoptions.
Voir aussi
Configuration automatique du débogage du noyau réseau KDNET
Configuration manuelle du débogage du noyau réseau KDNET
Configuration du débogage en mode noyau USB 3.0 xHCI-DBC (KDUSB)
Configuration du débogage en mode noyau EEM DE KDNET USB (KDNET-EEM-USB)