Добро пожаловать в OpenOCD

OpenOCD предоставляет поддержку программирования и отладки на кристалле с многоуровневой архитектурой интерфейса JTAG и поддержкой TAP, включая:

• воспроизведение (X)SVF для удобства автоматизированного тестирования ограничивающих контуров и программирования FPGA/CPLD;
• поддержку целей отладки (например, ARM, MIPS): пошаговое выполнение, точки останова/наблюдения, профилирование gprof и т.д.;
• драйверы чипов flash-памяти (например, CFI, NAND, внутренняя flash);
• встроенный интерпретатор Tcl для удобного написания скриптов.

Для взаимодействия с OpenOCD доступны несколько сетевых интерфейсов: Telnet, Tcl и GDB. Сервер GDB позволяет OpenOCD функционировать как «удаленная цель» для отладки встроенных систем на уровне исходного кода с помощью программы GNU GDB (и других программ, поддерживающих протокол GDB, например IDA Pro).

Этот файл README содержит обзор следующих тем:

• инструкции по быстрому старту,
• как найти и собрать дополнительную документацию OpenOCD,
• список поддерживаемого оборудования,
• процесс установки и сборки,
• советы по упаковке.

Краткое руководство для нетерпеливых

Если у вас есть популярная плата, просто запустите OpenOCD с её конфигурацией, например:

openocd -f board/stm32f4discovery.cfg

Если вы подключаете конкретный адаптер с определенной целью, необходимо подключить конфигурации как интерфейса JTAG, так и цели, например:

openocd -f interface/ftdi/jtagkey2.cfg -c "transport select jtag" \
        -f target/ti/calypso.cfg

openocd -f interface/stlink.cfg -c "transport select swd" \
        -f target/stm32l0.cfg

После запуска OpenOCD подключите GDB с помощью:

(gdb) target extended-remote localhost:3333

Установка OpenOCD

Простейший способ установить OpenOCD — через менеджер пакетов вашей операционной системы.

• Debian / Ubuntu

sh sudo apt install openocd

• Fedora

sh sudo dnf install openocd

• macOS (через Homebrew)

sh brew install open-ocd

• Windows (через MSYS2)

sh pacman -S mingw-w64-x86_64-openocd

Эти пакеты часто более стабильны, чем передовая основная ветка Git, где ведется активная разработка. «Упаковщики» создают бинарные релизы OpenOCD после публикации разработчиками новых исходных релизов. Старые версии OpenOCD не подходят для диагностики проблем в текущем релизе. Пользователям следует поддерживать связь с сопровождающими своих дистрибутивов или поставщиками интерфейсов, чтобы гарантировать регулярное предоставление соответствующих обновлений.

Если вы используете один из этих бинарных пакетов, для получения поддержки или более новых бинарных версий вы должны обращаться к Упаковщику. Разработчики OpenOCD не предоставляют прямой поддержку для упакованных бинарных файлов.

Заметка для упаковщиков OpenOCD

Вы являетесь УПАКОВЩИКОМ OpenOCD, если вы:

• продаете «dongles» и включаете в них предварительно собранные бинарные файлы;
• поставляете инструменты или IDE (средства разработки, интегрирующие OpenOCD);
• собираете пакеты (например, файлы RPM или DEB для дистрибутива GNU/Linux).

Как УПАКОВЩИК, вы, как правило, первыми получаете отчеты о большинстве проблем. Когда вы решаете эти проблемы для своих пользователей, ваше решение может помочь предотвратить сотни (если не тысячи) других вопросов от других пользователей.

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

Тем не менее, разработчики OpenOCD также хотели бы, чтобы вы придерживались нескольких рекомендаций:

• Отправляйте патчи, включая файлы конфигурации, в основную ветку разработки, участвуйте в обсуждениях;
• Включайте все опции, поддерживаемые OpenOCD, даже те, которые не связаны с вашим конкретным оборудованием;
• Используйте драйвер интерфейсного адаптера «ftdi» для устройств на базе FTDI.

Документация OpenOCD

Помимо документации, включенной в дерево исходного кода, последние руководства можно посмотреть в Интернете по следующим URL-адресам:

• Руководство пользователя OpenOCD: http://openocd.org/doc/html/index.html

• Руководство разработчика OpenOCD: http://openocd.org/doc/doxygen/html/index.html

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

Для получения дополнительной информации обратитесь к этим документам или свяжитесь с разработчиками, подписавшись на список рассылки разработчиков OpenOCD: openocd-devel@lists.sourceforge.net

Сборка документации OpenOCD

По умолчанию процесс сборки OpenOCD готовит документацию в формате «Info» и устанавливает ее стандартным способом, чтобы info openocd мог получить к ней доступ.

Дополнительно Руководство пользователя OpenOCD можно создать в следующих различных форматах:

Если задана переменная PDFVIEWER, это создает и показывает PDF-версию Руководства пользователя.

make pdf && ${PDFVIEWER} doc/openocd.pdf

Если задана переменная HTMLVIEWER, это создает и показывает HTML-версию Руководства пользователя.

make html && ${HTMLVIEWER} doc/openocd.html/index.html

Руководство разработчика OpenOCD содержит информацию о внутренней архитектуре и другие детали кода:

Примечание: убедитесь, что установлен doxygen, наберите doxygen --version

make doxygen && ${HTMLVIEWER} doxygen/index.html

Поддерживаемое оборудование

Адаптеры JTAG

AM335x, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432, BCM2835, Bus Blaster, Buspirate, Cadence DPI, Cadence vdebug, Chameleon, CMSIS-DAP, Cortino, Cypress KitProg, DENX, Digilent JTAG-SMT2, DLC 5, DLP-USB1232H, встроенные проекты, Espressif USB JTAG Programmer, eStick, FlashLINK, FlossJTAG, Flyswatter, Flyswatter2, FTDI FT232R, Gateworks, Hoegl, ICDI, ICEBear, J-Link, JTAG VPI, JTAGkey, JTAGkey2, JTAG-lock-pick, KT-Link, Linux GPIOD, Lisa/L, LPC1768-Stick, Mellanox rshim, MiniModule, NGX, Nuvoton Nu-Link, Nu-Link2, NXHX, NXP IMX GPIO, OOCDLink, Opendous, OpenJTAG, Openmoko, OpenRD, OSBDM, Presto, Redbee, Remote Bitbang, RLink, SheevaPlug devkit, Stellaris evkits, ST-LINK (с поддержкой трассировки SWO), STM32-PerformanceStick, STR9-comStick, sysfsgpio, Tigard, TI XDS110, TUMPA, Turtelizer, ULINK, USB-A9260, USB-Blaster, USB-JTAG, USBprog, VPACLink, VSLLink, Wiggler, XDS100v2, Xilinx XVC/PCIe, Xverve.

Цели отладки

ARM: AArch64, ARM11, ARM7, ARM9, Cortex-A/R (v7-A/R), Cortex-M (ARMv{6/7/8}-M), FA526, Feroceon/Dragonite, XScale. ARCv2, AVR32, DSP563xx, DSP5680xx, EnSilica eSi-RISC, EJTAG (MIPS32, MIPS64), ESP32, ESP32-S2, ESP32-S3, Intel Quark, LS102x-SAP, RISC-V, ST STM8, Xtensa.

Драйверы Flash-памяти

ADUC702x, AT91SAM, AT91SAM9 (NAND), ATH79, ATmega128RFA1, Atmel SAM, AVR, CFI, DSP5680xx, EFM32, EM357, eSi-RISC, eSi-TSMC, EZR32HG, FM3, FM4, Freedom E SPI, GD32, i.MX31, Kinetis, LPC8xx/LPC1xxx/LPC2xxx/LPC541xx, LPC2900, LPC3180, LPC32xx, LPCSPIFI, Marvell QSPI, MAX32, Milandr, MXC, NIIET, nRF51, nRF52 , NuMicro, NUC910, Nuvoton NPCX, onsemi RSL10, Orion/Kirkwood, PIC32mx, PSoC4/5LP/6, Raspberry RP2040, Renesas RPC HF и SH QSPI, S3C24xx, S3C6400, SiM3x, SiFive Freedom E, Stellaris, ST BlueNRG, STM32, STM32 QUAD/OCTO-SPI для Flash/FRAM/EEPROM, STMSMI, STR7x, STR9x, SWM050, TI CC13xx, TI CC26xx, TI CC32xx, TI MSP432, Winner Micro w600, Xilinx XCF, XMC1xxx, XMC4xxx.

Сборка OpenOCD

Файл INSTALL содержит общие инструкции по запуску configure и компиляции исходного кода OpenOCD. Этот файл предоставляется по умолчанию для всех пакетов GNU autotools. Если вы не знакомы с GNU autotools, вам следует сначала прочитать эти инструкции.

Примечание: если файл INSTALL отсутствует, это означает, что вы используете исходный код из ветки разработки, а не из релиза OpenOCD. В этом случае следуйте инструкциям «Компиляция OpenOCD» ниже, и файл будет создан первой командой ./bootstrap.

Остальная часть этого документа пытается дать некоторую инструкцию тем, кто ищет быструю установку.

Зависимости OpenOCD

В настоящее время для сборки OpenOCD требуется GCC или Clang. Разработчики начали применять строгие предупреждения для кода (-Wall, -Werror, -Wextra и другие) и используют особенности C99: встроенные функции, именованные инициализаторы, смешивание объявлений с кодом и другие приемы. Хотя возможно использование и других компиляторов, они должны быть достаточно современными и могут потребовать расширения поддержки для условного удаления расширений специфичных для GCC.

Вам также потребуется:

• make
• libtool
• pkg-config >= 0.23 или pkgconf
• libjim >= 0.79

Дополнительно, для сборки из Git:

• autoconf >= 2.69
• automake >= 1.14
• texinfo >= 5.0

Необязательные драйверы адаптеров на основе USB требуют libusb-1.0.

Необязательные драйверы интерфейсных адаптеров USB-Blaster, ASIX Presto и OpenJTAG требуют библиотеку libftdi.

Необязательный драйвер адаптера CMSIS-DAP требует библиотеку HIDAPI.

Необязательный драйвер адаптера linuxgpiod требует библиотеку libgpiod.

Необязательный драйвер адаптера J-Link требует библиотеку libjaylink.

Необязательный дизассемблер ARM требует библиотеку capstone.

Необязательный скрипт разработки checkpatch требует:

• perl
• python
• python-ply
• pymarkdownlnt

Компиляция OpenOCD

Для сборки OpenOCD используйте следующую последовательность команд:

./bootstrap
./configure [options]
make
sudo make install

Команда bootstrap необходима только при сборке из хранилища Git. Шаг configure генерирует файлы Makefile, необходимые для сборки OpenOCD, обычно с предоставлением одной или нескольких опций. Первый шаг 'make' соберет OpenOCD и поместит итоговый исполняемый файл в './src/'. Последний (необязательный) шаг, make install, поместит все файлы в требуемое место.

Чтобы увидеть список всех поддерживаемых опций, запустите ./configure --help

Параметры кросс-компиляции

Кросс-компиляция поддерживается стандартным способом для инструментов autotools: вам нужно лишь указать целевую тройку кросс-компиляции в опции --host, например, для кросс-сборки под 32-битную Windows с помощью MinGW на Debian:

./configure --host=i686-w64-mingw32 [options]

Для корректной работы pkg-config при кросс-компиляции вам может потребоваться дополнительный скрипт-обёртка, как описано в https://autotools.io/pkgconfig/cross-compiling.html.

Это необходимо, чтобы указать pkg-config, где искать целевые библиотеки, от которых зависит OpenOCD. Альтернативно вы можете напрямую указать переменные окружения *_CFLAGS и *_LIBS; подробности смотрите в выводе ./configure --help.

Более или менее готовый скрипт, выполняющий все эти действия, вы найдёте в contrib/cross-build.sh.

Порты с ключами доступа

Если вы хотите получить доступ к параллельному порту с использованием интерфейса PPDEV, вам нужно указать как --enable-parport, так и --enable-parport-ppdev, поскольку последняя опция является опцией драйвера parport.

То же самое верно для опции --enable-parport-giveio: вам нужно использовать как --enable-parport, так и --enable-parport-giveio, если вы хотите использовать метод доступа к параллельному порту через giveio вместо ioperm.

Получение OpenOCD из Git

Вы можете загрузить текущую версию из Git с помощью клиентского приложения вашего выбора из основного репозитория: git://git.code.sf.net/p/openocd/code

Вы можете предпочесть использовать зеркало:

• http://repo.or.cz/r/openocd.git
• git://repo.or.cz/openocd.git

Используя командную строку Git, вы можете выполнить следующую команду для создания локальной копии текущего репозитория (убедитесь, что в текущем каталоге нет директории с именем "openocd"):

git clone git://git.code.sf.net/p/openocd/code openocd

После этого вы можете обновлять её по мере необходимости с помощью git pull.

Также имеется веб-интерфейс gitweb, который вы можете использовать как для просмотра репозитория, так и для скачивания произвольных снимков по HTTP: http://repo.or.cz/w/openocd.git.

Снимки — это сжатые архивы с исходным кодом, каждый размером около 1,3 МБ на момент написания документа.

Делегирование прав

Запуск OpenOCD с правами root/администратора по соображениям безопасности настоятельно не рекомендуется.

Для USB-устройств в GNU/Linux следует использовать файл contrib/60-openocd.rules. Он, вероятно, должен находиться где-то в /etc/udev/rules.d/, но обратитесь к документации вашей операционной системы для уточнения. Не забудьте добавить себя в группу "plugdev".

Для адаптеров параллельного порта в GNU/Linux и FreeBSD пожалуйста измените права доступа к узлу устройства "ppdev" (parport или ppi).

Для адаптеров с параллельным портом в Windows вам нужно запустить install_giveio.bat (также возможно использование "ioperm" в Cygwin), чтобы дать обычным пользователям права на прямой доступ к регистрам "LPT".