Здравствуйте, писал для себя краткую инструкцию по работе с WCH-LinkE и подумал, а ведь она может быть полезна не только лишь мне.

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

Статья оформлена как инструкция с некоторыми короткими пояснениями.

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

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 в первый и раз и для настройки рабочего окружения мне потребовалось некоторое время. На официальном сайте openocd много документации, но мне она показалась немного разрозненной.

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

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

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

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

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

Также интересная особенность openocd это возможность писать скрипты на языке Tcl (тикль). JLink тоже поддерживает командный режим, но на первый взгляд тикль скрипты позволяют более глубоко залезать в железку и писать больше логики. Эта возможность очень полезна для проведения 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 тестов.

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

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

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

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

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

Примечание: полный список команд находится на сайте openocd.

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

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

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

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

Продолжаем открывать консоли и запускать телнеты. Запуск на порту 4444, позволит нам увидеть лог программы, полученный по RTT.

telnet localhost 4444

Результат выполнения команды ниже на скриншоте.

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

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

lappend post_init_commands {run_rtt}

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

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

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

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

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

Предполагается, что система сборки настроена и нужные плагины установлены. Начнем пожалуй с самого интересного с настройки отладки. Для это создадим или дополним в директории с проектом в папке .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 (rttConfig) канала 0. Лог с этого канала будет выводиться в терминале 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.

Я же продолжу использовать этот отладчик и в дальнейшем планирую больше погрузиться в написание для него скриптов.