Configuración del transporte del depurador EXDI

Artículo
11/01/2024

En este tema se describe cómo configurar la depuración en modo kernel mediante EXDI. La interfaz de depuración extendida (EXDI) es una capa de adaptación entre un depurador de software y un destino de depuración.

Las herramientas de depuración para Windows admiten la depuración de kernel mediante EXDI a partir de la versión 22000 de Windows.
La interfaz de usuario para configurar EXDI está disponible en el depurador a partir de la versión 1.2410.11001.0.

EXDI se puede usar para establecer una conexión con el entorno virtual de QEMU. Para obtener más información, consulte Configuración de la depuración en modo kernel de QEMU mediante EXDI.

Nota:

EXDI es una forma avanzada y especializada de depuración para entornos específicos. El uso de una conexión KDNET estándar es más fácil de configurar y se recomienda. Para configurar la depuración de red automáticamente, consulte Configuración automática de la depuración del kernel de red KDNET.

Introducción al servidor COM de EXDI

EXDI es una interfaz que amplía WinDbg agregando compatibilidad con depuradores de hardware (por ejemplo, basados en JTAG o basados en GdbServer). En el diagrama siguiente se muestra el rol de EXDI-GdbServer.

Diagrama de pila que muestra el rol de EXDI-GdbServer con WinDbg-DbgEng en la parte superior, una interfaz EXDI y un servidor COM EXDI que se comunica con un servidor GDB.

Un servidor COM hace referencia a un componente binario que implementa una interfaz COM. En este caso, exdi3.idl implementado por ExdiGdbSrv.dll para el cliente del protocolo de depurador de Windows.

El ExdiGdbsrv.dll implementa el lado cliente del protocolo GDB-RSP, el lado del servidor GDB (o algún tiempo denominado código auxiliar del servidor GDB) se implementa mediante el servidor GDB QEMU (o el código auxiliar del servidor GDB trace32/OpenOCD/UEFI GDB, etc.).

Como la conexión EXDI no tiene ninguna dependencia en Windows o en el protocolo KDNET de depuración de Windows que se carga en el equipo de destino. Dado que estos componentes del depurador de software no son necesarios, EXDI puede ser útil en los primeros problemas de inicio del sistema operativo y en la depuración de problemas de inicio del sistema operativo.

Importante

Dado que EXDI no usa el protocolo KDNET, el depurador conectado tiene mucha menos información sobre lo que se ejecuta en el equipo y muchos comandos funcionarán de forma diferente o no funcionarán en absoluto. El acceso a símbolos privados para el código que se depura puede ayudar al depurador a comprender mejor la ejecución del código de los sistemas de destino. Para obtener más información, consulte Símbolos públicos y privados.

Requisitos del dispositivo EXDI en modo kernel

El equipo que ejecuta el depurador se denomina equipo host y el equipo que se depura se denomina equipo de destino.

Se necesita lo siguiente:

En el equipo host y de destino, una tarjeta de red compatible con el entorno deseado, como QEMU.
Una conexión de red entre el destino y el host mediante TCP/IP.
Windows 10 o Windows 11, versión 22000 o posterior.

Limitaciones

Como se ha descrito anteriormente, dado que EXDI no usa el protocolo KDNET, el depurador conectado tiene menos información sobre el sistema de destino y el uso del depurador es diferente. Sin acceso a símbolos privados para el código de destino, muchos comandos que usan símbolos para comprender el estado del sistema de destino no funcionarán. En este caso, es posible ver la memoria y registrar el contenido y el código de desensamblaje. Determinar la ubicación del código en ejecución o realizar otras tareas comunes del depurador puede ser muy difícil y llevar mucho tiempo sin símbolos privados.

Depuración simultánea de EXDI y KDNET

En algunos escenarios complejos, por ejemplo, en el inicio del dispositivo, puede ser útil tener dos conexiones al dispositivo de destino. Una EXDI y una KDNET. Si el destino es un sistema operativo Windows, la depuración de software KDNET se configura como lo haría normalmente, por ejemplo, para conectarse a una máquina virtual. En esta configuración, cualquiera de los dos depuradores simultáneos puede interrumpir para depurar código en la máquina de destino.

WinDbg en el servidor de procesos

El componente EXDI binario puede ejecutarse fuera del proceso windbg o dentro del proceso de Windbg. El uso de la interfaz de usuario exDI o la mejora considerablemente la Inproc=<EXDI COM server binary> confiabilidad, al reducir los errores de inicio com. Por lo tanto, siempre se recomienda ejecutar la sesión EXDI con el parámetro Inproc, que siempre está habilitado al usar la interfaz de usuario.

Para el inicio de la línea de comandos, la opción predeterminada está fuera del proceso, pero el proceso debe habilitarse mediante el InProc=ExdiGdbDrv.dll parámetro .

Cliente servidor COM GDB

En este tema se describe el uso del cliente del servidor GDB COM de EXDI (ExdiGdbSrv.dll), que implementa la interfaz del depurador COM de EXDI. Es posible usar la misma interfaz COM para implementar otras interfaces, como un servidor COM EXDI para JTAG-DCI.

Resumen del proceso para usar una conexión EXDI

Use este proceso para usar una conexión EXDI con WinDbg.

Descargue e instale las herramientas de depuración de Windows en el sistema host.
Inicie WinDbg mediante la interfaz de usuario o la opción -kx para conectarse al servidor EXDI.
Use WinDbg para depurar el sistema de destino mediante un sub conjunto de comandos disponibles del depurador.

Para obtener un ejemplo de escenario de uso de EXDI, consulte Configuración de la depuración en modo kernel de QEMU mediante EXDI.

Descarga e instalación de las herramientas de depuración de Windows

Instale las herramientas de depuración de Windows en el sistema host. Para obtener información sobre cómo descargar e instalar las herramientas del depurador, consulte Herramientas de depuración para Windows.

Inicie WinDbg y conéctese al servidor EXDI.

Las siguientes opciones se pueden configurar en la interfaz de usuario de conexión del kernel exDI.

Interfaz de usuario de conexión del kernel exDI de Windbg, con las opciones de conexión mostradas, incluida la dirección IP y el puerto.

Tipo [Trace32|BMC-OpenOCD|QEMU|VMWare|UEFI] de destino Seleccione según el tipo de destino que desea depurar. Están disponibles los siguientes tipos de destino.
- Trace32: Configuración del servidor GDB del depurador Deuterbach Trace32 HW
- BMC-OpenOCD: configuración del servidor GDB del depurador BMC-OpenOCD HW
- QEMU: configuración del servidor GDB del simulador SW de QEMU
- VMWare: configuración del servidor GDB de VMWare
- UEFI: depuración de firmware UEFI
Arquitectura [x86 | ARM64 | x64] de destino: arquitectura del procesador de destino. Tenga en cuenta que es posible que todos los tipos de destino no admitan todas las arquitecturas de destino.
So [Windows|Linux] de destino: seleccione según el sistema operativo de destino que desea depurar.
Tamaño heurístico [None | 0xFE - PreNT |0xFFE - NT] de escaneo de imágenes: seleccione una de las tres opciones para determinar el tamaño heurístico para el examen de imágenes. Este valor configura cómo el motor del depurador examina la memoria en busca de la firma PE DOS, que se usa para recopilar el estado de execuición de código. Si no se especifica el valor del atributo (o "0"), el motor del depurador no usará la heurística rápida y revertirá a la heurística heredada que examina toda la memoria que busca la firma PE DOS. El valor predeterminado se selecciona para cada tipo de destino y se recomienda.
Servidor gdb y puerto: se establece en una cadena que contiene, IPTargetAddress, dos puntos y El puerto TargetIPAddress:TargetPortAddress de destinoAddress. Por ejemplo: LocalHost:1234 o 168.82.1.5:5555.
Interrumpir en las conexiones [on|off] Seleccione la casilla de verificación para interrumpir el destino una vez establecida la conexión.
Opciones avanzadas

Mostrar registro [on|off] de paquetes de comunicación: active la casilla para mostrar en valores hexadecimales el registro de paquetes de comunicaciones GDBServer sin procesar para depurar y solucionar problemas.

Una vez seleccionadas las opciones deseadas, seleccione Aceptar para conectarse.

Configuración de opciones avanzadas mediante los archivos XML de configuración de EXDI

La mayoría de las opciones necesarias están disponibles en la interfaz de usuario descrita en este tema. Para obtener información sobre cómo configurar opciones avanzadas mediante los archivos XML de configuración exDI, vea Archivos de configuración XML de EXDI.

Ejemplo de EXDI de la línea de comandos de WinDbg

Para iniciar la sesión de windbg que usa la interfaz EXDI en el símbolo del sistema, use estas opciones.

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

Para mostrar una salida adicional útil para fines de diagnóstico, se puede usar la sesión detallada -v:. Para obtener información general sobre las opciones de WinDbg, consulte Opciones de línea de comandos de WinDbg. Consulte Parámetros de carga de WinDbg de EXDI a continuación para obtener más información.

La consola del depurador mostrará la inicialización de 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

Sesión principal de WinDbg que muestra EXDI CLSID en el título de la ventana.

La ventana de la consola EXDIGdbServer también puede mostrar información sobre el estado de la conexión EXDI. Para obtener más información sobre la consola, consulte Solución de problemas.

Parámetros de carga de WinDbg de EXDI

Los parámetros siguientes se usan con WinDbg para iniciar una sesión de kernel EXDI.

-kx EXDI:Options

Las siguientes opciones de EXDI están disponibles con la opción -kx. Cada opción se debe separar mediante una coma.

Parámetro	Descripción
CLSID	ID de clase asignado al objeto LiveExdiGdbSrvServer (tal como se define en el archivo ExdiGdbSrv.idl).
Kd=Guess -or- NtBaseAddr	El motor del depurador usará un mecanismo heurístico general (o bien) buscará la dirección base NT.
ForceX86	Obliga al motor del depurador a usar la interfaz IeXdiX86Context3 para obtener o establecer el contexto de CPU.
DataBreaks=Exdi	Permitir el uso de puntos de interrupción de datos.
Inproc	Permitir el uso de un inproc Exdi-Server. Se recomienda esta opción: InProc=ExdiGdbDrv.dll
PathToSrvCfgFiles	Ruta de acceso a los archivos de configuración XML para EXDI.

Controlar la búsqueda heurística y el tamaño heurístico

Como se ha descrito anteriormente, el depurador usa un algoritmo heurístico para buscar la dirección base NT. Para cancelar la búsqueda heurística, al iniciar WinDbg a través de la línea de comandos, complete los pasos siguientes.

Establezca heuristicScanSize en 0 en el archivo exdiconfigdata.xml del servidor de destino al que se asociará.
Use el kd=NtBaseAddr tipo heurístico en la línea de comandos de Windbg.

Para obtener más información sobre cómo trabajar con archivos de configuración XML, vea Archivos de configuración XML de EXDI.

Usar WinDbg para depurar el sistema de destino: puntos de interrupción

El dbgeng.dll usa un algoritmo heurístico para buscar la ubicación de la dirección de carga base NT en el momento en que se produjo el comando break. Si los símbolos privados no están disponibles, se producirá un error en este proceso.

Esto significa que, en muchas secuencias de conexión, la interrupción no funcionará según lo previsto. Si va a irrumpir manualmente en el código, será una ubicación aleatoria que Windows estaba ejecutando en ese momento. Como es posible que los símbolos del código de destino no estén disponibles, puede ser difícil establecer puntos de interrupción mediante símbolos.

Comandos del depurador

Los comandos como los siguientes que accederán directamente a la memoria funcionarán.

k, kb, kc, kd, kp, kP, kv (Mostrar seguimiento de la pila)

r (Registros)

d, da, db, dc, dd, dD, df, dp, dq, du, dw (Mostrar memoria)

u (Desensamblaje)

Y puede recorrer el código mediante p (Paso).

También hay comandos que se pueden usar para intentar buscar código que desea depurar.

s (Memoria de búsqueda)

.imgscan (Buscar encabezados de imagen)

Imgscan puede ser útil con la depuración de EDXI, ya que a diferencia de la depuración de kernel basada en KDNET tradicional, es posible que el establecimiento de puntos de interrupción basados en símbolos no esté disponible. La ubicación de una imagen de destino deseada puede facilitar el uso de su ubicación para establecer un punto de interrupción de acceso a memoria.

.exdicmd (comando EXDI)

El .exdicmd envía un comando EXDI al sistema de destino mediante la conexión de depuración de EXDI activa. Para obtener más información, consulte .exdicmd (comando EXDI).

Solución de problemas

Use la salida de la ventana ExdiGdbServer para supervisar la secuencia de conexión.

Ventana de texto ExdiGdbServer que muestra números hexadecimales largos.

Problema: Error: No se puede establecer una conexión con GbDServer. Comprobación del cadena de conexión <hostname/ip>:portnumber

Este problema puede deberse a lo siguiente:

El ExdiGdbSrv.dll no se puede conectar al servidor GDB de destino.
El servidor GDB aún no se está ejecutando en el destino.
Problemas de firewall, asegúrese de que se puede acceder a ambas direcciones IP mediante ping, tracert o alguna otra herramienta para comprobar que el tráfico de GDB puede pasar por el firewall.

Problema: el escenario de error con el sistema de destino no está disponible - DbgCoInitialize devuelto 0x00000001

Se puede devolver la salida siguiente si el sistema de destino no está cargado o no está disponible.

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

EXDI: DbgCoInitialize returned 0x00000001

Este es un error común cuando el servidor COM de ExdiGdbSrv.dll no se pudo conectar al GDServer de QEMU, por lo que podría producir un error debido a:

La sesión anterior del ExdiGdbSrv.dll todavía está hospedada por un proceso de dllhost.exe, por lo que deberá eliminar el proceso de dllhost.exe. Use TaskList en un símbolo del sistema para buscar el PID de dllhost.exe que hospeda el ExdiGdbSrv.dll. Use TaskKill /PID <PID ID> /f y elimine el PID asociado. Para obtener más información sobre cómo trabajar con PID, vea Buscar el identificador de proceso.
El servidor gdbserver de QEMU aún no se ha iniciado o el archivo exdiconfigdata.xml contiene valores IP:Port no válidos. Si la sesión de WinDbg se inicia en el mismo equipo host que la máquina virtual Windows QEMU, ip=LocalHost.
Error al iniciar el servidor COM EXDI (ExdiGDbSrv.dll) a través del proceso de dllhost.exe (relacionado con COM). Para resolverlo, reinicie el equipo del depurador host o cierre sesión de Windows y vuelva a iniciar sesión. Si eso no funciona, vuelva a registrar el servidor COM EXDI después de reiniciar o iniciar sesión de nuevo.
- regsvr32.exe <full path to the ExdiGdbSrv.dll)

Problema: no se pudo iniciar la sesión de depuración: FAILURE HR=0x80004005:Failed to AttachKernel.

Este problema puede deberse a lo siguiente:

Como se ha descrito anteriormente, es posible que la sesión anterior de la ExdiGdbSrv.dll siga activa. Busque y finalice el host DLL asociado como se ha descrito anteriormente.

Cuadro de diálogo WinDbg en el que se muestra un error con HR 0x80004005.

Problema: No se pudo iniciar la depuración del kernel mediante EXDI.

Este problema puede deberse a lo siguiente:

Hay otra instancia de ExdiGdbSrv.dll (hospedado por dllhost.exe) que se ejecuta en la máquina del depurador host.
Finalice la instancia adicional del servicio COM que hospeda ExdiGdbSrv.dll.
- En primer lugar, enumere los procesos mediante una utilidad como TList en el equipo host. DLLHost que hospeda ExdiGdbSrv.dll mostrará ExdiGdbServer.
  
  tlist 261928 dllhost.exe ExdiGdbServer
- Use kill -f XXXXX en el símbolo del sistema del depurador para finalizar el proceso mediante el número de proceso.

Problema: Error: No se puede configurar la sesión de GdbServer.

Este problema puede deberse a lo siguiente:

Error al buscar la información de sesión, como la ruta de acceso a los archivos de configuración XML.

Problema: Error: la variable de entorno EXDI_GDBSRV_XML_CONFIG_FILE no está definida.

Este problema puede deberse a lo siguiente:

Las variables de entorno de ExdiGdbSrv.dll no están definidas o no están disponibles en el entorno.

Problema: Error: la variable de entorno EXDI_GDBSRV_XML_CONFIG_FILE no está definida. El ejemplo Exdi-GdbServer no continuará en este momento. Establezca la ruta de acceso completa en el archivo de configuración XML de Exdi.

Este problema puede deberse a lo siguiente:

La variable de entorno EXDI_GDBSRV_XML_CONFIG_FILE no está definida. En algunas situaciones, ExdiGDbSrv.dll seguiría funcionando si pulsa el botón "Aceptar", pero windbg.exe fallará al consultar registros del sistema (por ejemplo, a través de funciones rdmsr/wrmsr).