Configurazione del debug in modalità kernel USB KDNET (KDNET-USB)

Articolo
10/31/2024

Gli strumenti di debug per Windows supportano il debug in modalità kernel su un cavo USB 3.0 tramite KDNET tramite USB. Questo articolo descrive come configurare questa opzione di trasporto.

Il computer che esegue il debugger viene chiamato computer host e il computer sottoposto a debug viene chiamato computer di destinazione.

Il debug su un cavo USB 3.0 richiede l'hardware seguente:

Nel computer host, un controller host USB 3.0+ xHCI e una porta USB3.
Nel computer di destinazione, un controller host USB 3.0+ xHCI e una porta USB3 che supporta il debug (DBC)
Il controller host USB del computer di destinazione deve supportare l'interfaccia DBC (Intel xHCI Debug Capability Interface). Per altre informazioni, vedere la specifica xHCI disponibile nel sito Web Intel.

File di trasporto binario

I driver kdstub.dll e kdnic.sys vengono usati per supportare il trasporto del debugger KDNET-USB.

Requisiti dei cavi

Un cavo di debug USB Microsoft arancione, che è un cavo crossover A-A che dispone di due plug di tipo A-A e nessuna connessione Vbus. Questo cavo è disponibile da fornitori come DataPro - USB 3.0 Super-Speed A/A Debugging Cable.
Per connettere il tipo di host A alla porta C del tipo C, è necessario un adattatore USB 3.0 standard per connettere il tipo host A alla porta C di destinazione.

Per semplificare la risoluzione dei problemi, collegare il cavo direttamente tra il computer di destinazione e host, evitando hub o ancoraggi.

Configurare il computer di destinazione

Nel computer di destinazione individuare e avviare lo strumento UsbView . Lo strumento UsbView è incluso in Strumenti di debug per Windows. Per un sistema x64, UsbView si trova in C:\Programmi (x86)\Windows Kits\10\Tools\KitVersion\x64\usbview.exe.
In UsbView individuare tutti i controller host xHCI.

In UsbView espandere i nodi dei controller host xHCI. Cercare un'indicazione che una porta nel controller host supporta il debug.

[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

Prendere nota dei numeri di bus, dispositivo e funzione per il controller xHCI che si intende usare per il debug. UsbView visualizza questi numeri. Nell'esempio seguente il numero dell'autobus è 48, il numero del dispositivo è 0 e il numero di funzione è 0.
```
USB xHCI Compliant Host Controller
...
DriverKey: {36fc9e60-c465-11cf-8056-444553540000}\0020
...
Bus.Device.Function (in decimal): 48.0.0
```
Se è necessario confermare i parametri del bus, usare Gestione dispositivi. In Gestione dispositivi individuare il controller USB che si intende usare per il debug. In Posizione nella scheda Generale vengono visualizzati il bus, il dispositivo e i numeri di funzione. b, d e f sono i numeri di bus, dispositivo e funzione per il controller host USB3. I numeri di bus, dispositivo e funzione devono essere in formato decimale.

È anche possibile usare kdnet.exe per raccogliere informazioni sul controller 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.

Dopo aver identificato un controller xHCI che supporta il debug, il passaggio successivo consiste nell'individuare il connettore USB fisico associato a una porta nel controller xHCI. Per trovare il connettore fisico, collegare qualsiasi dispositivo USB 3.0 in qualsiasi connettore USB nel computer di destinazione. Aggiornare UsbView per vedere dove si trova il dispositivo. Se UsbView mostra il dispositivo connesso al controller host xHCI scelto, è stato trovato un connettore USB fisico che è possibile usare per il debug USB 3.0.

Importante

Prima di usare bcdedit o kdnet.exe per modificare le informazioni di avvio, potrebbe essere necessario sospendere temporaneamente le funzionalità di sicurezza di Windows, ad esempio BitLocker e Avvio protetto nel PC di test. Riabilitare queste funzionalità di sicurezza al termine dei test e gestire in modo appropriato il PC di test quando le funzionalità di sicurezza sono disabilitate.

Selezionare un valore univoco <port address> per ogni coppia di destinazione/host con cui si lavora, all'interno dell'intervallo consigliato da 50000 a 50039. 50005 è illustrato negli esempi seguenti.
Individuare l'utilità KDNet.exe nella directory del debugger WDK corrispondente al tipo di CPU, ad esempio x64.
Nel computer di destinazione aprire una finestra del prompt dei comandi come amministratore e immettere questo comando per abilitare il debug del kernel con -k l'opzione . -w, -b e -h abiliterà il debug del kernel per applicazioni di sistema winload, bootmgr e hypervisor. Per altre informazioni sulle opzioni di WinDbg, vedere Opzioni di avvio di WinDbg - Riga di comando.
```
kdnet.exe 169.254.255.255 50005 -k
```
- 169.254.255.255 l'indirizzo IP statico locale non instradabile deve essere usato per KDNET su USB3.
- kdnet.exe restituirà una chiave w.x.y.z che verrà usata da WinDbg per connettersi al dispositivo di destinazione.
Per usare una porta USB specifica, usare il parametro -busparams .
```
kdnet.exe -busparams 0.13.0 169.254.255.255 50005 -k
```
È consigliabile usare l'utilità KDNET. Questo strumento imposta le opzioni più complesse da impostare usando bcdedit, nonché il controllo e l'impostazione dei valori del Registro di sistema di supporto per PCI e risparmio energia.
```
bcdedit /dbgsettings NET hostip:169.254.255.255 port:50001 key:1.2.3.4 busparams:0.20.0 noDhcp
```

Disabilitare il risparmio energia

In alcuni casi, le transizioni di alimentazione possono interferire con il debug tramite USB 3.0. Per evitare questi problemi, disabilitare la sospensione selettiva per il controller host xHCI e il relativo hub radice, che si sta usando per il debug.

In Gestione dispositivi passare al nodo per il controller host xHCI. Fare clic con il pulsante destro del mouse sul nodo e scegliere Proprietà. Se è presente una scheda Risparmio energia, aprire la scheda e deselezionare la casella di controllo Consenti al computer di spegnere il dispositivo per risparmiare energia .
In Gestione dispositivi passare al nodo per l'hub radice del controller host xHCI. Fare clic con il pulsante destro del mouse sul nodo e scegliere Proprietà. Se è presente una scheda Risparmio energia, aprire la scheda e deselezionare la casella di controllo Consenti al computer di spegnere il dispositivo per risparmiare energia .

Al termine dell'uso del controller host xHCI per il debug, riabilitare la sospensione selettiva per il controller host xHCI.

Avviare una sessione di debug con WinDbg

Connettere un cavo di debug USB 3.0 alle porte USB 3.0 identificate scelte per il debug nei computer host e di destinazione.
Nel computer host aprire una versione di WinDbg (come amministratore) che corrisponda al bit di Windows in esecuzione nel computer host. Ad esempio, se il computer host esegue una versione a 64 bit di Windows, aprire la versione a 64 bit di WinDbg come amministratore.
Scegliere Connetti al kernel dal menu File. Nella finestra di dialogo Debug kernel aprire la scheda Net . Immettere le informazioni seguenti e fare clic su OK.
- Che <port address> è univoco per ogni coppia di destinazione/host ed è compreso nell'intervallo consigliato 50000-50039, è stato fornito come input quando è stata eseguita kdnet.exe.
- W.x.y.z <session key> generato quando kdnet.exe è stato eseguito e il relativo valore è stato visualizzato nell'output del comando.

Sessione della riga di comando con WinDbg

È anche possibile avviare una sessione con WinDbg immettendo questo comando in una finestra del prompt dei comandi.

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

Riavviare il computer di destinazione

Una volta caricato il debugger e pronto per l'esecuzione, riavviare il computer di destinazione. Un modo per riavviare il PC consiste nell'usare il shutdown -r -t 0 comando dal prompt dei comandi di un amministratore.

Dopo il riavvio del PC di destinazione, il debugger dovrebbe connettersi automaticamente.

Risoluzione dei problemi

Dispositivo USB non riconosciuto

Se nell'host viene visualizzata una notifica di Windows con il dispositivo USB di testo non riconosciuto quando si inserisce il cavo di debug, è possibile che si verifichi un problema di compatibilità USB 3.1 da 3.1 a 3.1 noto. Questo problema influisce sulle configurazioni di debug quando il cavo di debug è connesso a un controller USB 3.1 nell'host e un controller USB Intel (Ice Lake o Tiger Lake) 3.1 sulla destinazione.

Per altre informazioni e elenchi di modelli di processore, vedere Ice Lake (microprocessore) e Tiger Lake (microprocessore). Per trovare il modello di processore del computer di destinazione, aprire l'app Impostazioni e passare a Sistema e quindi Informazioni su. Il processore è elencato in Specifiche del dispositivo.

Per verificare questo problema, aprire Gestione dispositivi e cercare Usb Debug Connection Device in Universal Serial Bus Controllers (Controller universali del bus seriale). Se il dispositivo non è stato trovato, verificare la presenza di un dispositivo sconosciuto in Altri dispositivi. Fare clic con il pulsante destro del mouse sul dispositivo per aprire la relativa pagina delle proprietà. La casella di testo stato del dispositivo avrà il testo Windows ha arrestato questo dispositivo perché ha segnalato problemi (Codice 43) e Il dispositivo USB ha restituito un descrittore USB BOS non valido.

Per risolvere questo problema, eseguire questi comandi da un prompt dei comandi dell'amministratore per apportare modifiche al Registro di sistema:

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

Prestare attenzione quando si modifica direttamente il Registro di sistema, poiché le modifiche non corrette possono causare instabilità del sistema.

La connessione ritenta i messaggi nelle finestre della console del debugger e non può accedere alla destinazione - SkipPciProbeDebugDevice

Se viene visualizzato il messaggio seguente nella console del debugger KDNET, non è possibile avviare un'interruzione nella destinazione o riscontrare problemi con determinati comandi (ad esempio, kdfile), potrebbe essere dovuto alla ricezione di un pacchetto ping out-of-sequence da parte di KDNET.

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

Questo problema può verificarsi perché il driver pci.sys esegue il probe del dispositivo di debug. Per eliminare questi messaggi di errore, creare la voce del Registro di sistema seguente nel dispositivo TARGET al prompt dei comandi dell'amministratore.

Questa impostazione può anche consentire al debugger di connettersi se il trasporto KD iniziale non è riuscito a connettersi all'avvio, per qualche altro motivo, ad esempio se non è stato possibile configurare il dispositivo di debug all'avvio.

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

Riavviare quindi il computer di destinazione.

shutdown /r /t 0

Dopo il riavvio del dispositivo, gli errori dovrebbero scomparire e i comandi dovrebbero funzionare come previsto.

NO_KDNIC impostazione per migliorare le prestazioni e l'affidabilità

Se nel PC di destinazione è installata una scheda di interfaccia di rete Ethernet, è possibile ottenere ulteriori miglioramenti a livello di affidabilità e prestazioni impostando l'opzione NO_KDNIC .

bcdedit /set {current} loadoptions NO_KDNIC

L'aggiunta NO_KDNIC è facoltativa e può essere usata solo se la destinazione ha una scheda di interfaccia di rete aggiuntiva, Wi-Fi o USB per connettere una scheda USB-Ethernet per fornire l'accesso alla rete a Windows.

L'aggiunta NO_KDNIC impedirà l'esecuzione del driver kdnic.sys (driver basato su timer miniport) su KDNET, ovvero il traffico TCP/IP di Windows non verrà instradato tramite il trasporto KDNET. Il trasporto KDNET può quindi essere usato solo per instradare i pacchetti correlati al debug tra la KDNET di destinazione e il debugger host.

Ciò può aiutare a migliorare le prestazioni di rete che possono essere influenzate quando kdnic.sys driver è in esecuzione su kdnet. In questa situazione la destinazione non passerà mai alla sospensione, impedendo i test di gocciolamento dell'alimentazione o si verificheranno ritardi durante l'accesso alla destinazione tramite RDP. Ciò è dovuto al fatto che l'interfaccia KDNET deve instradare sia i pacchetti di rete TCP/IP del debugger che i pacchetti di rete TCP/IP di Windows quando kdnic.sys è in esecuzione.