Сконфигурировать и использовать отладчик в среде разработки ESP-IDF можно несколькими способами [1]:

• IDE Eclipse.
• Командная строка.
• Idf.py Debug Targets.

Замечание: рекомендуется сначала проверить, работает ли отладчик с использованием Idf.py Debug Targets или в командной строке (см. далее), и затем перейти к использованию Eclipse.

Eclipse это интегрированная среда разработки (IDE), которая предоставляет продвинутый набор инструментов для разработки и отладки программных приложений. Для приложений ESP-IDF есть плагин IDF Eclipse, предоставляющий 2 способа отладки:

1. ESP-IDF GDB OpenOCD Debugging.
2. GDB Hardware Debugging.

По умолчанию Eclipse поддерживает OpenOCD Debugging через плагин GDB Hardware Debugging, который требует запуска сервера OpenOCD из командной строки и конфигурирования клиента GDB в среде Eclipse, чтобы начать отладку. Этот метод отладки может быть затратным по времени и подверженным ошибкам.

Чтобы упростить процесс отладки, плагин IDF Eclipse имеет настраиваемый функционал ESP-IDF GDB OpenOCD Debugging. Этот функционал поддерживает конфигурирование сервера OpenOCD и клиента GDB в среде Eclipse. Все требуемые параметры конфигурации будут предварительно заполнены плагином, и вы сможете запускать отладку простым кликом на кнопке.

Таким образом, рекомендуется к использованию ESP-IDF GDB OpenOCD Debugging через плагин IDF Eclipse.

[GDB Hardware Debugging]

Замечание: этот метод рекомендуется только если вы по какой-то причине не можете отлаживаться в режиме ESP-IDF GDB OpenOCD Debugging.

Для установки плагина GDB Hardware Debugging откройте Eclipse и выберите Help > Install New Software.

После завершения установки выполните следующие шаги, чтобы сконфигурировать сессию отладки. Обратите внимание, что некоторые параметры конфигурации традиционные (generic), в то время как другие специфичны для проекта. Это будет показано далее на примере конфигурирования отладки проекта "blink" (находится в папке examples/get-started/blink каталога установки ESP-IDF). Если это еще не сделано, то добавьте этот проект в рабочее пространство (Eclipse workspace) после установки плагина Eclipse.

1. В Eclipse выберите пункт меню Run -> Debug Configuration. Откроется новое окно. В левой панели окна выполните двойной клик на GDB Hardware Debugging (или выберите GDB Hardware Debugging и нажмите кнопку New) для создания новой конфигурации.

2. В верхней строке формы, которая отобразится справа, введите имя этой конфигурации (Name:), например "Blink checking".

3. Ниже на закладке Main, под меткой Project:, нажмите на кнопку Browse и выберите проект blink.

4. В следующей строке, под меткой C/C++ Application:, нажмите кнопку Browse и выберите файл blink.elf. Если файла blink.elf здесь нет, то скорее всего еще не была выполнена сборка проекта. За инструкциями обратитесь к документации по Eclipse Plugin [2].

5. И наконец, под Build (if required) перед запуском кликните на радиокнопке Disable auto build.

Ниже показано окно мастера настройки конфигурации отладки после выполнения шагов 1 .. 5:

Рис. 1. Конфигурация GDB Hardware Debugging, закладка Main.

6. Кликните на закладку Debugger. В поле GDB Command, введите xtensa-esp32-elf-gdb для использования отладчика.

7. Измените конфигурацию по умолчанию Remote host вводом 3333 в поле ввода Port number.

Рис. 2. Конфигурация GDB Hardware Debugging, закладка Debugger.

8. Последняя закладка, которая требует изменения конфигурации по умолчанию, это Startup. Под меткой Initialization Commands снимите галочки Reset and Delay (seconds) и Halt. Затем в поле ввода ниже введите следующие строки:

mon reset halt
maintenance flush register-cache
set remote hardware-watchpoint-limit 2

Замечание: для автоматического обновления образа в flash перед запуском новой сессии отладки, добавьте следующие строки команд в поле Initialization Commands:

mon reset halt
mon program_esp ${workspace_loc:blink/build/blink.bin} 0x10000 verify

Для описания команды program_esp см. Upload Application for Debugging [3].

9. Снимите галочку с опции Load image под меткой Load Image and Symbols.

10. Ниже на той же закладке установите начальную точку останова (breakpoint), чтобы выполнить halt CPU после того, как он будет сброшен отладчиком. Плагин установит эту breakpoint в начало функции, которая введена в поле Set break point at:. Выберите эту опцию и введите app_main в предоставленное поле.

11. Выберите опцию Resume. Это возобновит работу программы после mon reset halt, выполненной в точке 8. Программа остановится на breakpoint, вставленной в app_main.

Результаты пунктов конфигурации 8 .. 11 показаны на следующей картинке:

Рис. 3. Конфигурация GDB Hardware Debugging, закладка Startup.

Если последовательность запуска выглядит запутанной, а соответствующие команды инициализации неясны, то обратитесь к подсказкам [4].

12. Если вы выполнили описанные выше шаги Configuring ESP32 Target, то target работоспособна и готова к общению с отладчиком. Перейдите непосредственно к отладке, кликнув на кнопке Debug. Иначе кликните на Apply для сохранения настроек, вернитесь к Configuring ESP32 Target и снова вернитесь сюда для запуска отладки.

Как только все шаги 1 .. 12 были выполнены успешно, откроется новая Eclipse-перспектива "Debug", как показано на следующей картинке.

Рис. 4. Перспектива Debug в среде Eclipse.

[Командная строка]

1. Начните с выполнения шагов, описанных в документации конфигурирования ESP32 Target [5]. Это необходимое условие для запуска сессии отладки.

2. Откройте новую сессию терминала и перейдите в директорию отлаживаемого проекта, например:

$ cd ~/esp/blink

3. Когда запускается отладчик, вам необходимо предоставить несколько параметров конфигурации и команд. Система сборки генерирует несколько файлов .gdbinit для облегчения эффективной отладки. Пути до этих файлов можно найти в build/project_description.json, под секцией gdbinit_files. Пути до этих файлов определяются следующим образом:

"gdbinit_files": {
    "01_symbols": "application_path/build/gdbinit/symbols",
    "02_prefix_map": "application_path/build/gdbinit/prefix_map",
    "03_py_extensions": "application_path/build/gdbinit/py_extensions",
    "04_connect": "application_path/build/gdbinit/connect"
}

Префикс XX_ в ключах JSON добавлен для обеспечения возможности их сортировки. Сортированные поля показывают рекомендуемый порядок, в котором предоставляются данные для GDB.

Описания генерируемых файлов .gdbinit:

symbols - содержит символы исходного кода для отладки.
prefix_map - конфигурирует карту префиксов для модификации путей исходного кода в GDB. Для дополнительной информации см. [6].
py_extensions - инициализирует Python-расширения в GDB. Это требует Python, собранного с libpython и версией, поддерживаемой GDB. Для проверки совместимости запустите команду xtensa-esp32-elf-gdb --batch-silent --ex "python import os", которая должна завершиться без ошибок.
connect - содержит команды, необходимые для установки соединения с target-устройством.

Чтобы улучшить отладку, вы также можете создавать пользовательские файлы .gdbinit, используемые либо вместе, либо вместо сгенерированных конфигураций.

4. Теперь вы готовы к запуску GDB. Используйте следующий пример команды для загрузки символов и подключения к target (добавлена опция -q для минимизирования вывода запуска):

$ xtensa-esp32-elf-gdb -q -x build/gdbinit/symbols -x build/gdbinit/prefix_map \
 -x build/gdbinit/connect build/blink.elf

5. Если предыдущие шаги были выполнены правильно, то вы увидите примерно вот такой лог с приглашением отладчика (gdb):

$ xtensa-esp32-elf-gdb -q -x build/gdbinit/symbols -x build/gdbinit/prefix_map \
 -x build/gdbinit/connect build/blink.elf

~/esp-idf/examples/get-started/blink$ xtensa-esp32-elf-gdb -q -x build/gdbinit/symbols \
 -x build/gdbinit/connect build/blink.elf
Reading symbols from build/blink.elf...
add symbol table from file "/home/user-name/esp-idf/examples/get-started/blink
 /build/bootloader/bootloader.elf"
[Switching to Thread 1070141764]
app_main () at /home/user-name/esp-idf/examples/get-started/blink/main/blink_example_main.c:95
 95          configure_led();
add symbol table from file "/home/alex/.espressif/tools/esp-rom-elfs/20241011/esp32_rev0_rom.elf"
JTAG tap: esp32.tap0 tap/device found: 0x00005c25 (mfg: 0x612 (Espressif Systems), part:
  0x0005, ver: 0x0)
[esp32] Reset cause (3) - (Software core reset)
Hardware assisted breakpoint 1 at 0x42009436: file /home/user-name/esp-idf/examples
 /get-started/blink/main/blink_example_main.c, line 92.
[Switching to Thread 1070139884]

Thread 2 "main" hit Temporary breakpoint 1, app_main () at /home/user-name/esp-idf/examples/
 get-started/blink/main/blink_example_main.c:92
92      {
(gdb)

Обратите внимание, что строки от третьей до последней показывают, что отладчик остановил выполнение кода процессором на breakpoint, установленной в файле build/gdbinit/connect на функции app_main(). Поскольку процессор остановлен, светодиод LED не должен мигать. Если это соответствует тому, что вы наблюдаете, вы готовы начать отладку.

Если у вас нет опыта в использовании отладчика GDB, см. пример командной строки сессии отладки в секции примеров отладки [7].

[Idf.py Debug Targets]

Также можно удобно выполнять описанные средства отладки из idf.py. Поддерживаются следующие команды:

1. idf.py openocd

Запустит OpenOCD в консоли с конфигурацией, определенной в окружении или через командную строку. Используется директория скрипта по умолчанию, определенная как переменная окружения OPENOCD_SCRIPTS, которая автоматически добавляется из скрипта Export для переменных окружения idf.py (через export.sh или export.bat). Можно изменить место расположения скрипта аргументом командной строки --openocd-scripts.

Для конфигурирования JTAG текущей платы используйте переменную окружения OPENOCD_COMMANDS или аргумент командной строки --openocd-commands. Если ничего из этого не определено, то OpenOCD запускается с определением платы в опции -f board/esp32-wrover-kit-3.3v.cfg.

2. idf.py gdb

Запустит GDB таким же способом, как было описано выше в разделе "Командная строка", с использованием сгенерированных GDB-скриптов, ссылающихся на текущий ELF-файл проекта. Для дополнительной информации см. раздел "Командная строка" выше.

3. idf.py gdbtui

То же самое, что и 2, но запустит gdb с аргументом tui, позволяя использовать простой вид исходного кода.

4. idf.py gdbgui

Запустит gdbgui frontend отладчика в окне браузера. Чтобы разрешить эту опцию, запустите скрипт инсталляции с аргументом "--enable-gdbgui", например install.sh --enable-gdbgui.

Вы можете комбинировать эти отладочные действия в одной командной строке, позволяя удобно настроить блокирующие и неблокирующие действия за один шаг. Скрипт idf.py реализует простую логику для перемещения фоновых действий (таких как openocd) в начало списка действий, и интерактивные действия (такие как gdb, monitor) в конец списка действий.

Вот пример очень полезной комбинации:

$ idf.py openocd gdbgui monitor

Эта команда запустит OpenOCD в фоновом процессе, запустит gdbgui в окне браузера с активным frontend отладчика, и откроет serial monitor в активной консоли.

[Ссылки]

1. Using Debugger site:espressif.com.
2. espressif / idf-eclipse-plugin site:github.com.
3. JTAG Debugging / Upload Application for Debugging site:espressif.com.
4. What Is the Meaning of Debugger's Startup Commands? site:espressif.com.
5. JTAG Debugging / Configuring ESP32 Target site:espressif.com.
6. Reproducible Builds and Debugging site:espressif.com.
7. Debugging Examples site:espressif.com.