Configurando a depuração do modo kernel KDNET USB (KDNET-USB)

Artigo
10/31/2024

As Ferramentas de Depuração para Windows dão suporte à depuração no modo kernel por meio de um cabo USB 3.0 usando KDNET por USB. Este artigo descreve como configurar essa opção de transporte.

O computador que executa o depurador é chamado de computador host, e o computador que está sendo depurado é chamado de computador de destino.

A depuração em um cabo USB 3.0 requer o seguinte hardware:

No computador host, um controlador de host xHCI USB 3.0+ e uma porta USB3.
No computador de destino, um controlador de host xHCI USB 3.0+ e uma porta USB3 que dá suporte à DBC (depuração)
O controlador de host USB do computador de destino deve oferecer suporte à DBC (Debug Capability Interface) Intel xHCI. Para obter mais informações, consulte a especificação xHCI disponível no site da Intel.

Arquivos de transporte binário

O driver kdstub.dll e kdnic.sys são usados para dar suporte ao transporte do depurador KDNET-USB.

Requisitos de cabo

Um cabo de depuração USB laranja da Microsoft, que é um cabo cruzado AA que possui dois plugues macho tipo A e nenhuma conexão Vbus. Este cabo está disponível em fornecedores como DataPro - Cabo de depuração A/A USB 3.0 Super-Speed.
Um adaptador USB 3.0 Tipo C para Tipo A padrão é necessário para conectar a porta tipo A do host à porta tipo C de destino.

Para simplificar a solução de problemas, conecte o cabo diretamente entre o computador de destino e o computador host, evitando hubs ou estações de encaixe.

Configurar o computador de destino

No computador de destino, localize e inicie a ferramenta UsbView . A ferramenta UsbView está incluída nas Ferramentas de Depuração para Windows. Para um sistema x64, UsbView estaria localizado em C:\Arquivos de Programas (x86)\Windows Kits\10\Tools\KitVersion\x64\usbview.exe.
Em UsbView, localize todos os controladores de host xHCI.

Em UsbView, expanda os nós dos controladores de host xHCI. Procure uma indicação de que uma porta no controlador de host dá suporte à depuração.

[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 os números de barramento, dispositivo e função do controlador xHCI que você pretende usar para depuração. UsbView exibe esses números. No exemplo a seguir, o número do barramento é 48, o número do dispositivo é 0 e o número da função é 0.
```
USB xHCI Compliant Host Controller
...
DriverKey: {36fc9e60-c465-11cf-8056-444553540000}\0020
...
Bus.Device.Function (in decimal): 48.0.0
```
Se você precisar confirmar os parâmetros do barramento, use o Gerenciador de dispositivos. No Gerenciador de Dispositivos, localize o Controlador USB que você pretende usar para depuração. Em Localização na guia Geral , os números de barramento, dispositivo e função são exibidos. b, d e f são os números de barramento, dispositivo e função para o controlador de host USB3. Os números bus, device e function devem estar no formato decimal.

Você também pode usar kdnet.exe para ajudar a coletar informações sobre o 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.

Depois de identificar um controlador xHCI que dá suporte à depuração, a próxima etapa é localizar o conector USB físico associado a uma porta no controlador xHCI. Para localizar o conector físico, conecte qualquer dispositivo USB 3.0 a qualquer conector USB no computador de destino. Atualize o UsbView para ver onde seu dispositivo está localizado. Se o UsbView mostrar seu dispositivo conectado ao controlador de host xHCI escolhido, você encontrou um conector USB físico que pode ser usado para depuração USB 3.0.

Importante

Antes de usar bcdedit ou kdnet.exe alterar as informações de inicialização, talvez seja necessário suspender temporariamente os recursos de segurança do Windows, como o BitLocker e a Inicialização Segura no computador de teste. Reabilite esses recursos de segurança quando o teste terminar e gerencie devidamente o PC de teste, quando os recursos de segurança estiverem desabilitados.

Escolha um exclusivo <port address> para cada par de destino/host com o qual você trabalha, dentro do intervalo recomendado de 50000-50039. 50005 é mostrado nos exemplos abaixo.
Localize o utilitário KDNet.exe no diretório do depurador WDK correspondente ao seu tipo de CPU, por exemplo, x64.
No computador de destino, abra uma janela do Prompt de Comando como Administrador e insira este comando para habilitar a depuração do kernel com -k a opção. O -w, -b e -h habilitarão a depuração do kernel para aplicativos do sistema winload, bootmgr e hypervisor. Para obter mais informações sobre as opções do WinDbg, consulte WinDbg – Opções de inicialização da linha de comando.
```
kdnet.exe 169.254.255.255 50005 -k
```
- 169.254.255.255 o endereço IP estático local de link não roteável deve ser usado para KDNET sobre USB3.
- kdnet.exe retornará uma chave w.x.y.z que será usada pelo WinDbg para se conectar ao dispositivo de destino.
Para usar uma porta USB específica, use o parâmetro -busparams .
```
kdnet.exe -busparams 0.13.0 169.254.255.255 50005 -k
```
Recomenda-se o uso do utilitário KDNET. Essa ferramenta define opções que são mais complicadas de definir usando bcdedit, bem como verificando e definindo valores de registro de suporte para PCI e gerenciamento de energia.
```
bcdedit /dbgsettings NET hostip:169.254.255.255 port:50001 key:1.2.3.4 busparams:0.20.0 noDhcp
```

Desativar gerenciamento de energia

Em alguns casos, as transições de energia podem interferir na depuração por USB 3.0. Para evitar esses problemas, desabilite a suspensão seletiva para o controlador de host xHCI e seu hub raiz, que você está usando para depuração.

No Gerenciador de Dispositivos, navegue até o nó do controlador de host xHCI. Clique com o botão direito do mouse no nó e escolha Propriedades. Se houver uma guia Gerenciamento de energia, abra-a e desmarque a caixa de seleção Permitir que o computador desligue este dispositivo para economizar energia .
No Gerenciador de Dispositivos, navegue até o nó do hub raiz do controlador de host xHCI. Clique com o botão direito do mouse no nó e escolha Propriedades. Se houver uma guia Gerenciamento de energia, abra-a e desmarque a caixa de seleção Permitir que o computador desligue este dispositivo para economizar energia .

Quando terminar de usar o controlador de host xHCI para depuração, reative a suspensão seletiva para o controlador de host xHCI.

Iniciar uma sessão de depuração usando o WinDbg

Conecte um cabo de depuração USB 3.0 às portas USB 3.0 identificadas que você escolheu para depuração nos computadores host e de destino.
No computador host, abra uma versão do WinDbg (como Administrador) que corresponda ao número de bits do Windows em execução no computador host. Por exemplo, se o computador host estiver executando uma versão de 64 bits do Windows, abra a versão de 64 bits do WinDbg como Administrador.
No menu Arquivo , escolha Anexar ao Kernel. Na caixa de diálogo Depuração do Kernel, abra a guia Rede . Insira as informações a seguir e clique em OK.
- O <port address> que é exclusivo para cada par de destino/host e está dentro do intervalo recomendado de 50000-50039, foi fornecido como entrada quando kdnet.exe foi executado.
- O <session key> w.x.y.z que foi gerado quando kdnet.exe foi executado e seu valor foi exibido na saída do comando.

Sessão de linha de comando com WinDbg

Você também pode iniciar uma sessão com o WinDbg inserindo este comando em uma janela do Prompt de Comando.

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

Reiniciar o computador de destino

Depois que o depurador estiver carregado e pronto para uso, reinicialize o computador de destino. Uma maneira de fazer reinicie o PC é usar o shutdown -r -t 0 comando do prompt de comando de um administrador.

Depois que o PC de destino for reiniciado, o depurador deverá se conectar automaticamente.

Solução de problemas

Dispositivo USB não reconhecido

Se uma notificação do Windows aparecer no host com o texto USB device not recognized quando você inserir o cabo de depuração, é possível que um problema conhecido de compatibilidade USB 3.1 para 3.1 esteja sendo atingido. Esse problema afeta as configurações de depuração quando o cabo de depuração está conectado a um controlador USB 3.1 no host e a um controlador USB Intel (Ice Lake ou Tiger Lake) 3.1 no destino.

Para obter mais informações e listas de modelos de processador, consulte Ice Lake (microprocessador) e/ou Tiger Lake (microprocessador). Para encontrar o modelo do processador da máquina de destino, abra o aplicativo Configurações e vá para Sistema e depois Sobre. O processador está listado em Especificações do dispositivo.

Para verificar esse problema, abra o Gerenciador de dispositivos e procure por Dispositivo de conexão de depuração USB em controladores Universal Serial Bus. Se este dispositivo não puder ser encontrado, verifique se há um dispositivo desconhecido em Outros dispositivos. Clique com o botão direito do mouse no dispositivo para abrir sua página de propriedades. A caixa de texto de status do dispositivo terá o texto Windows parou este dispositivo porque relatou problemas (Código 43) e O dispositivo USB retornou um descritor USB BOS inválido.

Para contornar esse problema, execute estes comandos em um prompt de comando do administrador para fazer alterações no 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

Tenha cuidado ao editar o registro diretamente, pois alterações incorretas podem levar à instabilidade do sistema.

A conexão repete mensagens nas janelas do console do depurador e não pode invadir o destino – SkipPciProbeDebugDevice

Se você encontrar a mensagem a seguir no console do depurador KDNET, não puder iniciar uma invasão no destino ou tiver problemas com determinados comandos (por exemplo, kdfiles), pode ser porque o KDNET recebeu um pacote de ping fora de sequência.

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

Esse problema pode ocorrer porque o driver pci.sys está investigando o dispositivo de depuração. Para eliminar essas mensagens de erro, crie a seguinte entrada do Registro no dispositivo TARGET em um prompt de comando do administrador.

Essa configuração também pode permitir que o depurador se conecte se o transporte KD inicial não puder se conectar na inicialização, por algum outro motivo, por exemplo, se o dispositivo de depuração não puder ser configurado na inicialização.

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

Em seguida, reinicie a máquina de destino.

shutdown /r /t 0

Depois que o dispositivo for reinicializado, os erros devem desaparecer e os comandos devem funcionar conforme o esperado.

NO_KDNIC configuração para melhor desempenho e confiabilidade

Se uma placa de rede ethernet estiver instalada no computador de destino, melhorias adicionais de confiabilidade e desempenho poderão ser obtidas definindo a NO_KDNIC opção.

bcdedit /set {current} loadoptions NO_KDNIC

A adição NO_KDNIC é opcional e só pode ser usada se o destino tiver uma porta NIC, Wi-Fi ou USB extra para conectar um adaptador USB-Ethernet para fornecer acesso à rede ao Windows.

A adição NO_KDNIC impedirá que o driver kdnic.sys (um driver baseado em temporizador de miniport) seja executado sobre o KDNET, o que significa que o tráfego TCP/IP do Windows não será roteado por meio do transporte KDNET. Em seguida, o transporte KDNET pode ser usado apenas para rotear pacotes relacionados à depuração entre o KDNET de destino e o depurador de host.

Isso pode ajudar no desempenho da rede que pode ser afetado quando kdnic.sys driver está em execução na parte superior do kdnet. Nessa situação, o alvo nunca entrará no modo de suspensão, impedindo testes de gotejamento de energia, ou ocorrerão atrasos ao acessar o alvo via RDP. Isso ocorre porque a interface KDNET precisa rotear os pacotes do depurador e os pacotes de rede TCP/IP do Windows quando kdnic.sys está em execução.