Настройка транспорта отладчика EXDI

2024-11-01

В этом разделе описывается настройка отладки в режиме ядра с помощью EXDI. Интерфейс расширенной отладки (EXDI) — это уровень адаптации между отладчиком программного обеспечения и целевым объектом отладки.

Средства отладки для Windows поддерживают отладку ядра с помощью EXDI, начиная с Windows версии 22000.
Пользовательский интерфейс для настройки EXDI доступен в отладчике, начиная с версии 1.2410.11001.0.

EXDI можно использовать для установления подключения к виртуальной среде QEMU. Дополнительные сведения см. в разделе "Настройка отладки в режиме ядра QEMU с помощью EXDI".

Примечание.

EXDI — это расширенная специализированная форма отладки для определенных сред. Использование стандартного подключения KDNET проще настроить и рекомендуется. Чтобы настроить автоматическую отладку сети, см. раздел "Настройка автоматической отладки сетевого ядра KDNET".

Общие сведения о сервере EXDI COM

EXDI — это интерфейс, который расширяет WinDbg, добавив поддержку аппаратных отладчиков (например, на основе JTAG или GdbServer). На приведенной ниже схеме показана роль EXDI-GdbServer.

Схема стека, отображающая роль EXDI-GdbServer с WinDbg-DbgEng, расположенным сверху, интерфейсом EXDI и сервером EXDI COM, взаимодействующим с сервером GDB.

COM-сервер ссылается на двоичный компонент, реализующий COM-интерфейс. В этом случае exdi3.idl реализован в ExdiGdbSrv.dll для использования клиентом протокола отладчика Windows.

Сам ExdiGdbsrv.dll реализует клиентскую сторону протокола GDB-RSP, а серверная сторона GDB (или, как ее иногда называют, заглушка сервера GDB) реализуется сервером QEMU GDB (или заглушкой сервера GDB для Trace32/OpenOCD/UEFI и т. д.).

Так как подключение EXDI не зависит от Windows или протокола KDNET отладки Windows, загружаемого на целевом компьютере. Так как эти компоненты отладчика программного обеспечения не требуются, EXDI может оказаться полезным в начале запуска устройства и при отладке проблем с запуском ОС.

Внимание

Так как EXDI не использует протокол KDNET, подключенный отладчик имеет значительно меньше сведений о том, что выполняется на компьютере, и многие команды будут работать по-разному или не работать вообще. Доступ к частным символам для отлаживаемого кода может помочь отладчику лучше понять выполнение кода целевых систем. Дополнительные сведения см. в разделе "Открытые и частные символы".

Требования к устройству в режиме ядра EXDI

Компьютер, на котором выполняется отладчик, называется главным компьютером, а отлаживаемый компьютер называется целевым компьютером.

Требуется следующее:

На целевом и хост-компьютере установлена сетевая карта, совместимая с нужной средой, такой как QEMU.
Сетевое подключение между целевым объектом и узлом с помощью TCP/IP.
Windows 10 или Windows 11 версии 22000 или более поздней.

Ограничения

Как описано выше, так как EXDI не использует протокол KDNET, подключенный отладчик имеет меньше сведений о целевой системе, а использование отладчика отличается. Без доступа к частным символам для целевого кода многие команды, использующие символы для понимания состояния целевой системы, не будут работать. В этом случае можно просматривать память и регистрировать содержимое и дизассемблировать код. Определение расположения запуска кода или выполнение других распространенных задач отладчика может быть очень сложным и трудоемким без закрытых символов.

Одновременная отладка EXDI и KDNET

В некоторых сложных сценариях, например в начале запуска устройства, может быть полезно иметь два подключения к целевому устройству. Один EXDI и один KDNET. Если целевой объект является ОС Windows, отладка программного обеспечения KDNET настраивается как обычно, например для подключения к виртуальной машине. В этой настройке любой из двух одновременных отладчиков может вмешаться для отладки кода на целевом компьютере.

WinDbg на сервере процессов

Двоичный компонент EXDI может работать вне процесса Windbg или внутри процесса Windbg. Использование пользовательского интерфейса EXDI или Inproc=<EXDI COM server binary> значительно повышает надежность, уменьшая ошибки запуска COM. Поэтому всегда рекомендуется запускать сеанс EXDI с параметром Inproc, который всегда включен при использовании пользовательского интерфейса.

По умолчанию запуск командной строки происходит вне процесса, но для включения выполнения в процессе необходимо использовать параметр InProc=ExdiGdbDrv.dll.

Клиент СЕРВЕРА COM GDB

В этом разделе описывается использование клиента СЕРВЕРА COM GDB EXDI (ExdiGdbSrv.dll), реализующего интерфейс отладчика EXDI COM. Можно использовать тот же com-интерфейс для реализации других интерфейсов, таких как COM-сервер EXDI для JTAG-DCI.

Сводка процесса использования подключения EXDI

Используйте этот процесс для использования подключения EXDI с WinDbg.

Скачайте и установите средства отладки Windows в хост-системе.
Запустите WinDbg с помощью пользовательского интерфейса или параметра -kx для подключения к серверу EXDI.
Используйте WinDbg для отладки целевой системы с помощью подсети доступных команд отладчика.

Пример сценария использования EXDI см. в разделе Настройка отладки режима ядра QEMU с помощью EXDI.

Скачивание и установка средств отладки Windows

Установите средства отладки Windows в хост-системе. Сведения о скачивании и установке средств отладчика см. в разделе "Средства отладки" для Windows.

Запустите WinDbg и подключитесь к серверу EXDI

Следующие параметры можно настроить в пользовательском интерфейсе подключения ядра EXDI.

Пользовательский интерфейс подключения ядра Windbg EXDI с параметрами подключения, включая IP-адрес и адрес порта.

Целевой тип[Trace32|BMC-OpenOCD|QEMU|VMware|UEFI] Выберите в соответствии с типом цели, который вы хотите отладить. Доступны следующие типы целевых объектов.
- Trace32: конфигурация сервера отладчика GDB Lauterbach Trace32 HW
- BMC-OpenOCD: конфигурация сервера GDB отладчика BMC-OpenOCD HW
- QEMU: конфигурация сервера GDB программного симулятора QEMU
- VMware: конфигурация сервера VMware GDB
- UEFI: отладка встроенного ПО UEFI
Целевая архитектура[x86 | ARM64 | x64] — архитектура целевого процессора. Обратите внимание, что все целевые типы могут не поддерживать все целевые архитектуры.
Целевая ОС[Windows|Linux] — выберите в соответствии с целевой ОС для отладки.
Эвристический размер сканирования изображений[None | 0xFE - PreNT |0xFFE - NT] — выберите один из трех вариантов, чтобы определить размер для эвристического сканирования изображений. Это значение настраивает способ, которым модуль отладки сканирует память в поисках сигнатуры PE DOS, используемой для получения состояния выполнения кода. Если значение атрибута не указано (или "0"), подсистема отладчика не будет использовать быструю эвристику и вернётся к устаревшей эвристике, которая сканирует всю память в поисках сигнатуры PE DOS. Значение по умолчанию выбрано для каждого целевого типа и рекомендуется.
Сервер Gdb и портTargetIPAddress:TargetPortAddress — задайте строку, содержащую IPTargetAddress, двоеточие и целевой портAddress. Пример: LocalHost:1234 или 168.82.1.5:5555.
Остановить соединение[on|off] Установите флажок, чтобы войти в целевой объект после установления подключения.
Дополнительные параметры

Отображение журнала пакетов связи. Установите флажок для отображения шестнадцатеричных значений необработанного журнала[on|off] пакетов связи GDBServer для отладки и устранения неполадок.

После выбора нужных параметров нажмите кнопку "ОК ", чтобы подключиться.

Настройка дополнительных параметров с помощью XML-файлов конфигурации EXDI

Наиболее необходимые параметры доступны в пользовательском интерфейсе, описанном в этом разделе. Сведения о настройке дополнительных параметров с помощью XML-файлов конфигурации EXDI см. в файлах конфигурации EXDI XML.

Пример командной строки WinDbg для EXDI

Чтобы запустить сеанс windbg, использующий интерфейс EXDI в командной строке, используйте эти параметры.

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

Чтобы отобразить дополнительные выходные данные, полезные для диагностики, можно использовать подробный сеанс -v. Общие сведения о параметрах WinDbg см. в разделе "Параметры командной строки WinDbg". Дополнительные сведения см. ниже в разделе Параметры загрузки WinDbg EXDI.

Консоль отладчика отобразит инициализацию транспорта 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

Основной сеанс WinDbg, отображающий CLSID EXDI в заголовке окна.

Окно консоли EXDIGdbServer также может отображать сведения о состоянии подключения EXDI. Дополнительные сведения о консоли см. в разделе "Устранение неполадок".

Параметры загрузки EXDI WinDbg

Для запуска сеанса ядра EXDI используются следующие параметры с WinDbg.

-kx EXDI:Options

Следующие параметры EXDI доступны с параметром -kx. Каждый параметр должен быть разделен с помощью запятой.

Параметр	Описание
CLSID	Идентификатор класса, назначенный LiveExdiGdbSrvServer (как определено в файлеExdiGdbSrv.idl).
Kd=Guess -или- NtBaseAddr	Движок отладчика будет использовать общие эвристические механизмы или искать адрес базы NT.
ForceX86	Заставляет отладчик использовать интерфейс IeXdiX86Context3 для получения и настройки контекста центрального процессора.
DataBreaks=Exdi	Разрешить использование точек останова данных.
Inproc	Разрешить использование сервера Exdi inproc. Этот параметр рекомендуется — InProc=ExdiGdbDrv.dll
PathToSrvCfgFiles	Путь к XML-файлам конфигурации для EXDI.

Контроль эвристического поиска и размера эвристики

Как описано ранее, отладчик использует эвристические алгоритмы для поиска базового адреса NT. Чтобы отменить эвристические поиски, при запуске WinDbg с помощью командной строки выполните следующие действия.

Установите для heuristicScanSize значение 0 в файле exdiconfigdata.xml для целевого сервера, к которому вы присоединяетесь.
Используйте эвристический тип в командной строке kd=NtBaseAddr Windbg.

Дополнительные сведения о работе с XML-файлами конфигурации см. в разделе EXDI XML Configuration files.

Отладка целевой системы с помощью WinDbg — точки останова

Dbgeng.dll использует эвристические алгоритмы для поиска расположения базового адреса загрузки NT во время выполнения команды останова. Если закрытые символы недоступны, этот процесс завершится ошибкой.

Это означает, что при множестве последовательностей подключений разрыв не будет функционировать должным образом. Если вы вручную проникнете в код, это будет случайная точка исполнения, на которой Windows выполнялся в данный момент. Так как символы целевого кода могут быть недоступны, может быть трудно задать точки останова с помощью символов.

Команды отладчика

Команды, которые прямо обращаются к памяти, такие как указанные ниже, будут работать.

k, kb, kc, kd, kp, kP, kv (Отобразить трассировку стека)

r (Регистр)

d, da, db, dc, dd, dD, df, dp, dq, du, dw (видеопамять)

u (Unassemble)

И вы можете выполнить пошаговое выполнение кода с помощью P (Step).

Существуют также команды, которые можно использовать для поиска кода, который требуется выполнить отладку.

s (память поиска)

.imgscan (поиск заголовков изображений)

Imgscan может быть полезным при отладке EDXI, так как в отличие от традиционной отладки ядра на основе KDNET, установка точек останова на основе символов может быть недоступна. Поиск требуемого целевого образа может упростить использование его расположения для задания точки останова доступа к памяти.

.exdicmd (команда EXDI)

Команда .exdicmd отправляет EXDI-команду в целевую систему через активное подключение для отладки EXDI. Дополнительные сведения см. в разделе .exdicmd (команда EXDI).

Устранение неполадок

Используйте выходные данные из окна ExdiGdbServer для мониторинга последовательности подключений.

Текстовое окно ExdiGdbServer с длинными шестнадцатеричными числами.

Проблема: ошибка: не удается установить соединение с GbDServer. Проверка строка подключения <hostname/ip>:portnumber

Эта проблема может быть вызвана следующими причинами:

ExdiGdbSrv.dll не удается подключиться к целевому серверу GDB.
Сервер GDB еще не запущен в целевом объекте.
Проблемы с брандмауэром, убедитесь, что оба IP-адреса доступны с помощью ping, tracert или другого средства, чтобы убедиться, что трафик GDB может проходить через брандмауэр.

Проблема: Сценарий ошибки с целевой системой недоступен — DbgCoInitialize вернул 0x00000001

Следующие выходные данные могут быть возвращены, если целевая система не загружена или недоступна.

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

EXDI: DbgCoInitialize returned 0x00000001

Это распространенная ошибка, когда COM-сервер ExdiGdbSrv.dll не смог подключиться к QEMU GDServer, поэтому может произойти сбой по следующим причинам:

Предыдущий сеанс ExdiGdbSrv.dll по-прежнему размещен процессом dllhost.exe, поэтому необходимо убить процесс dllhost.exe. Используйте TaskList в командной строке, чтобы найти PID процесса dllhost.exe, который размещает ExdiGdbSrv.dll. Используйте TaskKill /PID <PID ID> /f и убейте связанный идентификатор процесса. Дополнительные сведения о работе с piD см. в разделе "Поиск идентификатора процесса".
Сервер gdbserver QEMU еще не запущен или файл exdiconfigdata.xml содержит недопустимые значения IP:Port. Если сеанс WinDbg запускается на том же компьютере узла, что и виртуальная машина Windows QEMU, то IP=LocalHost.
Сбой при запуске COM-сервера EXDI (ExdiGDbSrv.dll) через процесс dllhost.exe (связанный COM). Чтобы устранить эту проблему, перезапустите компьютер, на котором выполняется отладка, или выйдите из Windows и войдите снова. Если это не работает, повторно зарегистрируйте COM-сервер EXDI после перезапуска или входа снова.
- regsvr32.exe <full path to the ExdiGdbSrv.dll)

Проблема. Не удалось запустить сеанс отладки: FAILURE HR=0x80004005:Failed to AttachKernel.

Эта проблема может быть вызвана следующими причинами:

Как описано выше, возможно, что предыдущий сеанс ExdiGdbSrv.dll по-прежнему активен. Найдите и завершите связанный узел DLL, как описано выше.

Диалоговое окно WinDbg, отображающее сбой с кодом 0x80004005.

Проблема. Не удалось запустить отладку ядра с помощью EXDI.

Эта проблема может быть вызвана следующими причинами:

Существует еще один экземпляр ExdiGdbSrv.dll (размещенный в dllhost.exe) на компьютере узла отладки.
Завершите дополнительный экземпляр службы COM, на котором размещена ExdiGdbSrv.dll.
- Сначала перечислить процессы с помощью служебной программы, например TList на хост-компьютере. DLLHost будет отображаться как ExdiGdbServer, если на нём размещена ExdiGdbSrv.dll.
  
  tlist 261928 dllhost.exe ExdiGdbServer
- Используйте kill -f XXXXX в командной строке отладчика, чтобы завершить процесс с помощью номера процесса.

Проблема: ошибка: не удается настроить сеанс GdbServer.

Эта проблема может быть вызвана следующими причинами:

Произошла ошибка при поиске сведений о сеансе, таких как путь к XML-файлам конфигурации.

Проблема. Ошибка: переменная среды EXDI_GDBSRV_XML_CONFIG_FILE не определена.

Эта проблема может быть вызвана следующими причинами:

ExdiGdbSrv.dll переменные среды не заданы или в противном случае недоступны в среде.

Проблема. Ошибка: переменная среды EXDI_GDBSRV_XML_CONFIG_FILE не определена. Пример Exdi-GdbServer не будет продолжаться на этом этапе. Задайте полный путь к XML-файлу конфигурации Exdi.

Эта проблема может быть вызвана следующими причинами:

Переменная среды EXDI_GDBSRV_XML_CONFIG_FILE не задана. В некоторых ситуациях ExdiGDbSrv.dll продолжит работать, если нажать кнопку "ОК", но windbg.exe не сможет выполнить запросы к системным регистрам (например, через функции rdmsr/wrmsr).