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

  • Artigo

As Ferramentas de Depuração para Windows dão suporte à depuração de kernel em um cabo USB usando o Modo de Emulação Ethernet (EEM) Este tópico descreve como configurar o EEM USB usando o utilitário kdnet.exe.

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

Requisitos do dispositivo EEM USB no modo kernel

Os seguintes itens são necessários:

  • No computador de destino, um controlador Synopsys USB 3.0 conectado a uma porta USB tipo C.

  • No computador host, é necessária uma porta USB 3.0 acessível externamente.

  • Atualização do Windows 10 de outubro de 2020 (20H2) ou posterior

O transporte KDNET-EEM-USB pode ser configurado para:

  • Dispositivo de depuração PCI. Esses dispositivos de depuração são definidos usando dbgsettings::busparams=seg.bus.dev.fun.
  • Dispositivos de depuração de tabela ACPI-DBG2. Esses dispositivos de depuração são definidos usando dbgsettings::busparams=1|2|3, que 1|2|3 aponta para a entrada de matriz ACPI DBG2-Table específica que contém a configuração do dispositivo de depuração.

Requisitos de cabo

  • Um cabo 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.

Arquivos de transporte binário

Os binários kd_0C_8086.dll para x64 e kd_8003_5143.dll para ARM são usados para dar suporte ao transporte do depurador KDNET-EEM-USB.

Confirme se um controlador USB compatível está disponível no destino

No computador de destino, inicie o Gerenciador de dispositivos.

Confirme se o Synopsys USB 3.0 Dual-Role Controller está listado.

Captura de tela do Gerenciador de dispositivos exibindo o nó USB com o Synopsys USB 3.0 Dual-Role Controller destacado.

Determine a porta de depuração quando várias portas estiverem disponíveis

Depois de identificar uma porta que dá suporte à depuração, a próxima etapa é localizar o conector USB físico associado a essa porta.

Por exemplo, no Surface Pro X, use a menor das duas portas USB C usada para depuração KDNET EEM.

Foto da lateral de um Surface Pro X com duas portas USB-C.

Use o kdnet.exe para confirmar o suporte ao dispositivo e exibir o valor de busparams

Dispositivos Intel / AMD 64

As opções de depuração BCDEDIT são armazenadas no repositório BCD (Dados de Configuração de Inicialização). Para obter mais informações, consulte BCDEdit /debug.

Dispositivos ARM

Os dispositivos ARM usam a tabela ACPI DBG2 para configurar o depurador, em que os busparams apontam para a entrada da tabela DBG2. Para especificar a porta de depuração que será usada, busparm é usado. Normalmente, apenas o primeiro barramento é usado e é 0 ou 1, dependendo do dispositivo. Normalmente, os dispositivos não usam busparams=0, pois a entrada da tabela 0 DBG2 normalmente é reservada para o COM do dispositivo serial. Para obter mais informações sobre a tabela ACPI DBG2, consulte DBG2 (Tabela 2 da Porta de Depuração da Microsoft).

Usar o kdnet.exe para configurar o KDNET EEM USB

Use o utilitário kdnet.exe para exibir as informações de parâmetro para controladores que dão suporte à depuração de transporte KDNET-EEM-USB.

  1. Confirme se as Ferramentas de Depuração do Windows estão instaladas no host e no sistema de destino. Para obter informações sobre como baixar e instalar as ferramentas do depurador, consulte Ferramentas de depuração para Windows.

  2. Localize o utilitário kdnet.exe. Por padrão, os arquivos estão localizados aqui.

    C:\Program Files (x86)\Windows Kits\10\Debuggers\x64

  3. No computador de destino, abra uma janela do prompt de comando como Administrador. Insira este comando para verificar se o computador de destino tem um adaptador de rede com suporte e para exibir o valor de busparams.

    C:\KDNET>kdnet.exe

Network debugging is not supported on any of the NICs in this machine.
KDNET supports NICs from Intel, Broadcom, Realtek, Atheros, Emulex, Mellanox
and Cisco.

Network debugging is supported on the following USB controllers:
busparams=1, Device-mode USB controller with Vendor ID: 5143 (Default)
busparams=2, Device-mode USB controller with Vendor ID: 5143
busparams=3, Device-mode USB controller with Vendor ID: 5143
busparams=4, Device-mode USB controller with Vendor ID: 5143

This Microsoft hypervisor supports using KDNET in guest VMs.

  4. Como a saída do kdnet.exe indica que um controlador USB suportado com um valor de busparams de 1 está disponível, podemos prosseguir.

Como configurar o computador de destino

Use o utilitário kdnet.exe para definir as configurações do depurador no computador de destino, seguindo estas etapas.

Importante

Antes de usar o bcdedit para alterar as informações de inicialização, talvez seja necessário suspender temporariamente os recursos de segurança do Windows, como BitLocker e Inicialização Segura, no computador de teste. Você pode reativar o Bit Locker e a Inicialização Segura assim que terminar de usar o BCDEdit para atualizar as informações de inicialização. Gerencie adequadamente o computador de teste, quando os recursos de segurança estiverem desabilitados.

  1. Use o comando mostrado abaixo para definir o valor de busparams, o endereço IP e a porta do sistema host e gerou uma chave de conexão exclusiva. O endereço IP 169.254.255.255 é usado para todas as conexões USB EMM.

  2. Escolha um endereço de porta exclusivo para cada par de destino/host com o qual você trabalha, dentro do intervalo recomendado de 50000 a 50039. 50005 é exibido no exemplo.


   C:\>kdnet.exe 169.254.255.255 50005

   Enabling network debugging on Intel(R) 82577LM Gigabit Network Connection.
   Key=2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p

  1. Copie a chave retornada em um arquivo .txt do bloco de notas. No exemplo mostrado, a chave gerada tem um valor de:

    2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p

  2. Use o comando BCDEdit para verificar se os parâmetros são os esperados. Para obter mais informações, consulte BCDEdit /dbgsettings

   C:\>bcdedit /dbgsettings

   busparams               1
   key                     2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
   debugtype               NET
   hostip                  169.254.255.255
   port                    50005
   dhcp                    No
   The operation completed successfully.

Desativar o firewall no host

No host, desabilite o firewall para o depurador.

Como conectar o WinDbg ao destino para depuração do kernel

No computador host, abra o WinDbg. No menu Arquivo, escolha Depuração de kernel. Na caixa de diálogo Depuração de Kernel, abra a guia Rede . Cole o número da porta e a chave que você salvou no arquivo .txt do bloco de notas anteriormente. Selecione OK.

Você também pode iniciar uma sessão do WinDbg abrindo uma janela do prompt de comando e inserindo o seguinte comando, em que é a porta selecionada acima e é a chave que foi retornada por kdnet.exe acima. Cole a chave que você salvou no bloco de notas .txt arquivo anteriormente.

windbg -k -d net:port=<YourDebugPort>,key=<YourKey>

Reiniciar o computador de destino

Depois que o depurador estiver conectado, reinicie 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

Solução de problemas do Target

Confirme se o Adaptador de Rede KDNET-USB-EMM do Windows está presente em Adaptadores de Rede no Gerenciador de Dispositivos do Windows.

As propriedades do dispositivo mostram quando o controlador é reservado para uso pelo depurador de kernel do Windows.

Captura de tela do Gerenciador de dispositivos exibindo o nó USB com o Synopsys USB 3.0 Dual-Role Controller indicando que o controlador está reservado.

Solução de problemas do host

Confirme se o Adaptador de Rede KDNET-USB-EMM do Windows está presente em Adaptadores de Rede no Gerenciador de Dispositivos do Windows.

No host, a conexão KDNET-EEM usando a porta USB Tipo A é mostrada.

Captura de tela do Gerenciador de Dispositivos exibindo o nó de rede com uma entrada de adaptador de rede KDNET USB-EEM do Windows.

Intel PCI - A conexão repete 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 determinados comandos (por exemplo, kdfiles), pode ser devido ao KDNET receber 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 incorretamente o dispositivo de depuração. Para eliminar os erros, crie a seguinte entrada do Registro no dispositivo TARGET em um prompt de comando do administrador.

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.

Confira também

Como configurar a depuração automática do kernel de rede KDNET

Como configurar a depuração do kernel de rede KDNET manualmente

Configurando a depuração do modo kernel (KDUSB) xHCI-DBC USB 3.0

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