Настройка отладки в режиме ядра USB KDNET (KDNET-USB)

Статья
10/31/2024

Средства отладки для Windows поддерживают отладку в режиме ядра по кабелю USB 3.0 с помощью KDNET через USB. В этой статье описывается настройка этого параметра транспорта.

Компьютер, на котором выполняется отладчик, называется главным компьютером, а отлаживаемый компьютер называется целевым компьютером.

Для отладки по кабелю USB 3.0 требуется следующее оборудование:

На хост-компьютере контроллер узла xHCI USB 3.0+ и порт USB3.
На целевом компьютере контроллер узла xHCI USB 3.0+ и порт USB3, поддерживающий отладку (DBC)
Контроллер USB-узла целевого компьютера должен поддерживать интерфейс возможностей отладки Intel xHCI (DBC). Дополнительные сведения см. в спецификации xHCI, доступной на веб-сайте Intel.

Двоичные файлы транспорта

Драйвер kdstub.dll и kdnic.sys используются для поддержки транспорта отладчика KDNET-USB.

Требования к кабелю

Оранжевый кабель отладки Microsoft USB, который является кроссоверным кабелем A-A с двумя подключаемыми модулями типа A и без подключения Vbus. Этот кабель доступен от поставщиков, таких как DataPro - USB 3.0 Суперскоростной кабель A/A.
Для подключения порта узла типа A к порту C целевого типа C требуется стандартный адаптер USB 3.0 типа C.

Чтобы упростить устранение неполадок, подключите кабель непосредственно между целевым компьютером и узлом, избегая любых концентраторов или док-станций.

Настройка целевого компьютера

На целевом компьютере найдите и запустите средство UsbView . Средство UsbView включается в средства отладки для Windows. Для системы x64 UsbView будет находиться в C:\Program Files (x86)\Windows Kits\10\Tools\KitVersion\x64\usbview.exe.
В UsbView найдите все контроллеры узлов xHCI.

В UsbView разверните узлы контроллеров узлов xHCI. Найдите признак того, что порт на контроллере узла поддерживает отладку.

[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

Запишите номера шины, устройства и функции для контроллера xHCI, который планируется использовать для отладки. UsbView отображает эти числа. В следующем примере номер шины равен 48, номер устройства равен 0, а номер функции — 0.
```
USB xHCI Compliant Host Controller
...
DriverKey: {36fc9e60-c465-11cf-8056-444553540000}\0020
...
Bus.Device.Function (in decimal): 48.0.0
```
Если необходимо подтвердить параметры шины, используйте диспетчер устройств. В диспетчер устройств найдите USB-контроллер, который планируется использовать для отладки. В разделе "Расположение " на вкладке "Общие " отображаются номера шины, устройства и функции. b, d и f — это номера шины, устройства и функции для контроллера узла USB3. Номера шин, устройств и функций должны быть в десятичном формате.

Вы также можете использовать kdnet.exe для сбора сведений о 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.

После идентификации контроллера xHCI, поддерживающего отладку, необходимо найти физический USB-соединитель, связанный с портом на контроллере xHCI. Чтобы найти физический соединитель, подключите любое устройство USB 3.0 к любому USB-соединителю на целевом компьютере. Обновите UsbView, чтобы узнать, где находится ваше устройство. Если UsbView отображает устройство, подключенное к выбранному контроллеру узла xHCI, вы нашли физический USB-соединитель, который можно использовать для отладки USB 3.0.

Внимание

Прежде чем использовать bcdedit или kdnet.exe изменить сведения о загрузке, может потребоваться временно приостановить функции безопасности Windows, такие как BitLocker и безопасная загрузка на тестовом компьютере. Повторно включите эти функции безопасности при завершении тестирования и соответствующим образом управляйте тестируемым компьютером при отключении функций безопасности.

Выберите уникальную <port address> для каждой пары целевых и узлов, с которыми вы работаете, в рекомендуемом диапазоне от 50000 до 50039. 50005 показано в приведенных ниже примерах.
Найдите программу KDNet.exe в каталоге отладчика WDK, соответствующий типу ЦП, например x64.
На целевом компьютере откройте окно командной строки от имени администратора и введите эту команду, чтобы включить отладку ядра с -k параметром. Функция -w, -b и -h включает отладку ядра для winload, bootmgr и системных приложений гипервизора. Дополнительные сведения о параметрах WinDbg см. в разделе WinDbg — параметры запуска командной строки.
```
kdnet.exe 169.254.255.255 50005 -k
```
- 169.254.255.255 неизменяемый статический IP-адрес канала должен использоваться для KDNET через USB3.
- kdnet.exe возвращает ключ w.x.y.z , который будет использоваться WinDbg для подключения к целевому устройству.
Чтобы использовать определенный USB-порт, используйте параметр -busparams .
```
kdnet.exe -busparams 0.13.0 169.254.255.255 50005 -k
```
Рекомендуется использовать служебную программу KDNET. Это средство задает параметры, которые сложнее задать с помощью bcdedit, а также проверку и настройку вспомогательных значений реестра для pci и управления питанием.
```
bcdedit /dbgsettings NET hostip:169.254.255.255 port:50001 key:1.2.3.4 busparams:0.20.0 noDhcp
```

Отключение управления питанием

В некоторых случаях переходы питания могут препятствовать отладке через USB 3.0. Чтобы избежать этих проблем, отключите выборочную приостановку для контроллера узла xHCI и корневого концентратора, который используется для отладки.

В диспетчер устройств перейдите к узлу для контроллера узла xHCI. Щелкните узел правой кнопкой мыши и выберите пункт "Свойства". Если есть вкладка "Управление питанием", откройте вкладку и снимите флажок "Разрешить компьютеру отключить это устройство для сохранения питания".
В диспетчер устройств перейдите к узлу корневого концентратора контроллера узла xHCI. Щелкните узел правой кнопкой мыши и выберите пункт "Свойства". Если есть вкладка "Управление питанием", откройте вкладку и снимите флажок "Разрешить компьютеру отключить это устройство для сохранения питания".

После завершения использования контроллера узла xHCI для отладки повторно включите выборочную приостановку для контроллера узла xHCI.

Запуск сеанса отладки с помощью WinDbg

Подключите отладочный кабель USB 3.0 к указанным портам USB 3.0, выбранным для отладки на узлах и целевых компьютерах.
На хост-компьютере откройте версию WinDbg (как администратор), которая соответствует разрядности Windows, работающей на хост-компьютере. Например, если главный компьютер работает с 64-разрядной версией Windows, откройте 64-разрядную версию WinDbg от имени администратора.
В меню "Файл" выберите "Подключиться к ядру". В диалоговом окне отладки ядра откройте вкладку "Net ". Введите следующие сведения и нажмите кнопку "ОК".
- Это <port address> уникально для каждой пары целевого или узла и находится в рекомендуемом диапазоне от 50000 до 50039, было предоставлено в качестве входных данных при запуске kdnet.exe.
- W.x.y.z <session key> , созданный при запуске kdnet.exe, и его значение отображалось в выходных данных команды.

Сеанс командной строки с WinDbg

Вы также можете запустить сеанс с WinDbg, введя эту команду в окне командной строки.

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

Перезагрузка целевого компьютера

После загрузки и готовности отладчика перезагрузите целевой компьютер. Одним из способов перезагрузки компьютера является использование shutdown -r -t 0 команды из командной строки администратора.

После перезапуска целевого компьютера отладчик должен подключаться автоматически.

Устранение неполадок

USB-устройство не распознано

Если уведомление windows отображается на узле с текстовым USB-устройством, не распознаваемым при вставке отладочного кабеля, возможно, возникает известная проблема совместимости USB 3.1 с 3.1. Эта проблема влияет на конфигурации отладки при подключении кабеля отладки к контроллеру USB 3.1 на узле и контроллеру Intel (Ice Lake или Tiger Lake) 3.1 USB на целевом объекте.

Дополнительные сведения и описания моделей процессоров см. в разделе Ice Lake (микропроцессор) и Tiger Lake (микропроцессор). Чтобы найти модель процессора целевого компьютера, откройте приложение "Параметры" и перейдите в system then About. Процессор указан в спецификациях устройств.

Чтобы проверить эту проблему, откройте диспетчер устройств и найдите устройство подключения отладки USB в контроллерах универсальной последовательной шины. Если это устройство не удается найти, проверьте наличие неизвестного устройства на других устройствах. Щелкните правой кнопкой мыши устройство, чтобы открыть страницу свойств. Текстовое поле состояния устройства будет иметь текст Windows остановлено это устройство, так как оно сообщило о проблемах (Код 43) и USB-устройство вернуло недопустимый дескриптор USB BOS.

Чтобы обойти эту проблему, выполните следующие команды из командной строки администратора, чтобы внести изменения в реестр:

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

Используйте осторожность при редактировании реестра напрямую, так как неправильные изменения могут привести к нестабильности системы.

Сообщения о повторных попытках подключения в окнах консоли отладчика и не могут войти в целевой объект — SkipPciProbeDebugDevice

Если вы столкнулись со следующим сообщением в консоли отладчика KDNET, не удается инициировать разрыв в целевом объекте или возникнуть проблемы с определенными командами (например, kdfiles), это может быть связано с получением пакета связи из-за 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.

Эта проблема может произойти, так как драйвер pci.sys проверит устройство отладки. Чтобы устранить эти сообщения об ошибках, создайте следующую запись реестра на целевом устройстве в командной строке администратора.

Этот параметр также может разрешить отладчику подключаться, если при загрузке не удалось подключиться к исходному транспорту KD, например, если устройство отладки не удалось настроить при загрузке.

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

Затем перезапустите целевой компьютер.

shutdown /r /t 0

После перезагрузки устройства ошибки должны исчезнуть, и команды должны работать должным образом.

параметр NO_KDNIC для повышения производительности и надежности

Если сетевой адаптер Ethernet установлен на целевом компьютере, можно добиться дополнительных улучшений надежности и производительности, задав NO_KDNIC параметр.

bcdedit /set {current} loadoptions NO_KDNIC

Добавление NO_KDNIC является необязательным и может использоваться только в том случае, если целевой объект имеет дополнительный сетевой адаптер, Wi-Fi или USB-порт для подключения адаптера USB-Ethernet для предоставления сетевого доступа к Windows.

Добавление NO_KDNIC не позволит драйверу kdnic.sys (драйверу на основе таймера мини-порта) работать поверх KDNET, что означает, что трафик WINDOWS TCP/IP не будет направляться через транспорт KDNET. Затем транспорт KDNET можно использовать только для маршрутизации пакетов, связанных с отладкой, между целевой KDNET и отладчиком узла.

Это может помочь с производительностью сети, которая может быть затронута при запуске драйвера kdnic.sys на вершине kdnet. В этой ситуации целевой объект никогда не будет спать, предотвращая тесты капли питания, или задержки будут возникать при доступе к целевому объекту через RDP. Это связано с тем, что интерфейс KDNET должен направлять пакеты отладчика и сетевые пакеты Windows TCP/IP при запуске kdnic.sys.