openocd.md

Памятка по работе с OpenOCD

Open On-Chip Debugger (OpenOCD) инструментарий отладки, внутрисхемного программирования и внутрисхемного тестирования для встраиваемых систем. Обычно он используется в качестве моста между аппаратным отладчиком и gdb, обеспечивая последнему абстракцию от железа.

Так что c интеграцией всё просто) Рисуем сову Учим нашу “любимую” ide запускать gdb с правильными параметрами, который в свою прицепится к openocd, настроенному для отладки нашего железа.

Основы работы с OpenOCD

В общем виде команда для запуска OpenOCD выглядит следующим образом:

openocd -f config1.cfg -c 'command' -f config2.cfg -f config3.cfg

Для работы openocd должен иметь представление о целевом процессоре (target) и аппаратном отладчике (interface). Ниже пример подключения к платке stm32f407-discovery, имеющей на борту отладчик st-linkv2:

openocd -f interface/stlink.cfg -c 'transport select hla_swd' -c 'adapter speed 4000' -f target/stm32f4x.cfg

Работает! OpenOCD успешно запустил сервер отладки.

Данную информацию мы передаём openocd в виде соответствующих конфигов: interface/stlink.cfg и target/stm32f4x.cfg. Перед каждым конфигом обязательно идет ключ -f. Дополнительно можно передать команды посредством ключа -c, список которых довольно внушителен. Дополнительную информацию можно молучить из man.

Отладчик ведет поиск скриптов следующих директориях в порядке убывания приоритета:

1. Текущая директория
2. Любая директория, переданная через опцию -s
3. Любая директория, установленная командой add_script_search_dir
4. Директория из переменной окружения OPENOCD_SCRIPTS (если установлена)
5. %APPDATA%/OpenOCD (только на Windows)
6. $HOME/Library/Preferences/org.openocd (только на Darwin)
7. $HOME/.openocd
8. Библиотека сторонних скриптов $pkgdatadir/site and
9. Библиотека сторонних скриптов $pkgdatadir/scripts

“Работая” в windows, вы скорее всего скачаете уже собранный openocd, поэтому $pkgdatadir будет эквивалентна папке с установленной программой. В линуксах, как правило он ставится через пакетный менеджер дистрибутива, $pkgdatadir обычно папка /usr/share/openocd/scripts/.

Примечание: Иногда openocd из репозитория отказывается работать с особенно свежим чипом, в этом случае следует собрать апстрим из гита. Отладчик активно развивается, но разработчики не торопятся инкрементировать версию пакета, так что openocd 0.11 с момент релиза прилично так изменился. Тем не менее мейнтейнеры пакетов обычно не торопятся его пересобирать. Если и это не помогло, то придется качать/собирать форк от производителей чипа. Сам сталкивался с подобным при отладке процов от техасских инструментов и свежего на тот момент stm32mp157. На данный момент полная поддержка этих чипов есть в апстриме.

Давайте посмотрим, какие готовые конфиги есть в нашем распоряжении, а там много всего полезного. Наиболее интересны нам папки interface, target и board, содержимое которых должно быть понятно из названий этих папок:

• Interface - содержит конфиги для аппаратных отладчиков, вроде st-link, j-link, cmsis-dap и т.д и т.п
• Board - в основном здесь хранятся готовые конфиги для отладочных плат. Также это хорошие примеры для написания своих board.cfg
• Target - следует понимать как chip. Файлы в этой папке содержат описание JTAG TAP для целевого процессора, процедур старта, инициализацию PLL т.д. Вообщем всё то, что специфично для конкретного процессора.

Попробуем подключится к нашей плате через готовый конфиг:

openocd -f board/stm32f4discovery.cfg

Результат очень похож на предыдущий, отличается только clock speed

Тут мы плавно переходим к командам, передаваемым через ключ -c. Так как хочется, чтобы написанные конфиги были максимально универсальнымы, нам дана возможность передавать команды для тонкой настройки отладочного сервера. Вернёмся к первому примеру:

openocd -f interface/stlink.cfg -c 'transport select hla_swd' -c 'adapter speed 4000' -f target/stm32f4x.cfg

Здесь мы выбрали интерфейс для связи с микроконтроллером (swd) и частоту (4МГц).

Примечание: Команды имеют полезное свойство перекрытия. Например, если передать последовательность команд -c ‘adapter speed 4000’ -c ‘adapter speed 3000’, то adapter speed будет установлен как 3000. Это знание нам ещё пригодится.

Давайте заглянем в конфиг stm32f4discovery.cfg:

# This is an STM32F4 discovery board with a single STM32F407VGT6 chip.
# http://www.st.com/internet/evalboard/product/252419.jsp
source [find interface/stlink.cfg]
transport select hla_swd

# increase working area to 64KB
set WORKAREASIZE 0x10000

source [find target/stm32f4x.cfg]
reset_config srst_only

Почти то же самое, что было у нас, за исключением пары штрихов. Минимально конфиг платы включает в себя файлы описания интерфейса (идет первым) и процессора. Иногда одного target-файла недостаточно, например, если у чипа нет набортной flash-памяти.

Используя конфиги из папок interface и target и руководствуясь примерами из board, вы сможете легко написать свой собственный board.cfg. Дополнив его командами или внешними скриптами можно серьёзно упростить себе жизнь.

Например, можно написать скрипт, с помощью которого можно прошивать плату одной командой, что удобно для прошивки загрузчика или при ремонте плат. Можно наделить скрипт дополнительным функционалом, например, прошивать серийные номера по фиксированному адресу.

Узнать больше о конфигурационных файлах можно из официальной документации на openocd, раздел Config File Guidelines.

Теперь, когда у вас появилось понимания процесса запуска openocd, можно попробовать с ним поработать. Для примера прошьём мигалку в нашу отладку:

Мигает! Мне лень заморачиваться с видео, так что просто поверьте на слово)

Сервер отладки OpenOCD предоставляет два основных интерфейса для работы с gdb и telnet. Последний позволяет управлять процессом отладки в ручном режиме: прошивать камень, стирать flash, модифицировать данные в ОЗУ или flash, модифицировать контекст, сделать программный сброс, выполнить инструкцию по адресу и т.д. Полный список команд, поддерживаемых данным камнем и отладчиком, можно увидеть посредством команды help.

Меня просили не привязывать статью к конкретной плате или отладчику, поэтому в завершение раздела добавлю пару примеров для работы с другими платами:

GD32VF103

openocd -f interface/jlink.cfg -c 'adapter speed 1000' -f target/gd32vf103.cfg

STM32F103 (Blue Pill)

openocd -f interface/jlink.cfg -c 'transport select swd' -c 'adapter speed 1000' -f target/stm32f1x.cfg

Работа с OpenOCD через GDB

Как было сказано выше, сервер отладки OpenOCD имеет один или несколько портов для подключения gdb. Несколько gdb-портов открываются в том случае, если отлаживаемя железка имеет несколько TAP/DAP, номер каждого последующего порта инкрементируется на единицу. Важно не ошибиться портом.

GDB очень мощный инструмент, ни один из плагинов для ide не предоставляет всего его функционала. Некоторые ide, например vs code, предоставляют доступ к консоли gdb. Настоятельно рекомендую ознакомиться с документацией на этот замечательный инструмент.

Работа с OpenOCD через IDE

Популярные ide, как правило, имеют плагины для работы с openocd разной степени кривости. Впрочем, ничего страшного в этом нет, базовые знания, полученные из предыдущих разделов, помогут преодолеть трудности и разобраться в подводных камнях.

VS Code

Чаще всего меня просили помочь настроить vs code, так что начнём с неё. Этот мегаредактор/недоIDE является конструктором, из которого можно собрать что-нибудь прикольное. Степень “прикольности” зависит от вашего терпения и желания курить справку к очередному плагину.

В коробке с конструктором можно найти плагин Cortex-Debug который и поможет нам в отладке. Далее пошаговое пояснение:

1. Переходим в меню “Run and Debug (ctrl+shift+d)”, там жмякаем на ссылку “create a launch.json file”. Откроется выпадающее меню, в котором выбрать Cortex-Debug.

2. Скрипт launch.json откроется автоматически с конфигурацией для Cortex-Debug по-умолчанию, которую нужно подправить её под нашу плату. Наш скрипт может иметь несколько конфигураций для запуска, которые можно добавлять здоровенной кнопкой “Add Configuration”.

3. Правим конфигурацию. Как видно из скриншота, каких-то откровений в ней нет, всё это мы разбирали в первом разделе. Единственное, был добавлен путь до файла с описанием регистров .svd

4. Готово можно отлаживаться. Насколько это удобно, решать уже вам.

Qt Creator

Архитектура этой IDE с device и kit ведет к несколько запутанной настройке, но всё оборимо:

1. Нужно включить плагин BareMetal. Открываем меню Installed plugins (help->About plugins), находим через поиск и включаем нужный плагин.
2. Теперь нужно настроить отладочный сервер. Открываем меню настроек (Tool->Options...), выбираем раздел Device, в нём вкладку Bare Metal, в которой добавляем новый отладочный сервер нажатием кнопки “Add”. Настраивается сервер также, как и для vs code.
3. Теперь нужно создать device. Переключаемся на вкладку Devices, нажимаем кнопку “Add”, выбираем bare metal device, далее выбираем наш отладочный сервер.
4. Переходим на вкладку Kits, создаём новый kit и настраиваем как на скриншоте.
5. Всё почти готово. Теперь при открытии проекта необходимо выбрать наш кит и настроить директорию сборки, там всё интуитивно. Скорее всего понадобится ещё настроить параметры запуска, далем как на скриншоте
6. Запутанно, неправда ли) Но результат того стоил, наверное... Доступ к консоли отладчика также есть, но реализация практически неюзабельна.

CLion

Далее на очереди Clion. Популярная, очень даже адекватная ide с вменяемой поддержкой встраиваемых систем. Настройка среды сильно проще, чем у креатора. Лезем в Run->Edit Configurations... Удаляем созданные по-умолчанию конфигурации для cmake и создаём новые для openocd, всё предельно интуитивно. Есть нормальная консоль gdb.