Настройка связки VScode, OpenOCD, WCH-LinkE, Cortex-M

Что это такое и для чего нужно

Wch-link является программатором для ARM, RISC-V микроконтроллеров. По возможностям это аналог St-link, JLink и прочих. По сравнению с st-link он поддерживает контроллеры не только фирмы STM. А по сравнению с JLink стоит намного дешевле и не имеет проблем с лицензиями, которые могут встречаться у дешевых клонов JLink. Также плюсом идет поддержка набирающих популярность контроллеров от китайской компании WCH.

Есть несколько вариантов этого отладчика, я буду говорить о версии Wch-linkE rev 1.3.

Он поддерживает SWD/JTAG, но JTAG я не проверял. Сам отладчик поддерживает протокол CMSIS-DAP адаптера и соответственно, может использоваться вместо него. Также есть встроенный UART для отладки. В целом коробочка производит приятное впечатление.

Драйвера, мануал и прочее можно скачать с сайта производителя. Работа с МК данной фирмы предполагаются, через IDE MounRiver Studio(MRS). Это IDE на основе Eclipcse, аналог CubeIDE. Я предпочитаю использовать vscode и судя по информации из интернета этому ничего не мешает. Так как на данный момент у меня нет контроллера с ядром RISC-V я буду использовать этот отладчик вместо JLink для популярных ARM-Cortex-M. Интересно посмотреть на сколько этот отладчик лучше, хуже и способен ли заменить JLink.

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

Установка драйверов отладчика

Самое первое, что потребуется установить драйвер на отладчик. Для этого можно установить WCH-LinkUtility. При её установке также поставятся драйвера для отладчика. По функциональности эта программа аналогична старой программе от ST — ST-LINK utility.

Примечание: на линукс системе никакие драйвера ставить не нужно, отладчик и usb-uart появится в системе автоматчики при подключении.

Подробнее об openocd

Работать с программатором я планирую, через openocd. Этот проект поддерживает множество программаторов. На сколько я понял суть проекта заключается, что большая часть логики вынесена на хост, а сам адаптер только дрыгает ножками и передает в обе стороны данные. Возможно я не прав, глубоко я не погружался, но факт остается фактом, что используя openocd можно работать со множеством программаторов. Запишу, это свойство в плюс данного подхода, люблю универсальность.

Также интересная особенность openocd это возможность писать скрипты на языке Tcl (тикль). JLink тоже поддерживает командный режим, но на первый взгляд тикль скрипты openocd позволяют более глубоко залезать в железку и написать больше логики. Эта возможность очень полезна для проведения HW тестов. Но скрипты требуют дальнейшего изучения, может быть и не все так радужно. Я пока использовал возможность скриптинга по минимуму, только для работы с RTT.

Больше информации можно получить на официальном сайте OpenOCD.

Установка openocd

Как я понял подразумеватся самому собирать из исходников openocd. Но также есть неофициальная готовая бинарная сборка, я предпочел воспользоваться готовой сборкой.

Дальше можно добавить в переменную окружения PATH путь до бинарника openocd. Это нужно, чтобы система могла найти openocd при вызове из командной строки без указания полного пути до него. А также находила файлы из комплекта поставки, которые находятся в директориях interface и target.

Проверим, что openocd работает.

Подключение к целевому контроллеру (таргету)

Данные об адаптере, целевом MCU (микроконтроллере), о способе подключения openocd получает из файлов конфигов или из аргументов командой строки. Удобнее использовать файлы конфигов. На самом деле эти файлы могут быть и тикль скриптами, что мы увидим в дальнейшем.

Итак, для подключения нам понадобиться описание адаптера. Я взял готовый файл cmsis-dap.cfg из папки корень_openocd/openocd/interface и немного доработал его. Сохранил в ту же папку под именем wch-cmsis-dap.cfg. Содержимое этого файла по ссылке.

В соседней с директорией interface, есть папка target, там хранятся скрипты для подключения соответствующему таргету.

Я пока туда не лазил, поэтому, что-то более подробного не могу сказать. Единственное, что можно отметить, что в этих скриптах производятся чтение размеров блоков памяти устройства. Это дает надежду, что можно сделать скрипт, который будет через отладчик и целевой МК проверять периферийные устройства на плате. Это может быть неплохой альтернативой специальной прошивки для hw тестов.

Итог: для подключения передаем в openocd данные о типе адаптера и о типе тергета. Если все получилось, то увидим примерно следующее.

Примечание: для конкретики я работаю с платой на чипе gd32f425, но как видим для него подходит конфиг от stm32f4.

openocd -f "interface/wch-cmsis-dap.cfg" -f "target/stm32f4x.cfg"

Ручная работа c openocd

Для отладки скриптов мне, кажется, удобно воспользоваться ручным вариантов работы с отладчиком. Собственно, при подключении он нам и пишет на какие порты мы можем подключиться. Порт, который обеспечивает режим командной строки для отладчика это 4444. Полный список команд находится на сайте openocd.

Пример: подключится через telnet на порт 4444 и активировать RTT сервер. Для работы потребуется утилита telnet.

Примечание: для windows систем, скорее всего придется установить эту программу, поэтому оставлю ссылку на официальную документацию.

В окне терминала подключаемся к таргету.

openocd -f "interface/wch-cmsis-dap.cfg" -f "target/stm32f4x.cfg"

В новом окне терминала вводим:

telnet localhost 4444

Теперь в окне терминала телнета вводим. Тут мы пытаемся найти в ОЗУ по идентификатору «SEGGER RTT» найти блок управления rtt и указываем размер буферов. В строчке запуска сервера на 9090 порту указываем к какому каналу RTT будем подключаться.

rtt setup 0x20000000 2048 "SEGGER RTT"
rtt start
rtt server start 9090 0

Продолжаем откоывать консоли и запускать телнеты 🙂

telnet localhost 4444

И теперь тут мы уведем лог, которые мы получаем через RTT.

Пример ручного запуска RTT сервера.

Пример tcl скрипта

Запуск RTT сервера можно автоматизировать для этого я написал скрипт. Его можно запускать, как аргумент openocd при запуске. Это делается через ключ -f rtt.tcl. В этом файле я немного поэкспериментировал в скриптинге. Написал пару функций. Наверное, самое интересное в этом скрипте это cтрока:

lappend post_init_commands {run_rtt}

Строка добавляет мою функцию в post init процесс т.е. запускает скрипт после инициализации адаптера и таргета. Это важно, если этого не сделать возникнет ошибка, связанная с функцией init.

Интеграция с Visual Studio Code

Примерно поняв процесс работы с отладчиком можно приступить к его интеграции в vscode. Для сборки самого проекта я использую CMake и плагины для его интеграции в редактор. Для отладки потребуется плагин cortex-deubug.

Примечание: можно работать со стандартным плагином cppdbg, но конфигурация будет объёмнее.

Примечание: ссылка на мою старую статью о vscode и СMake. Она требует дополнений, думаю, что сейчас можно найти и более актуальные статьи на данную тему.

Предполагается, что система сборки настроена и нужные плагины установлены. Начнем пожалуй с самого интересного с настройки отладки. Для это создадим или дополним в директории с проектом в папке .vscode файл launch.json. Часть файла с настройкой отладчика:

    {
        "name": "Debug (OpenOCD)",
        "cwd": "${workspaceRoot}",
        "executable": "${command:cmake.launchTargetPath}",
        "request": "launch",
        "type": "cortex-debug",
        "servertype": "openocd",
        "interface": "swd",
        "device": "STM32F205RG",
        "runToEntryPoint": "main",
        "svdFile": "${workspaceRoot}/resources/STM32F20x.svd",
        "configFiles": [
            "interface/wch-cmsis-dap.cfg",
            "target/stm32f2x.cfg"
        ],
        "preLaunchCommands": [
            "set mem inaccessible-by-default off",
            "monitor reset"
        ],
        "postLaunchCommands": [
            "monitor reset init",
            "monitor sleep 100"
        ],
        "rttConfig": {
            "enabled": true,
            "address": "auto",
            "clearSearch": false,
            "polling_interval": 20,
            "rtt_start_retry": 20000,
            "decoders": [
                {
                    "label": "RTT channel 0",
                    "port": 0,
                    "timestamp": true,
                    "type": "console"
                }
            ]
        }
    }

Из особенностей можно отметить настройку RTT канала 0. Лог из канала будет выводиться в терминале vscode.

Пример работы отладчика в vscode.

Для прошивки я создал задачу и добавил её в файл .vscode/tasks.json. Приведу код только таски прошивки, важно, что она зависит от задачи сборки. Если это не нужно, то можно просто удалить строчку: «dependsOn»: «CMake: build active target».

    {
        "type": "shell",
        "dependsOn": "CMake: build active target",
        "label": "OpenOcd: flash",
        "options": {
            "cwd": "${workspaceRoot}"
        },
        "command": "openocd",
        "args": [
            "-f",
            "interface/wch-cmsis-dap.cfg",
            "-f",
            "target/stm32f4x.cfg",
            "-c", "program ${command:cmake.launchTargetPath} verify reset exit"
        ],
        "group": "test"
    }

Итог

На текущий момент я доволен работой отладчика в связке с openocd. Во всяком случае в моих проектах он вполне тянет на замену JLink. Возможно, в дальнейшем выявится недостатки, но пока все более, чем хорошо и стабильно работает.

Надеюсь это статья будет полезна, чтобы воспользоваться wch-link для работы с Cortex-M.