Configuración de la depuración en modo kernel DE KDNET USB (KDNET-USB)

Artículo
10/31/2024

Herramientas de depuración para Windows admite la depuración en modo kernel a través de un cable USB 3.0 mediante KDNET a través de USB. En este artículo se describe cómo configurar esta opción de transporte.

El equipo que ejecuta el depurador se denomina equipo host y el equipo que se depura se denomina equipo de destino.

La depuración a través de un cable USB 3.0 requiere el siguiente hardware:

En el equipo host, un controlador de host xHCI USB 3.0+ y un puerto USB3.
En el equipo de destino, un controlador de host xHCI USB 3.0+ y un puerto USB3 que admite la depuración (DBC)
El controlador de host USB del equipo de destino debe admitir la interfaz de funcionalidad de depuración (DBC) de Intel xHCI. Para obtener más información, consulte la especificación xHCI disponible en el sitio web de Intel.

Archivos de transporte binarios

El controlador kdstub.dll y kdnic.sys se usan para admitir el transporte del depurador KDNET-USB.

Requisitos de cable

Un cable de depuración USB de Microsoft naranja, que es un cable cruzado A-A que tiene dos enchufes tipo A macho y sin conexión Vbus. Este cable está disponible en proveedores como DataPro - USB 3.0 Super-Speed A/A Debugging Cable.
Se requiere un adaptador de tipo C usb 3.0 estándar a tipo A para conectar el puerto de tipo host A al puerto de tipo C de destino.

Para simplificar la solución de problemas, conecte el cable directamente entre el equipo de destino y host, evitando los concentradores o las estaciones de acoplamiento.

Configuración del equipo de destino

En el equipo de destino, busque e inicie la herramienta UsbView . La herramienta UsbView se incluye en Herramientas de depuración para Windows. Para un sistema x64, UsbView se encuentra en C:\Archivos de programa (x86)\Windows Kits\10\Tools\KitVersion\x64\usbview.exe.
En UsbView, busque todos los controladores de host xHCI.

En UsbView, expanda los nodos de los controladores de host xHCI. Busque una indicación de que un puerto en el controlador host admite la depuración.

[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

Anote los números de bus, dispositivo y función del controlador xHCI que quiere usar para la depuración. UsbView muestra estos números. En el ejemplo siguiente, el número de bus es 48, el número de dispositivo es 0 y el número de función es 0.
```
USB xHCI Compliant Host Controller
...
DriverKey: {36fc9e60-c465-11cf-8056-444553540000}\0020
...
Bus.Device.Function (in decimal): 48.0.0
```
Si necesita confirmar los parámetros de bus, use Administrador de dispositivos. En Administrador de dispositivos, busque el controlador USB que quiere usar para la depuración. En Ubicación de la pestaña General , se muestran los números de bus, dispositivo y función. b, d y f son los números de bus, dispositivo y función para el controlador de host USB3. Los números de bus, dispositivo y función deben estar en formato decimal.

También puede usar kdnet.exe para ayudar a recopilar información sobre el controlador 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.

Después de identificar un controlador xHCI que admita la depuración, el siguiente paso es localizar el conector USB físico asociado a un puerto en el controlador xHCI. Para encontrar el conector físico, conecte cualquier dispositivo USB 3.0 a cualquier conector USB en el equipo de destino. Actualice UsbView para ver dónde se encuentra el dispositivo. Si UsbView muestra el dispositivo conectado al controlador de host xHCI elegido, ha encontrado un conector USB físico que puede usar para la depuración USB 3.0.

Importante

Antes de usar bcdedit o kdnet.exe para cambiar la información de arranque, es posible que deba suspender temporalmente las características de seguridad de Windows, como BitLocker y Arranque seguro en el equipo de prueba. Vuelva a habilitar estas características de seguridad cuando finalicen las pruebas y administre adecuadamente el equipo de prueba cuando las características de seguridad estén deshabilitadas.

Elija un único <port address> para cada par de destino o host con el que trabaje, dentro del intervalo recomendado de 50000-50039. 50005 se muestra en los ejemplos siguientes.
Busque la utilidad KDNet.exe en el directorio del depurador WDK que coincida con el tipo de CPU, por ejemplo x64.
En el equipo de destino, abra una ventana del símbolo del sistema como administrador y escriba este comando para habilitar la depuración de kernel con -k la opción . -w, -b y -h habilitarán la depuración del kernel para aplicaciones del sistema winload, bootmgr y hypervisor. Para obtener más información sobre las opciones de WinDbg, consulte Opciones de inicio de la línea de comandos de WinDbg.
```
kdnet.exe 169.254.255.255 50005 -k
```
- 169.254.255.255 la dirección IP estática de vínculo no enrutable debe usarse para KDNET a través de USB3.
- kdnet.exe devolverá una clave w.x.y.z que WinDbg usará para conectarse al dispositivo de destino.
Para usar un puerto USB específico, use el parámetro -busparams .
```
kdnet.exe -busparams 0.13.0 169.254.255.255 50005 -k
```
Se recomienda usar la utilidad KDNET. Esta herramienta establece opciones más complicadas para establecer mediante bcdedit, así como comprobar y establecer valores de registro auxiliares para pci y administración de energía.
```
bcdedit /dbgsettings NET hostip:169.254.255.255 port:50001 key:1.2.3.4 busparams:0.20.0 noDhcp
```

Deshabilitar la administración de energía

En algunos casos, las transiciones de energía pueden interferir con la depuración a través de USB 3.0. Para evitar estos problemas, deshabilite la suspensión selectiva para el controlador de host xHCI y su centro raíz, que se usa para la depuración.

En Administrador de dispositivos, vaya al nodo del controlador de host xHCI. Haga clic con el botón derecho en el nodo y elija Propiedades. Si hay una pestaña Administración de energía, abra la pestaña y desactive la casilla Permitir que el equipo apague este dispositivo para guardar la energía .
En Administrador de dispositivos, vaya al nodo del centro raíz del controlador de host xHCI. Haga clic con el botón derecho en el nodo y elija Propiedades. Si hay una pestaña Administración de energía, abra la pestaña y desactive la casilla Permitir que el equipo apague este dispositivo para guardar energía .

Cuando termine de usar el controlador de host xHCI para la depuración, vuelva a habilitar la suspensión selectiva para el controlador de host xHCI.

Inicio de una sesión de depuración mediante WinDbg

Conecte un cable de depuración USB 3.0 a los puertos USB 3.0 identificados que ha elegido para la depuración en el host y los equipos de destino.
En el equipo host, abra una versión de WinDbg (como administrador) que coincida con el bit de Windows que se ejecuta en el equipo host. Por ejemplo, si el equipo host ejecuta una versión de 64 bits de Windows, abra la versión de 64 bits de WinDbg como administrador.
En el menú Archivo , elija Asociar al kernel. En el cuadro de diálogo Depuración de kernel, abra la pestaña Net . Escriba la siguiente información y haga clic en Aceptar.
- Que <port address> es único para cada par de destino o host, y está dentro del intervalo recomendado de 50000-50039, se proporcionó como entrada cuando se ejecutó kdnet.exe.
- W.x.y.z <session key> que se generó cuando se ejecutó kdnet.exe y su valor se mostró en la salida del comando.

Sesión de línea de comandos con WinDbg

También puede iniciar una sesión con WinDbg escribiendo este comando en una ventana del símbolo del sistema.

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

Reinicio del equipo de destino

Una vez cargado y listo el depurador, reinicie el equipo de destino. Una manera de reiniciar el equipo es usar el comando desde el shutdown -r -t 0 símbolo del sistema de un administrador.

Una vez reiniciado el equipo de destino, el depurador debe conectarse automáticamente.

Solución de problemas

Dispositivo USB no reconocido

Si aparece una notificación de Windows en el host con el dispositivo USB de texto no reconocido al insertar el cable de depuración, es posible que se alcance un problema de compatibilidad conocido de USB 3.1 a 3.1. Este problema afecta a las configuraciones de depuración cuando el cable de depuración está conectado a un controlador USB 3.1 en el host y un controlador USB Intel (Ice Lake o Tiger Lake) 3.1 en el destino.

Para obtener más información y listados de modelos de procesador, consulte Ice Lake (microprocesador) o Tiger Lake (microprocesador). Para buscar el modelo de procesador de la máquina de destino, abra la aplicación Configuración y vaya a Sistema y, a continuación, Acerca de. El procesador aparece en Especificaciones del dispositivo.

Para comprobar este problema, abra Administrador de dispositivos y busque Dispositivo de conexión de depuración USB en Controladores de bus serie universales. Si no se encuentra este dispositivo, compruebe si hay un dispositivo desconocido en Otros dispositivos. Haga clic con el botón derecho en el dispositivo para abrir su página de propiedades. El cuadro de texto estado del dispositivo tendrá el texto Windows detenido este dispositivo porque ha notificado problemas (código 43) y el dispositivo USB devolvió un descriptor DE BOS USB no válido.

Para solucionar este problema, ejecute estos comandos desde un símbolo del sistema de administrador para realizar cambios en el Registro:

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

Tenga cuidado al editar el registro directamente, ya que los cambios incorrectos pueden provocar inestabilidad del sistema.

Los mensajes de reintento de conexión en las ventanas de la consola del depurador y no se pueden interrumpir en el destino: SkipPciProbeDebugDevice

Si encuentra el siguiente mensaje en la consola del depurador de KDNET, no puede iniciar una interrupción en el destino o experimentar problemas con determinados comandos (por ejemplo, kdfiles), puede deberse a que KDNET recibe un paquete ping fuera de secuencia.

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

Este problema puede ocurrir porque el controlador de pci.sys está sondeando el dispositivo de depuración. Para eliminar estos mensajes de error, cree la siguiente entrada del Registro en el dispositivo TARGET en un símbolo del sistema del administrador.

Esta configuración también puede permitir que el depurador se conecte si el transporte de KD inicial no se pudo conectar al arranque, por algún otro motivo, por ejemplo, si el dispositivo de depuración no se pudo configurar en el arranque.

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

A continuación, reinicie la máquina de destino.

shutdown /r /t 0

Una vez que el dispositivo se reinicie, los errores deben desaparecer y los comandos deben funcionar según lo previsto.

NO_KDNIC configuración para mejorar el rendimiento y la confiabilidad

Si se instala una NIC ethernet en el equipo de destino, se pueden lograr mejoras adicionales de confiabilidad y rendimiento estableciendo la NO_KDNIC opción .

bcdedit /set {current} loadoptions NO_KDNIC

Agregar NO_KDNIC es opcional y solo se puede usar si el destino tiene una NIC adicional, Wi-Fi o puerto USB para conectar un adaptador USB-Ethernet para proporcionar acceso de red a Windows.

Agregar NO_KDNIC impedirá que el controlador kdnic.sys (un controlador basado en temporizador de miniporte) se ejecute sobre KDNET, lo que significa que el tráfico TCP/IP de Windows no se enrutará a través del transporte KDNET. A continuación, el transporte de KDNET solo se puede usar para enrutar paquetes relacionados con la depuración entre el KDNET de destino y el depurador de host.

Esto puede ayudar con el rendimiento de la red que puede verse afectado cuando kdnic.sys controlador se ejecuta encima de kdnet. En esta situación, el destino nunca pasará a dormir, evitará pruebas de goteo de energía o se producirán retrasos al acceder al destino a través de RDP. Esto se debe a que la interfaz KDNET debe enrutar los paquetes del depurador y los paquetes de red TCP/IP de Windows cuando se ejecuta kdnic.sys.