Como configurar a depuração no modo kernel de uma máquina virtual manualmente usando uma porta COM virtual

Artigo
07/08/2024

As Ferramentas de Depuração para Windows dão suporte à depuração de kernel de uma máquina virtual. A máquina virtual pode estar localizada no mesmo computador físico que o depurador ou em um computador diferente conectado à mesma rede. Este tópico descreve como configurar a depuração de uma máquina virtual manualmente usando uma porta COM virtual via KDCOM.

Usar a rede virtual KDNET é uma opção mais rápida e é recomendada. Para obter mais informações, consulte Configurando a depuração de rede de uma máquina virtual com KDNET.

Configurando a máquina virtual de destino

O computador que executa o depurador é chamado de computador host e a máquina virtual que está sendo depurada é chamada de máquina virtual de destino.

Importante

Antes de usar o BCDEdit para alterar as informações de inicialização, talvez você precise suspender de forma temporária 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 adequadamente o PC de teste, quando os recursos de segurança estiverem desabilitados.

Na máquina virtual, em uma janela elevada do Prompt de Comando, insira os comandos a seguir.

bcdedit /debug on

bcdedit /dbgsettings porta de depuração serial:n taxa de transmissão:115200

onde n é o número de uma porta COM na máquina virtual.
Na máquina virtual, configure a porta COM para mapear para um pipe nomeado. O depurador se conectará por meio desse pipe. Para obter mais informações sobre como criar esse pipe, consulte a documentação da máquina virtual.
Inicie o depurador no modo elevado, por exemplo, em um prompt de comando do administrador. O depurador deve estar em execução no modo elevado ao depurar uma VM em um pipe serial. Depois que o depurador estiver anexado e em execução, reinicialize a VM de destino.

Iniciando a sessão de depuração usando o WinDbg

No computador host, abra o WinDbg como Administrador. O depurador deve estar em execução no modo elevado ao depurar uma VM em um pipe serial. No menu Arquivo, escolha Depuração de kernel. Na caixa de diálogo Depuração do Kernel, abra a guia COM . Marque a caixa Pipe e marque a caixa Reconectar . Para Taxa de transmissão, insira 115200. Em Redefinições, insira 0.

Se o depurador estiver em execução no mesmo computador que a máquina virtual, insira o seguinte para Porta.

\\.\pipe\PipeName.

Se o depurador estiver em execução em um computador diferente da máquina virtual, insira o seguinte para Porta.

\\VMHost\pipe\PipeName

Selecione OK.

Você também pode iniciar o WinDbg na linha de comando. Se o depurador estiver em execução no mesmo computador físico que a máquina virtual, insira o comando a seguir em uma janela do Prompt de Comando.

windbg -k com:pipe,port=\\.\pipe\PipeName,resets=0,reconnect

Se o depurador estiver em execução em um computador físico diferente da máquina virtual, insira o comando a seguir em uma janela do Prompt de Comando.

windbg -k com:pipe,port=\\VMHost\pipe\PipeName,resets=0,reconnect

Iniciando a sessão de depuração usando KD

Para depurar uma máquina virtual em execução no mesmo computador físico que o depurador, insira o comando a seguir em uma janela do Prompt de Comando com privilégios elevados .

kd -k com:pipe,port=\\.\pipe\PipeName,resets=0,reconnect

Para depurar uma máquina virtual que está sendo executada em um computador físico diferente do depurador, insira o comando a seguir em uma janela do Prompt de Comando.

kd -k com:pipe,port=\\VMHost\pipe\PipeName,resets=0,reconnect

Parâmetros

VMHost
Especifica o nome do computador em que a máquina virtual está sendo executada.

PipeName
Especifica o nome do pipe que você criou na máquina virtual.

redefinições=0
Especifica que um número ilimitado de pacotes de redefinição pode ser enviado ao destino quando o host e o destino estão sincronizando. Use o parâmetro resets=0 para o Microsoft Virtual PC e outras máquinas virtuais cujos pipes descartam bytes em excesso. Não use esse parâmetro para VMware ou outras máquinas virtuais cujos pipes não descartam todos os bytes em excesso.

Reconectar
Faz com que o depurador desconecte e reconecte automaticamente o pipe se ocorrer uma falha de leitura/gravação. Além disso, se o depurador não encontrar o pipe nomeado quando o depurador for iniciado, o parâmetro reconnect fará com que o depurador aguarde até que um pipe chamado PipeName apareça. Use reconnect para Virtual PC e outras máquinas virtuais que destroem e recriam seus pipes durante a reinicialização do computador. Não use esse parâmetro para VMware ou outras máquinas virtuais que preservam seus pipes durante a reinicialização do computador.

Para obter mais informações sobre opções de linha de comando adicionais, consulte Opções de linha de comando KD ou Opções de linha de comando do WinDbg.

Máquinas Virtuais de Geração 2

Por padrão, as portas COM não são apresentadas em máquinas virtuais de geração 2. Você pode adicionar portas COM por meio do PowerShell ou WMI. Para que as portas COM sejam exibidas no console do Gerenciador do Hyper-V, elas devem ser criadas com um caminho.

Para habilitar a depuração de kernel usando uma porta COM em uma máquina virtual de geração 2, siga estas etapas:

Desabilite a Inicialização Segura inserindo este comando do PowerShell:

Set-VMFirmware –Vmname VmName –EnableSecureBoot Desativado

onde VmName é o nome da sua máquina virtual.
Adicione uma porta COM à máquina virtual inserindo este comando do PowerShell:

Set-VMComPort –VMName VmName 1 \\.\pipe\PipeName

Por exemplo, o comando a seguir configura a primeira porta COM na máquina virtual TestVM para se conectar ao pipe nomeado TestPipe no computador local.

Set-VMComPort –VMName TestVM 1 \\.\pipe\TestPipe
Depois que o depurador estiver anexado e em execução, pare e inicie a VM a frio para ativar as portas COM na VM.　Os UARTS emulados não estão disponíveis para depuração, a menos que pelo menos um esteja realmente configurado com um nome de pipe e eles não possam ser adicionados a quente.
Reative a inicialização segura quando terminar de atualizar as alterações de configuração.

Para obter mais informações sobre VMs de Geração 2, consulte Visão geral da Máquina Virtual de Geração 2.

Observações

Se o computador de destino parou de responder, o computador de destino ainda está parado devido a uma ação de depuração de kernel anterior ou você usou a opção de linha de comando -b, o depurador interrompe o computador de destino imediatamente.

Caso contrário, o computador de destino continuará em execução até que o depurador ordene que ele seja interrompido.

Solução de problemas de firewalls e acesso à rede

Seu depurador (WinDbg ou KD) deve ter acesso por meio do firewall. Esse pode ser o caso até mesmo de portas seriais virtuais com suporte de adaptadores de rede.

Se você for solicitado pelo Windows a desativar o firewall quando o depurador for carregado, selecione todas as três caixas.

Dependendo das especificidades da VM em uso, talvez seja necessário alterar as configurações de rede de suas máquinas virtuais para conectá-las ao Adaptador de Depuração de Rede do Kernel da Microsoft. Caso contrário, as máquinas virtuais não terão acesso à rede.

Firewall do Windows

Você pode usar o Painel de Controle para permitir o acesso por meio do firewall do Windows. Abra o Painel > de Controle Sistema e Segurança e selecione Permitir um aplicativo por meio do Firewall do Windows. Na lista de aplicativos, localize o Depurador Simbólico da GUI do Windows e o Depurador de Kernel do Windows. Use as caixas de seleção para permitir que esses dois aplicativos passem pelo firewall. Reinicie seu aplicativo de depuração (WinDbg ou KD).

VMs de terceiros

VMWare Se você reiniciar a máquina virtual usando os recursos do VMWare (por exemplo, o botão de redefinição), saia do WinDbg e reinicie o WinDbg para continuar a depuração. Durante a depuração da máquina virtual, o VMWare geralmente consome 100% da CPU.