Einrichten des KDNET USB-Kernelmodusdebuggings (KDNET-USB)

Artikel
10/31/2024

Das Debuggen von Tools für Windows unterstützt das Debuggen im Kernelmodus über ein USB 3.0-Kabel mit KDNET über USB. In diesem Artikel wird beschrieben, wie Sie diese Transportoption konfigurieren.

Der Computer, auf dem der Debugger ausgeführt wird, wird als Hostcomputer bezeichnet, und der Computer, der debugged wird, wird als Zielcomputer bezeichnet.

Für das Debuggen über ein USB 3.0-Kabel ist die folgende Hardware erforderlich:

Auf dem Hostcomputer gibt es einen xHCI USB 3.0+-Hostcontroller und einen USB3-Anschluss.
Auf dem Zielcomputer gibt es einen xHCI USB 3.0+-Hostcontroller und einen USB3-Anschluss, der das Debuggen (DBC) unterstützt.
Der USB-Hostcontroller des Zielcomputers muss die Intel xHCI Debug Capability Interface (DBC) unterstützen. Weitere Informationen finden Sie in der xHCI-Spezifikation auf der Intel-Website.

Binärtransportdateien

Die kdstub.dll und kdnic.sys Treiber werden verwendet, um den KDNET-USB-Debuggertransport zu unterstützen.

Kabelanforderungen

Ein orangefarbenes Microsoft USB-Debugkabel, bei dem es sich um ein A-A-Crossover-Kabel handelt, das über zwei steckerartige Typ-A-Stecker und keine Vbus-Verbindung verfügt. Dieses Kabel ist von Anbietern wie DataPro - USB 3.0 Super-Speed A/A Debugging Kabel erhältlich.
Zum Verbinden des Hosttyps A mit dem Zieltyp C ist ein Standardmäßiger USB 3.0 Typ C-Adapter erforderlich.

Um die Problembehandlung zu vereinfachen, verbinden Sie das Kabel direkt zwischen Dem Ziel- und Hostcomputer, und vermeiden Sie Hubs oder Dockingstationen.

Einrichten des Zielcomputers

Suchen Sie auf dem Zielcomputer das UsbView-Tool, und starten Sie es. Das UsbView-Tool ist in debugtools für Windows enthalten. Bei einem x64-System befindet sich UsbView in C:\Programme (x86)\Windows Kits\10\Tools\KitVersion\x64\usbview.exe.
Suchen Sie in UsbView alle xHCI-Hostcontroller.

Erweitern Sie in UsbView die Knoten der xHCI-Hostcontroller. Suchen Sie nach einem Hinweis, dass ein Port auf dem Hostcontroller das Debuggen unterstützt.

[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

Notieren Sie sich die Bus-, Geräte- und Funktionsnummern für den xHCI-Controller, den Sie für das Debuggen verwenden möchten. UsbView zeigt diese Nummern an. Im folgenden Beispiel ist die Busnummer 48, die Gerätenummer 0 und die Funktionsnummer 0.
```
USB xHCI Compliant Host Controller
...
DriverKey: {36fc9e60-c465-11cf-8056-444553540000}\0020
...
Bus.Device.Function (in decimal): 48.0.0
```
Wenn Sie die Busparameter bestätigen müssen, verwenden Sie Geräte-Manager. Suchen Sie in Geräte-Manager den USB-Controller, den Sie für das Debuggen verwenden möchten. Unter "Position " auf der Registerkarte "Allgemein " werden die Bus-, Geräte- und Funktionsnummern angezeigt. b, d und f sind die Bus-, Geräte- und Funktionsnummern für den USB3-Hostcontroller. Die Bus-, Geräte- und Funktionsnummern müssen im Dezimalformat vorliegen.

Sie können auch kdnet.exe verwenden, um Informationen zum USB-Controller zu sammeln.

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.

Nachdem Sie einen xHCI-Controller identifiziert haben, der das Debuggen unterstützt, besteht der nächste Schritt darin, den physischen USB-Anschluss zu finden, der einem Port auf dem xHCI-Controller zugeordnet ist. Um den physischen Anschluss zu finden, schließen Sie ein beliebiges USB 3.0-Gerät an einen beliebigen USB-Anschluss auf dem Zielcomputer an. Aktualisieren Sie USBView, um zu sehen, wo sich Ihr Gerät befindet. Wenn UsbView Ihr Gerät anzeigt, das mit Ihrem ausgewählten xHCI-Hostcontroller verbunden ist, haben Sie einen physischen USB-Anschluss gefunden, den Sie für das USB 3.0-Debugging verwenden können.

Wichtig

Bevor Sie Startinformationen mithilfe bcdedit oder kdnet.exe ändern, müssen Sie möglicherweise vorübergehend Windows-Sicherheitsfeatures wie BitLocker und sicherer Start auf dem Test-PC anhalten. Aktivieren Sie diese Sicherheitsfunktionen wieder, wenn die Tests abgeschlossen sind, und verwalten Sie den Test-PC angemessen, wenn die Sicherheitsfunktionen deaktiviert sind.

Wählen Sie ein eindeutiges <port address> Ziel-/Hostpaar aus, mit dem Sie arbeiten, innerhalb des empfohlenen Bereichs von 50000-50039. 50005 wird in den folgenden Beispielen gezeigt.
Suchen Sie das Hilfsprogramm KDNet.exe im WDK-Debuggerverzeichnis, das Ihrem CPU-Typ entspricht, z. B. x64.
Öffnen Sie auf dem Zielcomputer ein Eingabeaufforderungsfenster als Administrator, und geben Sie diesen Befehl ein, um das Kerneldebugging mit -k Option zu aktivieren. Mit "-w", "-b" und "-h" wird das Kerneldebugging für Winload-, Bootmgr- und Hypervisor-Systemanwendungen aktiviert. Weitere Informationen zu den WinDbg-Optionen finden Sie unter WinDbg – Befehlszeilenstartoptionen.
```
kdnet.exe 169.254.255.255 50005 -k
```
- 169.254.255.255 die nicht routingfähige link-lokale statische IP-Adresse muss für KDNET über USB3 verwendet werden.
- kdnet.exe gibt einen Schlüssel w.x.y.z zurück, der von WinDbg zum Herstellen einer Verbindung mit dem Zielgerät verwendet wird.
Verwenden Sie den Parameter "-busparams ", um einen bestimmten USB-Anschluss zu verwenden.
```
kdnet.exe -busparams 0.13.0 169.254.255.255 50005 -k
```
Die Verwendung des KDNET-Hilfsprogramms wird empfohlen. Dieses Tool legt Optionen fest, die komplizierter für die Verwendung von bcdedit festgelegt werden können, sowie das Überprüfen und Festlegen von unterstützenden Registrierungswerten für PCI- und Energieverwaltung.
```
bcdedit /dbgsettings NET hostip:169.254.255.255 port:50001 key:1.2.3.4 busparams:0.20.0 noDhcp
```

Energieverwaltung deaktivieren

In einigen Fällen können Stromübergänge das Debuggen über USB 3.0 beeinträchtigen. Um diese Probleme zu vermeiden, deaktivieren Sie das selektive Anhalten für den xHCI-Hostcontroller und dessen Stammhub, den Sie zum Debuggen verwenden.

Navigieren Sie in Geräte-Manager zum Knoten für den xHCI-Hostcontroller. Klicken Sie mit der rechten Maustaste auf den Knoten, und wählen Sie "Eigenschaften" aus. Wenn es eine Power Management-Registerkarte gibt, öffnen Sie die Registerkarte, und deaktivieren Sie den Computer zum Deaktivieren dieses Geräts zum Speichern des Stromkontrollkästchens .
Navigieren Sie in Geräte-Manager zum Knoten für den Stammhub des xHCI-Hostcontrollers. Klicken Sie mit der rechten Maustaste auf den Knoten, und wählen Sie "Eigenschaften" aus. Wenn es eine Power Management-Registerkarte gibt, öffnen Sie die Registerkarte, und deaktivieren Sie das Kontrollkästchen "Computer zulassen", um dieses Gerät zu deaktivieren .

Wenn Sie mit der Verwendung des xHCI-Hostcontrollers zum Debuggen fertig sind, aktivieren Sie das selektive Anhalten für den xHCI-Hostcontroller erneut.

Starten einer Debugsitzung mit WinDbg

Schließen Sie ein USB 3.0-Debugkabel an die identifizierten USB 3.0-Ports an, die Sie für das Debuggen auf dem Host- und Zielcomputer ausgewählt haben.
Öffnen Sie auf dem Hostcomputer eine Version von WinDbg (als Administrator), die der Bitanzahl von Windows entspricht, die auf dem Hostcomputer ausgeführt wird. Wenn beispielsweise der Hostcomputer eine 64-Bit-Version von Windows ausführt, öffnen Sie die 64-Bit-Version von WinDbg als Administrator.
Wählen Sie im Menü "Datei " die Option "An Kernel anhängen" aus. Öffnen Sie im Dialogfeld "Kerneldebugging" die Registerkarte "Net ". Geben Sie die folgenden Informationen ein, und klicken Sie auf "OK".
- Das <port address> für jedes Ziel-/Hostpaar eindeutig ist und sich innerhalb des empfohlenen Bereichs von 50000-50039 befindet, wurde als Eingabe bereitgestellt, wenn kdnet.exe ausgeführt wurde.
- Die <session key> w.x.y.z, die generiert wurde, als kdnet.exe ausgeführt wurde und der Wert in der Befehlsausgabe angezeigt wurde.

Befehlszeilensitzung mit WinDbg

Sie können eine Sitzung auch mit WinDbg starten, indem Sie diesen Befehl in ein Eingabeaufforderungsfenster eingeben.

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

Starten Sie den Zielcomputer neu.

Sobald der Debugger geladen und einsatzbereit ist, starten Sie den Zielcomputer neu. Eine Möglichkeit, den PC neu zu starten, besteht darin, den Befehl über die shutdown -r -t 0 Eingabeaufforderung eines Administrators zu verwenden.

Nach dem Neustart des Ziel-PCs sollte der Debugger automatisch eine Verbindung herstellen.

Problembehandlung

USB-Gerät nicht erkannt

Wenn eine Windows-Benachrichtigung auf dem Host mit dem Text-USB-Gerät beim Einfügen des Debugkabels nicht erkannt wird, ist es möglich, dass ein bekanntes USB 3.1 bis 3.1-Kompatibilitätsproblem erreicht wird. Dieses Problem betrifft Debugkonfigurationen, wenn das Debugkabel an einen USB 3.1-Controller auf dem Host angeschlossen ist, und einen Intel (Ice Lake oder Tiger Lake) 3.1-USB-Controller auf dem Ziel.

Weitere Informationen und Auftragsverarbeitermodellauflistungen finden Sie unter Ice Lake (Mikroprozessor) und Tiger Lake (Mikroprozessor). Um das Prozessormodell des Zielcomputers zu finden, öffnen Sie die Einstellungs-App, und wechseln Sie zu "System" und dann "Info". Der Prozessor wird unter Gerätespezifikationen aufgeführt.

Um dieses Problem zu überprüfen, öffnen Sie Geräte-Manager, und suchen Sie unter universellen seriellen Bus-Controllern nach USB-Debugverbindungsgerät. Wenn dieses Gerät nicht gefunden werden kann, suchen Sie unter "Andere Geräte" nach einem unbekannten Gerät. Klicken Sie mit der rechten Maustaste auf das Gerät, um die Eigenschaftenseite zu öffnen. Das Textfeld für den Gerätestatus weist den Text auf, den Windows dieses Gerät beendet hat, da es Probleme (Code 43) gemeldet hat und das USB-Gerät einen ungültigen USB BOS-Deskriptor zurückgegeben hat.

Um dieses Problem zu umgehen, führen Sie die folgenden Befehle an einer Administrator-Eingabeaufforderung aus, um Änderungen an der Registrierung vorzunehmen:

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

Achten Sie beim direkten Bearbeiten der Registrierung darauf, dass falsche Änderungen zu Systeminstabilität führen können.

Verbindungsversuche von Nachrichten in den Debuggerkonsolenfenstern und können nicht in das Ziel unterteilt werden – SkipPciProbeDebugDevice

Wenn die folgende Meldung in der KDNET-Debuggerkonsole auftritt, kann keine Unterbrechung in das Ziel initiiert werden oder Probleme mit bestimmten Befehlen auftreten (z. B. kdfiles), kann es daran liegen, dass KDNET ein out-of-sequence-Pingpaket empfängt.

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

Dieses Problem kann auftreten, da der pci.sys Treiber das Debuggerät probiert. Um diese Fehlermeldungen zu beseitigen, erstellen Sie den folgenden Registrierungseintrag auf dem ZIELgerät an einer Administrator-Eingabeaufforderung.

Diese Einstellung kann auch zulassen, dass der Debugger eine Verbindung herstellen kann, wenn der anfängliche KD-Transport beim Start nicht verbunden werden konnte, z. B. wenn das Debuggerät beim Start nicht konfiguriert werden konnte.

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

Starten Sie dann den Zielcomputer neu.

shutdown /r /t 0

Sobald das Gerät neu gestartet wird, sollten die Fehler verschwinden, und Befehle sollten wie erwartet funktionieren.

NO_KDNIC Einstellung für verbesserte Leistung und Zuverlässigkeit

Wenn eine Ethernet-NIC auf dem Ziel-PC installiert ist, können durch Festlegen der NO_KDNIC Option zusätzliche Zuverlässigkeits- und Leistungsverbesserungen erzielt werden.

bcdedit /set {current} loadoptions NO_KDNIC

Das Hinzufügen NO_KDNIC ist optional und kann nur verwendet werden, wenn das Ziel über einen zusätzlichen NIC-, WLAN- oder USB-Anschluss verfügt, um einen USB-Ethernet-Adapter zu verbinden, um netzwerkzugriff auf Windows zu ermöglichen.

Durch das Hinzufügen NO_KDNIC wird verhindert, dass der kdnic.sys Treiber (ein miniport-timerbasierter Treiber) über KDNET ausgeführt wird, was bedeutet, dass Windows TCP/IP-Datenverkehr nicht über den KDNET-Transport weitergeleitet wird. Anschließend kann der KDNET-Transport nur verwendet werden, um Debugging-bezogene Pakete zwischen dem Ziel-KDNET und dem Hostdebugger weiterzuleiten.

Dies kann bei der Netzwerkleistung helfen, die betroffen sein kann, wenn kdnic.sys Treiber über kdnet ausgeführt wird. In dieser Situation wechselt das Ziel nie in den Ruhezustand, verhindert Stromdiptests oder Verzögerungen beim Zugriff auf das Ziel über RDP. Dies liegt daran, dass die KDNET-Schnittstelle sowohl Debuggerpakete als auch Windows TCP/IP-Netzwerkpakete weiterleiten muss, wenn kdnic.sys ausgeführt wird.