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

As Ferramentas de Depuração para Windows suportam depuração em modo kernel através de um cabo USB 3.0 usando KDNET através de USB. Este artigo descreve como configurar essa opção de transporte.

O computador que executa o depurador é chamado de computador hoste o computador que está sendo depurado é chamado de computador de destino.

A depuração através de um cabo USB 3.0 requer o seguinte hardware:

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

Arquivos de transporte binários

Os drivers kdstub.dll e kdnic.sys são usados para suportar o transporte do depurador KDNET-USB.

Requisitos para cabos

Um cabo de depuração USB laranja da Microsoft, que é um cabo cruzado A-A que tem dois plugues machos tipo A e nenhuma conexão Vbus. Este cabo está disponível a partir de fornecedores como DataPro - USB 3.0 Super-Speed A / A Debugging Cable.
É necessário um adaptador USB 3.0 Tipo C para Tipo A padrão para conectar a porta do tipo A do host à porta do 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 ancoragem.

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, o UsbView estaria localizado em C:\Program Files (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 anfitrião suporta 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 pretende usar para depuração. 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 de barramento, use o Gerenciador de dispositivos. No Gestor de Dispositivos, localize o Controlador USB que pretende utilizar para debugging. 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 host USB3. Os números de barramento, dispositivo e função devem estar em formato decimal.

Também pode utilizar kdnet.exe para ajudar a recolher 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 suporte depuração, o passo seguinte é localizar o conector USB físico associado a uma porta no controlador xHCI. Para encontrar o conector físico, conecte qualquer dispositivo USB 3.0 a qualquer conector USB no computador de destino. Atualize o UsbView para ver onde o dispositivo está localizado. Se o UsbView mostrar seu dispositivo conectado ao controlador host xHCI escolhido, então você encontrou um conector USB físico que pode ser usado para depuração USB 3.0.

Importante

Antes de utilizar bcdedit ou kdnet.exe alterar as informações de arranque, poderá ter de suspender temporariamente as funcionalidades de segurança do Windows, como o BitLocker e o Arranque Seguro, no PC de teste. Reative esses recursos de segurança quando o teste estiver concluído e gerencie adequadamente o PC de teste quando os recursos de segurança estiverem desativados.

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 digite este comando para ativar a depuração do núcleo com a opção -k. O -w, -b e -h habilitará 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 via 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. Esta ferramenta define opções que são mais complicadas de definir usando bcdedit, bem como verificar e definir 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 a gestão de energia

Em alguns casos, as transições de energia podem interferir na depuração via USB 3.0. Para evitar esses problemas, desative a suspensão seletiva para o controlador de host xHCI, bem como o respetivo hub raiz, que está a usar para depuração.

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

Quando terminar de utilizar o controlador host xHCI para depuração, ative novamente a suspensão seletiva para o controlador 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 anfitrião, abra uma versão do WinDbg (como Administrador) que corresponda à arquitectura de bits do Windows em execução no computador anfitrião. 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 seguintes informações 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 WinDbg inserindo este comando em uma janela de prompt de comando.

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

Reinicie o computador de destino

Assim que o depurador estiver carregado e pronto para ser usado, reinicie o computador de destino. Uma maneira de fazer a reinicialização do PC, é usar o comando shutdown -r -t 0 a partir do prompt de comando de um administrador.

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

Solução de problemas

Dispositivo USB não reconhecido

Se uma notificação do Windows aparecer no host com o texto dispositivo USB não reconhecido quando o utilizador insere o cabo de depuração, é possível que um problema conhecido de compatibilidade entre USB 3.1 e 3.1 esteja a ocorrer. Esse problema afeta as configurações de depuração quando o cabo de depuração é conectado a um controlador USB 3.1 no host e um controlador USB Intel (Ice Lake ou Tiger Lake) 3.1 no destino.

Para obter mais informações e listagens 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, em seguida, Sobre. O processador está listado em Especificações do dispositivo.

Para verificar esse problema, abra o Gerenciador de dispositivos e procure por USB Debug Connection Device 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 O Windows parou este dispositivo porque ele relatou problemas (Código 43) e O dispositivo USB retornou um descritor BOS USB inválido.

Para contornar esse problema, execute estes comandos de 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 tenta novamente mensagens nas janelas do console do depurador e não pode invadir o destino - SkipPciProbeDebugDevice

Se você encontrar a seguinte mensagem no console do depurador KDNET, não puder iniciar uma invasão no destino ou tiver problemas com certos comandos (por exemplo, kdfiles), isso pode ser devido ao KDNET receber um pacote 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 acontecer 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 conseguiu 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

Uma vez que o dispositivo é reinicializado, os erros devem desaparecer e os comandos devem funcionar conforme o esperado.

NO_KDNIC configuração para melhorar o desempenho e a confiabilidade

Se uma placa de rede ethernet estiver instalada no PC de destino, melhorias adicionais de confiabilidade e desempenho podem ser alcançadas 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 de rede ao Windows.

A adição NO_KDNIC impedirá que o driver kdnic.sys (um driver baseado em temporizador de miniporta) seja executado sobre o KDNET, o que significa que o tráfego TCP/IP do Windows não será roteado via 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 do host.

Isso pode ajudar no desempenho da rede, que pode ser afetado quando o controlador kdnic.sys está a ser executado em cima do KDNet. Nesta situação, o alvo nunca entrará em 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 pacotes de depurador e pacotes de rede TCP/IP do Windows quando kdnic.sys está em execução.

Reposição automática do controlador USB anfitrião

Às vezes, o depurador pode encontrar uma condição de pilha USB batida que pode ser causada por uma enumeração USB com falha anterior. Isso fará com que o depurador não consiga se conectar à máquina de destino, mesmo quando todas as configurações estiverem configuradas corretamente.

Em cenários de IC, esse problema pode ser resolvido desativando manualmente\rhabilitando o controlador USB pai. Para outros cenários, como laboratórios de teste automatizados, etapas manuais como essa não são viáveis. Ao ativar a RestartKdNetUsbDebugDevice configuração, o cliente do depurador monitorará automaticamente a enumeração USB com falha e redefinirá a pilha USB quando um dispositivo batido for detetado. Isso permitirá que o depurador se conecte sem qualquer intervenção do usuário. Essa funcionalidade é incorporada ao aplicativo cliente do depurador e, portanto, só fica ativa quando o cliente do depurador está em execução e a configuração está habilitada.

Como habilitar:

Opção 1: No prompt do depurador, execute o seguinte comando.

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

Advertência

Talvez você não consiga usar a estratégia para definir a opção se o dispositivo de depuração USB já estiver falhando ao enumerar, pois isso impedirá que a sessão se conecte e invada o destino para que você nunca chegue a um prompt de depurador funcional.

Opção 2: A partir do (novo) aplicativo Windbg vá para "File" -> "Settings" -> "Kernel debugging settings" e clique na caixa de seleção "Enable automatic reset of host USB controller when needed." em seguida, inicie normalmente a partir da caixa de diálogo "anexar ao kernel".

Opção 3: Crie (ou modifique o arquivo config.xml existente) para incluir a RestartKdNetUsbDebugDevice configuração. O arquivo config.xml é carregado do mesmo diretório que o aplicativo cliente do depurador, ou seja, kd.exe ou (legado) windbg.exe. Se não houver um presente, crie um novo arquivo chamado config.xml com o seguinte conteúdo:

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

Se já houver um config.xml presente, mescle o <Setting Name="RestartKdNetUsbDebugDevice" Type="VT_BOOL" Value="true"></Setting>Debug.Advanced elemento xml no nó do documento xml existente.