Como configurar a depuração no modo kernel 2PF usando o KDNET
As Ferramentas de depuração para Windows oferecem suporte à depuração de kernel por um cabo de rede usando várias Funções Físicas (PFs) nas NICs suportadas, particionando o espaço de configuração PCI.
Com a depuração de 2PF, cada PF pode ser conectada a uma única porta de rede, permitindo que a funcionalidade de depuração do kernel seja conectada a uma PF enquanto a pilha de rede padrão conversa com a outra PF. Por esse motivo, o KDNIC não precisa rotear o tráfego de rede do Windows via KDNET, e o KDNET será responsável apenas pelo roteamento do tráfego do depurador do kernel do host. Isso resulta em um aumento drástico de desempenho.
Este tópico descreve como configurar a depuração de 2PF usando o utilitário kdnet.exe.
Os fornecedores de placas de rede são incentivados a habilitar o suporte para esse recurso. Para obter mais informações, consulte Suporte para driver de rede miniporta KDNET 2PF do depurador.
Dois drivers serão executados sobre o espaço de configuração PCI particionado
O driver da caixa de entrada do Windows será executado fora da porta de rede primária no local PCI bus.dev.fun0.0.
O módulo KDNET-Ext. ficará sem a PF adicionada e em bus.dev.fun0.1, Essa técnica garante que o driver de NIC da caixa de entrada do Windows não seja afetado pelo compartilhamento da NIC com o KDNET.
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 2PF no modo kernel
Os seguintes itens são necessários:
No computador de destino, uma placa de rede 2PF compatível.
No computador host, uma placa de rede.
Uma conexão de rede entre o destino e o host.
Windows 10, compilação 21313 e posterior.
Placas de rede 2PF compatíveis
Fornecedores como NVIDIA, Mellanox e Cisco fornecem NICs que aceitam a depuração de rede 2PF. Verifique com o fornecedor da placa de rede quais modelos da placa de rede são aceitos. Observe que alguns fornecedores oferecem suporte à 2PF em um subconjunto de placas de rede que compartilham a mesma ID PnP.
Use o kdnet.exe para confirmar o suporte ao dispositivo e exibir o valor de busparams
Use o utilitário kdnet.exe para exibir as informações de parâmetro para controladores que suportam a depuração de transporte KDNET 2PF.
Confirme se as Ferramentas de depuração do Windows estão instaladas no sistema host. Para obter informações sobre como baixar e instalar as ferramentas do depurador, consulte Ferramentas de depuração para Windows.
Localize os arquivos kdnet.exe e VerifiedNICList.xml. Por padrão, eles estão localizados aqui.
C:\Program Files (x86)\Windows Kits\10\Debuggers\x64No computador host, copie os dois arquivos para um compartilhamento de rede ou pen drive para que eles estejam disponíveis no computador de destino.
No computador de destino, crie um diretório
C:\KDNETe copie os arquivos kdnet.exe e VerifiedNICList.xml para ele.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 supported on the following NICs: busparams=141.0.0, Mellanox ConnectX-4 Lx Ethernet Adapter #2, Plugged in, Primary function, multiple physical functions are supported. Network debugging is supported on the following USB controllers: busparams=128.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft) busparams=0.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft) busparams=128.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft) busparams=0.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)Como a saída mostrada acima não inclui "O KDNET está sendo executado na NIC.", isso indica que a depuração KDNET tradicional não está habilitada em nenhum dos adaptadores.
Se a NIC não funcionar com o recurso de várias PF, a notificação de status de PF de "várias funções físicas são suportadas" será omitida (em branco) das informações exibidas.
Se a NIC funcionar com várias PF, as informações reais exibidas dependerão da combinação da porta de rede (porta raiz/porta adicionada da PF), bem como do status do cabo conectado/desconectado de/para a porta física da NIC.
Esta tabela resume as diferentes notificações da PF para a NIC primária.
O adaptador de NIC bus.dev.fun corresponde a Status do cabo Status da PF original (primário) Cabo PF conectado Função primária, várias funções físicas estão habilitadas original (primário) Cabo PF desconectado Função primária, várias funções físicas são suportadas Esta tabela resume as diferentes notificações da PF para a NIC secundária.
O adaptador de NIC bus.dev.fun corresponde a Status do cabo Status da PF nova porta PF (secundária) O Kdnet está em execução Função secundária nova porta PF (secundária) cabo desconectado ou status desconhecido Função primária, várias funções físicas estão habilitadas, mas a função secundária não é usada Se a saída de kdnet.exe indicar que um controlador de NIC suportado está disponível, poderemos continuar.
Como configurar o computador de destino para 2PF
Use o utilitário kdnet.exe para definir as configurações do depurador no PC de destino para 2PF, 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.
Esse processo adicionará uma nova função física (PF) à NIC, especificada por bus.device.function. A nova PF pode ser usada apenas pelo KDNET, uma vez que o driver da caixa de entrada do Windows está configurado para não ser executado em uma PF secundária adicionada. Siga estas etapas para adicionar uma nova PF que será usada pelo dispositivo de depuração.
Confirme se a depuração está desativada antes de adicionar a nova função física
- Use o comando BCDEdit para confirmar se o KD está desabilitado no destino antes de adicionar um novo PF na NIC. Isso é necessário para garantir que o driver de NIC do fornecedor padrão seja carregado para que possa ser usado para adicionar a nova PF.
C:\> bcdedit /enum
...
debug No
Como alternativa, use kdnet.exe sem parâmetros para ver se a depuração está habilitada. A saída abaixo mostra o KDNET sendo executado em um sistema com depuração habilitada em uma NIC. Essa é a configuração legada de baixo desempenho.
c:\Debuggers>kdnet
Network debugging is supported on the following NICs:
busparams=141.0.0, Mellanox ConnectX-4 Lx Ethernet Adapter #2, KDNET is running on this NIC.
Network debugging is supported on the following USB controllers:
busparams=128.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=128.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
- Se o valor de depuração for definido como Yes, use o comando set para desabilitar a depuração.
C:\> bcdedit.exe /debug off
C:\> bcdedit.exe /set {default} bootdebug off
C:\> bcdedit.exe /set {bootmgr} bootdebug off
- Use o comando
shutdown -r -t 0do prompt de comando de um administrador para reinicializar.
Depois que o PC de destino for reiniciado, e a depuração, desativada, poderemos adicionar a nova função física.
Adicionar a nova função física
- Abra um prompt de comando elevado e execute o seguinte comando para adicionar uma segunda PF. Todos os valores são fornecidos usando valores decimais.
C:\KDNET> kdnet -addpf 141.0.0 198.51.100.1 50001
Succeeded adding a Pci PF on :141.0.1. Please power off or reboot the machine.
Enabling network debugging on Mellanox ConnectX-4 Lx Ethernet Adapter #2.
Manage-bde.exe not present. Bitlocker presumed disabled.
To debug this machine, run the following command on your debugger host machine.
windbg -k net:port=50001,key=2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
Then reboot this machine by running shutdown -r -t 0 from this command prompt.
bus.dev.fun é a porta de localização PCI do adaptador NIC que suporta o recurso PF múltiplo, portanto, a nova PF será adicionada/conectada a este dispositivo de rede.
A opção -addpf habilita automaticamente a depuração do kernel sobre o transporte KDNET na porta PF adicionada.
[host name/host ip address] é o endereço TCP/IP do computador host. Use o comando ipconfig no computador host para determinar esse endereço.
[port number] é o número da porta TCP/IP. Você pode escolher qualquer número de porta entre 49152 e 65535. O intervalo recomendado é entre 50000 e 50039. A porta escolhida será aberta para acesso exclusivo pelo depurador em execução no computador host. 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.
Observe que -addpf também adicionará o atributo NO_KDNIC à instalação do sistema operacional {default} loadoptions. Isso ocorre porque o KDNIC não é mais necessário para ser executado em cima do KDNET.
O loadoptions = NO_KDNIC é adicionado à tag {default} OS para garantir que kdnic.sys não seja executado fora da PF recém-adicionada (141.0.1)
Use o comando bcdedit para confirmar que NO_KDNIC foi definido.
C:\KDNET> bcdedit /enum {default}
Windows Boot Loader
-------------------
identifier {current}
device partition=C:
path \Windows\system32\winload.efi
description Windows Server
locale en-US
loadoptions NO_KDNIC
inherit {bootloadersettings}
recoverysequence {c23c4005d-12ae-11eb-9399-ac9840c152e7}
displaymessageoverride Recovery
recoveryenabled Yes
bootdebug No
testsigning Yes
isolatedcontext Yes
flightsigning Yes
allowedinmemorysettings 0x15000075
osdevice partition=C:
systemroot \Windows
resumeobject {c23c4005d-12ae-11eb-9399-ac9840c152e7}
nx OptOut
debug Yes
hypervisordebug No
2. Run the bcdedit /enum command to display the generated key.
```console
C:\KDNET> bcdedit /dbgsettings
busparams 141.0.1
key 2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
debugtype NET
hostip 198.51.100.1
port 50001
dhcp Yes
The operation completed successfully.
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.1sp3yo9yz874pOpcionalmente, use kdnet.exe para confirmar se as várias funções físicas estão habilitadas.
C:\KDNET> kdnet.exe
Network debugging is supported on the following NICs:
busparams=141.0.0, Mellanox ConnectX-4 Lx Ethernet Adapter #2, Plugged in, Primary function, multiple physical functions are enabled.
busparams=141.0.1, Mellanox ConnectX-4 Lx Ethernet Adapter, KDNET is running on this NIC, Secondary function.
Network debugging is supported on the following USB controllers:
busparams=128.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=128.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
Desativar o firewall no host
No host, desative o firewall da porta do 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 do 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 arquivo .txt do bloco de notas 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 a reinicialização do PC é usar o comando shutdown -r -t 0 de um prompt de comando do administrador.
Depois que o PC de destino for reiniciado, o depurador deverá se conectar automaticamente.
Assim que a máquina for reinicializada, o firmware da NIC atribuirá um novo endereço MAC à recém-adicionada KDNET PF, e dbgsettings::busparams apontará para a PF recém-adicionada.
Como localizar o endereço MAC para o adaptador 2PF
Como a PF recém-adicionada é uma porta configurada para barramento PCI, haverá um novo valor de endereço MAC atribuído à PF recém-adicionada pelo firmware da NIC. A ferramenta kdnet.exe atualmente não suporta a exibição do endereço MAC para a 2PF adicionada.
Há duas maneiras de encontrar o novo endereço MAC:
Usar WinDbg/KD com uma sessão KD local
Execute o depurador de kernel local windbg.exe -kl no destino.
Verifique se você tem acesso ao arquivo de símbolo kdnet.pdb executando .reload /f kdnet.dll
Execute o comando .kdtargetmac para obter o endereço MAC.
kd> .kdtargetmac
Force unload of kdnet.dll
ModLoad: fffff800`18510000 fffff800`18557000 kdnet.dll
Loading symbols for fffff800`18510000 kdnet.dll -> kdnet.dll
The target machine MAC address in open-device format is: DC9840C151E8
Executar as ferramentas de firmware fornecidas pelo fornecedor
Uma maneira de localizar o endereço MAC é executar as ferramentas de firmware fornecidas pelo fornecedor. Consulte o fornecedor da NIC para obter informações sobre download, instalação e uso das ferramentas do fornecedor.
...
Base MAC: 98039baa757c 4
Localize o campo Endereço MAC. Calcule o valor do endereço MAC KDNET 2PF adicionando sequencialmente um ao último dígito do dispositivo MAC raiz. Assim, para o dispositivo raiz com um endereço de 98039baa757c, o dispositivo KDNET 2PF teria um endereço de 98039baa757d.
Como restaurar o estado de configuração anterior ― Remoção da segunda PF PCI
Você pode remover a PF adicionado anteriormente de um dispositivo usando a opção kdnet -removepf e o valor bus.device.function original. A PF será desanexada da NIC, e o recurso atribuído à PF será liberado pelo firmware da NIC.
Para remover a KDNET PF do dispositivo, abra um prompt de comando elevado e execute o seguinte comando.
kdnet -removepf [bus.dev.fun] [host name/host ip address] [port number]
Em que bus.dev.fun é a porta de localização PCI do adaptador NIC onde a PF foi originalmente conectada. Este é o mesmo local PCI originalmente passado para kdnet -addpf.
O uso da opção -removepf também reativa a depuração do kernel sobre o KDNET no bus.dev.fun original.
C:\KDNET> kdnet -removepf 141.0.0 198.51.100.1 50001
Succeeded removing a Pci PF on :141.0.0. Please power off or reboot the machine.
Enabling network debugging on Mellanox ConnectX-4 Lx Ethernet Adapter #2.
Manage-bde.exe not present. Bitlocker presumed disabled.
O comando kdnet.exe -removepf também removerá o atributo NO_KDNIC da instalação do sistema operacional {default} loadoptions, já que o KDNET será ativado no bus.dev.fun original, ou seja, o dbgsettings::busparams apontará para a porta de rede original. Isso fará com que o KDNIC seja usado novamente, fornecendo uma conexão de rede novamente sobre o KDNET.
Uma vez que a PF é removida, a máquina precisa ser reinicializada para que as alterações de BCD sejam aplicadas.
shutdown -r -t 0
Solução de problemas de configuração do adaptador de host
Verifique se o adaptador 2PF está presente no gerenciador de dispositivos
Você pode verificar se a KDNET PF foi adicionada com êxito verificando se o novo adaptador NIC tem uma nova porta bus.dev.fun na lista de adaptadores do Gerenciador de dispositivos do Windows.
Este diagrama mostra três adaptadores diferentes, com o adaptador n° 2 reservado para uso pelo depurador do kernel.
Mensagens de erro comuns - adição de uma nova PF
C:\KDNET> kdnet -addpf 28.0.0 192.168.137.1 50005
Device Name:\\.\Mlx5Util
Pci Bus:28.0.0
A PCI PF já está configurada nesta porta: Erro = (0x80004004) Falha na operação da PF no dispositivo de depuração. O dispositivo de depuração não está configurado para KDNET.
- Não adicione/remova uma PF na porta raiz onde ela já foi adicionada como PF.
Mensagens de erro comuns - remoção da PF
C:\KDNET> kdnet -removepf 28.0.1 192.168.137.1 50005
Adapter is not active: Error=(0x80070002)
Device Name:\\.\Mlx5Util
Pci Bus:28.0.1
O adaptador não está ativo: Erro = (0x80070002) Falha na operação da PF no dispositivo de depuração. O dispositivo de depuração não está configurado para KDNET
- Não use uma porta PF adicionada com o parâmetro de linha de comando "-removepf/-addpf", pois qualquer operação na porta PF adicionada resultará em uma falha (erro: o adaptador não está ativo na porta), já que o driver da caixa de entrada da NIC do fornecedor está configurado para não ser executado expressamente em na PF adicionada.
- Ambas as opções de linha de comando (-addpf/-removepf) devem ser usadas somente no dispositivo PCI raiz.
C:\KDNET> kdnet -removepf 28.0.0 192.168.137.1 50005
Device Name:\\.\Mlx5Util
Pci Bus:28.0.0
Não há PCI PF para remoção nesta porta: Erro = (0x80004005) Falha na operação da PF no dispositivo de depuração. O dispositivo de depuração não está configurado para KDNET.
- Se você adicionar uma nova PF e, em seguida, decidir removê-la sem reinicializá-la, ocorrerá uma falha, uma vez que o firmware da NIC do fornecedor requer reinicializar/redefinir o HW da NIC antes que ele possa reconhecer a PF recém-adicionada.
Mensagens de erro comuns - BCDEdit
NO_KDNIC não está presente na instalação do BCD OS {default}.
- Não é recomendado usar bcdedit.exe para modificar/alterar o dispositivo de depuração (dbgsettings) depois de adicionar uma nova PF. As opções de linha de comando kdnet -addpf/removepf configurarão o dispositivo de depuração e também adicionarão/removerão automaticamente o token
NO_KDNICde/para{default}::loadoptions.
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 USB KDNET EEM (KDNET-EEM-USB)