Konfigurowanie debugowania trybu jądra USB KDNET (KDNET-USB)

Narzędzia debugowania dla systemu Windows obsługują debugowanie w trybie jądra przez kabel USB 3.0 przy użyciu KDNET przez USB. W tym artykule opisano sposób konfigurowania tej opcji transportu.

Komputer z uruchomionym debugerem jest nazywany komputerem hosta , a debugowany komputer jest nazywany komputerem docelowym .

Debugowanie przez USB 3.0 wymaga następującego sprzętu:

• Na komputerze głównym kontroler xHCI USB 3.0+ oraz port USB3.
• Na komputerze docelowym kontroler hosta xHCI USB 3.0 lub nowszy oraz port USB3 obsługujący debugowanie (DBC)
• Kontroler hosta USB komputera docelowego musi obsługiwać interfejs funkcji debugowania Intel xHCI (DBC). Aby uzyskać więcej informacji, zobacz specyfikację xHCI dostępną w witrynie sieci Web firmy Intel.

Pliki transportu binarnego

Sterowniki kdstub.dll i kdnic.sys są używane do obsługi transportu debugera KDNET-USB.

Wymagania dotyczące kabli

• Pomarańczowy debugowania USB firmy Microsoft, który jest krzyżowym A-A, który ma dwa męskie wtyczki typu A i bez połączenia Vbus. Ten jest dostępny od dostawców, takich jak DataPro - USB 3.0 Super-Speed A/A Cable debugowania.

• Do podłączenia portu typu A hosta do portu docelowego typu C wymagany jest standardowy adapter USB 3.0 z typu C do typu A.

Aby uprościć rozwiązywanie problemów, podłącz kabel bezpośrednio między komputerem docelowym a komputerem hosta, unikając wszelkich koncentratorów lub stacji dokujących.

Konfigurowanie komputera docelowego

1. Na komputerze docelowym znajdź i uruchom narzędzie UsbView . Narzędzie UsbView jest dołączone do narzędzi debugowania dla systemu Windows. W przypadku systemu x64 element UsbView znajduje się w C:\Program Files (x86)\Windows Kits\10\Tools\KitVersion\x64\usbview.exe.

2. W aplikacji UsbView znajdź wszystkie kontrolery hosta xHCI.

3. W aplikacji UsbView rozwiń węzły kontrolerów hosta xHCI. Poszukaj wskazania, że port na kontrolerze hosta obsługuje debugowanie.

   [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
   

4. Zanotuj numery magistrali, urządzenia i funkcji dla kontrolera xHCI, który ma być używany do debugowania. UsbView wyświetla te liczby. W poniższym przykładzie numer magistrali to 48, numer urządzenia to 0, a numer funkcji to 0.

   USB xHCI Compliant Host Controller
   ...
   DriverKey: {36fc9e60-c465-11cf-8056-444553540000}\0020
   ...
   Bus.Device.Function (in decimal): 48.0.0
   

5. Jeśli musisz potwierdzić parametry magistrali, użyj Menedżera urządzeń. W Menedżerze urządzeń znajdź kontroler USB, który ma być używany do debugowania. W obszarze Lokalizacja na karcie Ogólne wyświetlane są numery magistrali, urządzenia i funkcji. b, d i f to magistrala, urządzenie i numery funkcji dla kontrolera hosta USB3. Numery magistrali, urządzenia i funkcji muszą mieć format dziesiętny.

6. Można również użyć kdnet.exe, aby ułatwić zbieranie informacji o kontrolerze 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.
   

7. Po zidentyfikowaniu kontrolera xHCI obsługującego debugowanie następnym krokiem jest zlokalizowanie fizycznego łącznika USB skojarzonego z portem na kontrolerze xHCI. Aby znaleźć złącze fizyczne, podłącz dowolne urządzenie USB 3.0 do dowolnego łącznika USB na komputerze docelowym. Odśwież widok UsbView, aby zobaczyć, gdzie znajduje się urządzenie. Jeśli UsbView pokazuje, że urządzenie jest podłączone do wybranego kontrolera hosta xHCI, oznacza to, że znaleziono fizyczne złącze USB, którego można użyć do debugowania USB 3.0.

8. Wybierz unikatową <port address> dla każdej pary docelowej/hosta, z którą pracujesz, w zalecanym zakresie od 50000 do 50039. W poniższych przykładach pokazano 50005.

9. Znajdź narzędzie KDNet.exe w katalogu debugera WDK pasującego do typu procesora CPU, na przykład x64.

10. Na komputerze docelowym otwórz okno wiersza polecenia jako administrator i wprowadź to polecenie, aby włączyć debugowanie jądra z opcją -k . -w, -b i -h włączy debugowanie jądra dla aplikacji systemowych winload, bootmgr i hypervisor. Aby uzyskać więcej informacji na temat opcji WinDbg, zobacz WinDbg — opcje uruchamiania wiersza polecenia.

    kdnet.exe 169.254.255.255 50005 -k
    

    • 169.254.255.255 statyczny adres IP bez routingu-lokalny musi być używany dla sieci KDNET przez USB3.
    • kdnet.exe zwróci klucz w.x.y.z , który będzie używany przez windbg do nawiązania połączenia z urządzeniem docelowym.

    Aby użyć określonego portu USB, użyj parametru -busparams .

    kdnet.exe -busparams 0.13.0 169.254.255.255 50005 -k
    

    Zalecane jest użycie narzędzia KDNET. To narzędzie ustawia opcje, które są bardziej złożone do skonfigurowania przy użyciu bcdedit, oraz sprawdza i ustawia pomocnicze wartości rejestru dla PCI i zarządzania energią.

    bcdedit /dbgsettings NET hostip:169.254.255.255 port:50001 key:1.2.3.4 busparams:0.20.0 noDhcp
    

Wyłączanie zarządzania energią

W niektórych przypadkach przejścia zasilania mogą zakłócać debugowanie za pośrednictwem portu USB 3.0. Aby uniknąć tych problemów, wyłącz selektywne wstrzymanie dla kontrolera hosta xHCI i jego centrum głównego, którego używasz do debugowania.

1. W Menedżerze urządzeń przejdź do węzła głównego kontrolera xHCI. Kliknij prawym przyciskiem myszy węzeł i wybierz polecenie Właściwości. Jeśli istnieje karta Zarządzanie energią, otwórz kartę i wyczyść pole wyboru obok opcji Zezwalaj komputerowi na wyłączenie tego urządzenia w celu oszczędzania energii.

2. W Menedżerze urządzeń przejdź do węzła dla głównego centrum kontrolera hosta xHCI. Kliknij prawym przyciskiem myszy węzeł i wybierz polecenie Właściwości. Jeśli istnieje karta Zarządzanie energią, otwórz kartę i wyczyść pole wyboru Zezwól komputerowi na wyłączenie tego urządzenia w celu oszczędzania energii.

Po zakończeniu korzystania z kontrolera hosta xHCI do debugowania ponownie włącz selektywne wstrzymanie dla kontrolera hosta xHCI.

Rozpoczynanie sesji debugowania przy użyciu usługi WinDbg

1. Podłącz kabel debugowania USB 3.0 do zidentyfikowanych portów USB 3.0, które wybrałeś do debugowania na komputerze-hoście i komputerze docelowym.

2. Na komputerze-hoście otwórz wersję WinDbg (uruchomioną jako administrator), która odpowiada wersji bitowej systemu Windows działającego na komputerze-hostie. Jeśli na przykład na komputerze-hoście jest uruchomiona 64-bitowa wersja systemu Windows, otwórz 64-bitową wersję windbg jako administrator.

3. W menu Plik wybierz pozycję Dołącz do jądra. W oknie dialogowym Debugowanie jądra otwórz kartę Net. Wprowadź następujące informacje i kliknij OK.

   • Wartość <port address>, która jest unikatowa dla każdej pary docelowej/hosta i znajduje się w zalecanym zakresie 50000–50039, została podana jako dane wejściowe po uruchomieniu kdnet.exe.

   • Plik <session key> w.x.y.z, który został wygenerowany podczas uruchamiania kdnet.exe, a jego wartość wyświetlono w danych wyjściowych polecenia.

Sesja wiersza polecenia z WinDbg

Możesz również uruchomić sesję z windbg, wprowadzając to polecenie w oknie wiersza polecenia.

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

Ponowne uruchamianie komputera docelowego

Gdy debuger zostanie załadowany i będzie gotowy do użycia, uruchom ponownie komputer docelowy. Jednym ze sposobów ponownego uruchomienia komputera jest użycie shutdown -r -t 0 polecenia w wierszu polecenia administratora.

Po ponownym uruchomieniu komputera docelowego debuger powinien połączyć się automatycznie.

Rozwiązywanie problemów

Nie rozpoznano urządzenia USB

Jeśli na hoście pojawia się powiadomienie z tekstem urządzenie USB nierozpoznane po podłączeniu kabla do debugowania, możliwe, że występuje znany problem ze zgodnością między USB 3.1. Ten problem ma wpływ na konfiguracje debugowania, gdy kabel debugowania jest podłączony do kontrolera USB 3.1 na hoście i kontrolera USB Intel (Ice Lake lub Tiger Lake) 3.1 na celu.

Aby uzyskać więcej informacji i listy modeli procesora, zobacz Ice Lake (mikroprocesor) i Tiger Lake (mikroprocesor). Aby znaleźć model procesora maszyny docelowej, otwórz aplikację Ustawienia i przejdź do pozycji System , a następnie pozycję Informacje. Procesor jest wymieniony w obszarze Specyfikacje urządzeń.

Aby zweryfikować ten problem, otwórz Menedżera urządzeń i poszukaj urządzenia Połączenie debugowania USB w sekcji Kontrolery uniwersalnej magistrali szeregowej. Jeśli nie można odnaleźć tego urządzenia, sprawdź nieznane urządzenie w obszarze Inne urządzenia. Kliknij prawym przyciskiem myszy urządzenie, aby otworzyć jego stronę właściwości. W polu tekstowym Stan urządzenia zostanie wyświetlony tekst Zatrzymano to urządzenie przez system Windows, ponieważ zgłosił problemy (kod 43), a urządzenie USB zwróciło nieprawidłowy deskryptor USB BOS.

Aby obejść ten problem, uruchom następujące polecenia w wierszu polecenia administratora, aby wprowadzić zmiany w rejestrze:

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

Należy zachować ostrożność podczas bezpośredniej edycji rejestru, ponieważ nieprawidłowe zmiany mogą prowadzić do niestabilności systemu.

Komunikaty o ponawianiu prób połączenia w oknach konsoli debugera i nie można uzyskać dostępu do celu — SkipPciProbeDebugDevice

Jeśli w konsoli debugera KDNET pojawi się następujący komunikat, nie można rozpocząć interakcji z obiektem docelowym lub napotykasz problemy z niektórymi poleceniami (np. kdfiles), może to być spowodowane odebraniem pakietu ping poza sekwencją.

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

Ten problem może wystąpić, ponieważ sterownik pci.sys sonduje urządzenie debugowania. Aby wyeliminować te komunikaty o błędach, utwórz następujący wpis rejestru na urządzeniu DOCELOWYM w wierszu polecenia administratora.

To ustawienie może również umożliwić debugerowi nawiązanie połączenia, jeśli początkowy transport KD nie może nawiązać połączenia podczas rozruchu, z jakiegoś innego powodu, na przykład jeśli nie można skonfigurować urządzenia debugowania podczas rozruchu.

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

Następnie uruchom ponownie maszynę docelową.

shutdown /r /t 0

Po ponownym uruchomieniu urządzenia błędy powinny zniknąć, a polecenia powinny działać zgodnie z oczekiwaniami.

Ustawienie NO_KDNIC dla zwiększonej wydajności i niezawodności

Jeśli karta sieciowa Ethernet jest zainstalowana na komputerze docelowym, można osiągnąć dodatkowe ulepszenia niezawodności i wydajności, ustawiając NO_KDNIC opcję.

bcdedit /set {current} loadoptions NO_KDNIC

Dodawanie NO_KDNIC jest opcjonalne i może być używane tylko wtedy, gdy urządzenie docelowe ma dodatkową kartę sieciową, Wi-Fi lub port USB do podłączenia adaptera USB-Ethernet, aby zapewnić dostęp do sieci dla systemu Windows.

Dodanie NO_KDNIC uniemożliwi działanie sterownika kdnic.sys (sterownika opartego na czasomierzu miniportu) na KDNET, co powoduje, że ruch TCP/IP systemu Windows nie będzie kierowany za pośrednictwem transportu KDNET. Następnie transport KDNET może służyć tylko do kierowania pakietów związanych z debugowaniem między docelową siecią KDNET a debugerem hosta.

Może to pomóc w wydajności sieci, która może mieć wpływ, gdy sterownik kdnic.sys jest uruchomiony w oparciu o kdnet. W takiej sytuacji urządzenie docelowe nigdy nie przejdzie w stan uśpienia, co uniemożliwia przeprowadzenie testów zużycia energii lub pojawią się opóźnienia podczas uzyskiwania dostępu do urządzenia za pośrednictwem protokołu RDP. Jest to spowodowane tym, że interfejs KDNET musi kierować zarówno pakiety debugera, jak i pakiety sieciowe TCP/IP systemu Windows po uruchomieniu kdnic.sys.

Automatyczne resetowanie kontrolera USB hosta

Czasami debuger może napotkać stan stosu USB, który może być spowodowany wcześniej niepowodzeniem wyliczenia USB. Spowoduje to niepowodzenie połączenia debugera z maszyną docelową nawet wtedy, gdy wszystkie ustawienia są poprawnie skonfigurowane.

W scenariuszach IC ten problem można obejść, ręcznie wyłączając\rwłączenie nadrzędnego kontrolera USB. W przypadku innych scenariuszy, takich jak zautomatyzowane laboratoria testowe, czynności ręczne, takie jak te, nie są możliwe. Po włączeniu RestartKdNetUsbDebugDevice tego ustawienia klient debugera automatycznie będzie monitorować wyliczenie USB, które zakończyło się niepowodzeniem i zresetować stos USB po wykryciu urządzenia. Umożliwi to debugerowi nawiązanie połączenia bez żadnej interwencji użytkownika. Ta funkcja jest wbudowana w aplikację kliencą debugera i jest aktywna tylko wtedy, gdy klient debugera jest uruchomiony, a ustawienie jest włączone.

Jak włączyć:

Opcja 1. W wierszu polecenia debugera uruchom następujące polecenie.

kd> dx Debugger.Settings.Debug.Advanced.RestartKdNetUsbDebugDevice=true

Opcja 2: W nowej aplikacji Windbg przejdź do pozycji "Plik" - "Ustawienia" -> "Ustawienia" -> "Ustawienia debugowania jądra" i kliknij pole wyboru "Włącz automatyczne resetowanie kontrolera USB hosta w razie potrzeby"., a następnie uruchom je normalnie w oknie dialogowym "Dołączanie do jądra".

Opcja 3. Utwórz (lub zmodyfikuj istniejący) plik config.xml, RestartKdNetUsbDebugDevice aby uwzględnić ustawienie. Plik config.xml jest ładowany z tego samego katalogu co aplikacja kliencka debugera, tj. kd.exe lub (starsza wersja) windbg.exe. Jeśli jeszcze go nie ma, utwórz nowy plik o nazwie config.xml z następującą zawartością:

<?xml version="1.0" encoding="utf-8"?>
<Settings Version="2">
  <Namespace Name="Debug">
    <Namespace Name="Advanced">
      <Setting Name="RestartKdNetUsbDebugDevice" Type="VT_BOOL" Value="true"></Setting>
    </Namespace>
  </Namespace>
</Settings>

Jeśli istnieje już config.xml, scal <Setting Name="RestartKdNetUsbDebugDevice" Type="VT_BOOL" Value="true"></Setting> element XML z węzłem Debug.Advanced w istniejącym dokumencie XML.

Zobacz też

Automatyczne konfigurowanie debugowania jądra sieci KDNET

Konfiguracja ręczna debugowania jądra sieci KDNET

Ręczne konfigurowanie debugowania w trybie jądra

Konfigurowanie debugowania trybu jądra USB 3.0 xHCI-DBC (KDUSB)

Konfigurowanie debugowania Kernel-Mode USB KDNET EEM (KDNET-EEM-USB)