Configurar o transporte do depurador EXDI

Artigo
11/01/2024

Este tópico descreve como configurar a depuração no modo kernel usando EXDI. A Extended Debugging Interface (EXDI) é uma camada de adaptação entre um depurador de software e um destino de depuração.

As Ferramentas de Depuração do Windows oferecem suporte à depuração do kernel usando EXDI a partir do Windows versão 22000.
A interface do usuário para configurar o EXDI está disponível no depurador a partir da versão 1.2410.11001.0.

A EXDI pode ser usada para estabelecer uma conexão com o ambiente virtual QEMU. Para obter mais informações, consulte Configurando a depuração do modo kernel QEMU usando EXDI.

Observação

EXDI é uma forma avançada e especializada de depuração para ambientes específicos. Uma conexão KDNET padrão é mais fácil de configurar e é recomendada. Para configurar a depuração de rede automaticamente, confira Configurar a depuração automática do kernel de rede KDNET.

Visão geral do servidor EXDI COM

EXDI é uma interface que estende o WinDbg adicionando suporte para depuradores de hardware (por exemplo, baseado em JTAG ou baseado em GdbServer). O diagrama abaixo ilustra a função do EXDI-GdbServer.

Diagrama de pilha que mostra a função do EXDI-GdbServer com WinDbg-DbgEng na parte superior, uma interface EXDI e um servidor EXDI COM se comunicando com um servidor GDB.

Um servidor COM refere-se a um componente binário que implementa uma interface COM. Nesse caso, exdi3.idl implementado pelo ExdiGdbSrv.dll para o cliente de protocolo do depurador do Windows.

O próprio ExdiGdbsrv.dll implementa o lado do cliente do protocolo GDB-RSP, o lado do servidor GDB (ou às vezes chamado de stub do servidor GDB) é implementado pelo servidor QEMU GDB (ou stub do servidor GDB Trace32 / OpenOCD / UEFI, etc.)

Como a conexão EXDI não depende do Windows ou do protocolo KDNET de depuração do Windows que está sendo carregado no computador de destino. Como esses componentes do depurador de software não são necessários, o EXDI pode ser útil na ativação inicial do dispositivo e na depuração de problemas de inicialização do sistema operacional.

Importante

Como a EXDI não usa o protocolo KDNET, o depurador conectado tem significativamente menos informações sobre o que está sendo executado no PC e muitos comandos funcionarão de forma diferente ou podem não funcionar. O acesso a símbolos privados para o código que está sendo depurado pode ajudar o depurador a entender melhor a execução do código do sistema de destino. Para obter mais informações, confira Símbolos Públicos e Privados.

Requisitos do dispositivo EXDI no modo kernel

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

Os seguintes itens são necessários:

No computador de destino e host, uma placa de rede compatível com o ambiente desejado, como QEMU.
Uma conexão de rede entre o destino e o host usando TCP/IP.
Windows 10 ou Windows 11 versão 22000 ou posterior.

Limitações

Como descrito acima, como a EXDI não faz uso do protocolo KDNET, o depurador conectado tem menos informações sobre o sistema de destino, e o uso do depurador é diferente. Sem acesso a símbolos privados para o código de destino, muitos comandos que usam símbolos para entender o estado do sistema de destino não funcionarão. Nesse caso, é possível visualizar a memória, registrar conteúdos e desmontar códigos. Sem símbolos privados, determinar o local da execução do código ou executar outras tarefas comuns do depurador pode ser muito difícil e demorado.

Depuração simultânea de EXDI e KDNET

Em alguns cenários complexos, por exemplo, na ativação inicial do dispositivo, pode ser útil ter duas conexões com o dispositivo de destino. Uma EXDI e uma KDNET. Se o destino for um sistema operacional Windows, a depuração de software KDNET será configurada normalmente, por exemplo, para se conectar a uma máquina virtual. Nessa configuração, qualquer um dos dois depuradores simultâneos pode entrar para depurar códigos no computador de destino.

WinDbg no servidor de processo

O componente EXDI binário pode ser executado fora do processo Windbg ou dentro do processo Windbg. O uso da interface do usuário EXDI ou do melhora substancialmente a Inproc=<EXDI COM server binary> confiabilidade, reduzindo os erros de inicialização COM. Portanto, é sempre recomendável executar a sessão EXDI com o parâmetro Inproc, que está sempre habilitado ao usar a interface do usuário.

Para inicialização de linha de comando, a opção padrão é fora do processo, mas o inprocess deve ser habilitado usando o InProc=ExdiGdbDrv.dll parâmetro.

Cliente servidor COM GDB

Este tópico descreve o uso do cliente do Servidor GDB (ExdiGdbSrv.dll EXDI), que implementa a interface do depurador EXDI COM. É possível usar a mesma interface COM para implementar outras interfaces, como um servidor EXDI COM para JTAG-DCI.

Resumo do processo para usar uma conexão EXDI

Use este processo para usar uma conexão EXDI com o WinDbg.

Baixe e instale as ferramentas de depuração do Windows no sistema host.
Inicie o WinDbg usando a interface do usuário ou a opção -kx para se conectar ao servidor EXDI.
Use o WinDbg para depurar o sistema de destino usando um subconjunto de comandos de depurador disponíveis.

Para obter um exemplo de cenário de uso de EXDI, consulte Configurando a depuração do modo kernel QEMU usando EXDI.

Baixe e instale as Ferramentas de Depuração do Windows.

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

Inicie o WinDbg e conecte-se ao servidor EXDI

As opções a seguir podem ser configuradas na interface do usuário de conexão do kernel EXDI.

Interface do usuário de conexão do kernel EXDI do Windbg, com opções de conexão mostradas, incluindo IP e endereço de porta.

Tipo de destino [Trace32|BMC-OpenOCD|QEMU|VMWare|UEFI] Selecione de acordo com o tipo de destino que você deseja depurar. Os seguintes tipos de destino estão disponíveis.
- Trace32 : Configuração do servidor GDB do depurador de hardware Lauterbach Trace32
- BMC-OpenOCD : Configuração do servidor GDB do depurador de HW BMC-OpenOCD
- QEMU : Configuração do servidor GDB do simulador do SW do QEMU
- VMWare : Configuração do servidor VMWare GDB
- UEFI: Depuração de firmware UEFI
Arquitetura [x86 | ARM64 | x64] de destino - Arquitetura do processador de destino. Observe que todos os tipos de destino podem não suportar todas as arquiteturas de destino.
SO [Windows|Linux] de destino - Selecione de acordo com o SO de destino que você gostaria de depurar.
Tamanho [None | 0xFE - PreNT |0xFFE - NT] heurístico da digitalização de imagens - Selecione uma das três opções para determinar o tamanho heurístico da digitalização de imagens. Esse valor configura como o mecanismo do depurador verifica a memória procurando a assinatura do PE DOS, que é usada para coletar o estado de execução do código. Se o valor do atributo não for especificado (ou "0"), o mecanismo do depurador não usará a heurística rápida e retornará à heurística herdada que verifica toda a memória em busca da assinatura do PE DOS. O valor padrão é selecionado para cada tipo de destino e é recomendado.
Servidor e porta TargetIPAddress:TargetPortAddress Gdb - Defina como uma string que contém o IPTargetAddress, dois pontos e o PortAddress de destino. Por exemplo: LocalHost:1234 ou 168.82.1.5:5555.
Interromper conexões [on|off] Marque a caixa de seleção para entrar no destino depois que a conexão for estabelecida.
Opções avançadas

Mostrar log [on|off] de pacotes de comunicação - Marque a caixa de seleção para exibir em valores hexadecimais o log de pacotes de comunicações GDBServer bruto para depuração e solução de problemas.

Depois que as opções desejadas forem selecionadas, selecione Ok para conectar.

Configurar opções avançadas usando os arquivos XML de configuração EXDI

As opções mais necessárias estão disponíveis na interface do usuário descrita neste tópico. Para obter informações sobre como configurar opções avançadas usando os arquivos XML de configuração EXDI, consulte Arquivos de configuração XML EXDI.

Exemplo de EXDI de linha de comando do WinDbg

Para iniciar a sessão windbg que usa a interface EXDI no prompt de comando, use estas opções.

c:\Debuggers> windbg.exe -v -kx exdi:CLSID={29f9906e-9dbe-4d4b-b0fb-6acf7fb6d014},Kd=Guess,InProc=ExdiGdbDrv.dll,DataBreaks=Exdi

Para exibir uma saída adicional útil para fins de diagnóstico, é possível usar a sessão detalhada -v:. Para obter informações gerais sobre as opções do WinDbg, confira Opções de linha de comando do WinDbg. Consulte os Parâmetros de carregamento WinDbg da EXDI abaixo para obter mais informações.

O console do depurador exibirá a inicialização do transporte EXDI.

EXDI: DbgCoInitialize returned 0x00000001
EXDI: CoCreateInstance() returned 0x00000000
EXDI: QueryInterface(IExdiServer3) returned 0x00000000
EXDI: Server::GetTargetInfo() returned 0x00000000
EXDI: Server::SetKeepaliveInterface() returned 0x00000000
EXDI: Server::GetNbCodeBpAvail() returned 0x00000000
EXDI: ExdiNotifyRunChange::Initialize() returned 0x00000000
EXDI: LiveKernelTargetInfo::Initialize() returned 0x00000000
EXDI: Target initialization succeeded
Kernel Debugger connection established

Sessão principal do WinDbg exibindo CLSID da EXDI no título da janela.

A janela do console do EXDIGdbServer também pode exibir informações sobre o status da conexão EXDI. Para obter mais informações sobre o console, consulte Solução de problemas.

Parâmetros de carregamento WinDbg da EXDI

Os parâmetros a seguir são usados com o WinDbg para iniciar uma sessão do kernel da EXDI.

-kx EXDI:Opções

As opções da EXDI a seguir estão disponíveis com a opção -kx. Cada opção deve ser separada por vírgula.

Parâmetro	Descrição
CLSID	ID de classe atribuída ao LiveExdiGdbSrvServer (conforme definido no arquivo ExdiGdbSrv.idl).
Kd=Adivinhe -ou- NtBaseAddr	O mecanismo do depurador usará um mecanismo heurístico geral -ou- procurará o endereço base do NT.
ForceX86	Força o mecanismo do depurador a usar a interface IeXdiX86Context3 para obter/definir o contexto da CPU.
DataBreaks=Exdi	Permita o uso de pontos de interrupção de dados.
Inproc	Permita o uso de um Exdi-Server inproc. Esta opção é recomendada - InProc=ExdiGdbDrv.dll
CaminhoToSrvCfgFiles	O caminho para os arquivos de configuração XML para EXDI.

Controlando a pesquisa heurística e o tamanho heurístico

Conforme descrito anteriormente, o depurador usa um algoritmo heurístico para localizar o endereço base do NT. Para cancelar a pesquisa heurística, ao iniciar o WinDbg por meio da linha de comando, conclua as etapas a seguir.

Defina o heuristicScanSize como 0 no arquivo exdiconfigdata.xml do servidor de destino ao qual você será anexado.
Use o kd=NtBaseAddr tipo heurístico na linha de comando do Windbg.

Para obter mais informações sobre como trabalhar com arquivos de configuração XML, consulte Arquivos de configuração XML EXDI.

Usar o WinDbg para depurar o sistema de destino – pontos de interrupção

O dbgeng.dll usa um algoritmo heurístico para encontrar o local do endereço de carga base do NT no momento em que ocorreu o comando de interrupção. Se os símbolos privados não estiverem disponíveis, esse processo falhará.

Isso significa que, em muitas sequências de conexão, a interrupção não funcionará conforme o esperado. Se você interromper manualmente o código, será um local aleatório que o Windows estava executando naquele momento. Como os símbolos para o código de destino podem não estar disponíveis, pode ser difícil definir pontos de interrupção usando símbolos.

Comandos do depurador

Como os seguintes comandos que acessam a memória diretamente funcionarão.

k, kb, kc, kd, kp, kP, kv (Exibir Backtrace da Pilha)

r (Registros)

d, da, db, dc, dd, dD, df, dp, dq, du, dw (Display Memory)

u (Desmontar)

E você pode percorrer o código usando p (Etapa).

Há também comandos que podem ser usados para tentar localizar o código que você deseja depurar.

s (Memória de Pesquisa)

.imgscan (Localizar cabeçalhos de imagem)

Imgscan pode ser útil com a depuração EDXI, pois ao contrário da depuração de kernel baseada em KDNET tradicional, a definição de pontos de interrupção com base em símbolos pode não estar disponível. Localizar uma imagem de destino desejada pode facilitar o uso de sua localização para definir um ponto de interrupção de acesso à memória.

.exdicmd (Comando EXDI)

O .exdicmd envia um comando EXDI para o sistema de destino usando a conexão de depuração EXDI ativa. Para obter mais informações, confira .exdicmd (Comando EXDI).

Solução de problemas

Use a saída da janela ExdiGdbServer para monitorar a sequência de conexão.

Janela de texto ExdiGdbServer exibindo números hexadecimais longos.

Problema: Erro: Não é possível estabelecer uma conexão com o GbDServer. Verificar a cadeia de conexão <hostname/ip>:portnumber

Esse problema pode ser causado pelo seguinte:

O ExdiGdbSrv.dll não pode se conectar ao servidor GDB de destino.
O servidor GDB ainda não está em execução no destino.
Problemas de firewall, certifique-se de que ambos os endereços IP estejam acessíveis usando ping, tracert ou alguma outra ferramenta para verificar se o tráfego GDB pode passar pelo firewall.

Problema: O cenário de erro com o sistema de destino não está disponível - DbgCoInitialize retornou 0x00000001

A saída a seguir poderá ser retornada se o sistema de destino não estiver carregado ou não estiver disponível.

Microsoft (R) Windows Debugger Version 10.0.20317.1 AMD64
Copyright (c) Microsoft Corporation. All rights reserved.

EXDI: DbgCoInitialize returned 0x00000001

Este é um erro comum quando o servidor COM ExdiGdbSrv.dll não consegue se conectar ao QEMU GDServer, portanto, ele pode falhar devido a:

A sessão anterior do ExdiGdbSrv.dll ainda é hospedada por um processo dllhost.exe. Então, você precisará encerrar o processo dllhost.exe. Use TaskList em um prompt de comando para localizar o PID do dllhost.exe que hospeda o ExdiGdbSrv.dll. Use TaskKill /PID <PID ID> /f e elimine o PID associado. Para obter mais informações sobre como trabalhar com PIDs, consulte Localizando a ID do processo.
O gdbserver QEMU ainda não foi iniciado ou o arquivo exdiconfigdata.xml contém valores IP:Port inválidos. Se a sessão WinDbg for iniciada no mesmo PC host que a VM QEMU do Windows, o IP=LocalHost.
Falha ao iniciar o servidor EXDI COM (ExdiGDbSrv.dll) por meio do processo dllhost.exe (relacionado ao COM). Para resolver isso, reinicie o PC do depurador Host ou saia e entre novamente no Windows. Se isso não funcionar, registre novamente o servidor EXDI COM depois de reiniciar/entrar novamente.
- regsvr32.exe <full path to the ExdiGdbSrv.dll)

Problema: Não foi possível inciar a sessão de depuração: FAILURE HR=0x80004005:Failed to AttachKernel.

Esse problema pode ser causado pelo seguinte:

Como descrito acima, é possível que a sessão anterior do ExdiGdbSrv.dll ainda esteja ativa. Localize e encerre o host DLL associado conforme descrito acima.

Caixa de diálogo WinDbg exibindo falha com HR 0x80004005.

Problema: Não foi possível iniciar a depuração do kernel usando EXDI.

Esse problema pode ser causado pelo seguinte:

Há outra instância do ExdiGdbSrv.dll (hospedada por dllhost.exe) em execução no computador do depurador de host.
Encerre a instância extra do serviço COM que hospeda o ExdiGdbSrv.dll.
- Primeiro liste os processos usando utilitários como TList no PC host. O DLLHost que está hospedando o ExdiGdbSrv.dll mostrará ExdiGdbServer.
  
  tlist 261928 dllhost.exe ExdiGdbServer
- Use kill -f XXXXX no prompt de comando do depurador para encerrar o processo usando o número do processo.

Problema: Erro: Não é possível configurar a sessão do GdbServer.

Esse problema pode ser causado pelo seguinte:

Ocorreu um erro ao localizar as informações da sessão, como o caminho para os arquivos de configuração XML.

Problema: Erro: A variável de ambiente EXDI_GDBSRV_XML_CONFIG_FILE não está definida.

Esse problema pode ser causado pelo seguinte:

As variáveis de ambiente ExdiGdbSrv.dll não estão definidas ou não estão disponíveis no ambiente.

Problema: erro: a variável de ambiente EXDI_GDBSRV_XML_CONFIG_FILE não está definida. O exemplo Exdi-GdbServer não continuará neste momento. Defina o caminho completo para o arquivo de configuração Exdi XML.

Esse problema pode ser causado pelo seguinte:

A variável de ambiente EXDI_GDBSRV_XML_CONFIG_FILE não está definida. Em algumas situações, ExdiGDbSrv.dll continuaria funcionando se você pressionar o botão "OK", mas windbg.exe falhará ao consultar os registros do sistema (por exemplo, por meio das funções rdmsr/wrmsr).