STM32CubeIDE: среда разработки для STM32

Что изменилось в версиях 2.x

Ветка 2.x заметно отличается от привычных по старым инструкциям версий 1.x, где внутри среды был графический конфигуратор выводов (перспектива Device Configuration Tool).

В заметках к версиям 1.x ST советовала для работы в версии 1.4 и новее заводить новое рабочее пространство (workspace) и импортировать в него с копированием проекты из более ранних версий; к версиям 2.x такого примечания нет.

Установка и требования

STM32CubeIDE распространяется бесплатно по лицензии ST SLA0048, скачивается со страницы продукта на st.com. Порядок установки описан в отдельном руководстве UM2563; несколько версий среды можно держать на компьютере одновременно.

При первом запуске среда спрашивает, где создать рабочее пространство (workspace) — папку, в которой лежат проекты; активным может быть только одно. Две вещи из руководств ST стоит учесть сразу:

• имена workspace и проектов и весь путь к ним должны состоять только из символов ASCII — значит, кириллицы не должно быть и в именах папок, через которые проходит путь, включая папку пользователя Windows, если workspace лежит в ней;
• в Windows папку workspace не стоит прятать глубоко: при слишком длинных путях к файлам сборка завершается ошибками.

Создание проекта

Пустой проект прямо в STM32CubeIDE

Команда File → STM32 Project Create/Import → Create New STM32 Project, затем «STM32CubeIDE project». В мастере выбирают микроконтроллер на вкладке MCU/MPU Selector (фильтр по серии и ядру) или плату на вкладке Board Selector, вводят имя проекта, язык (C или C++) и тип результата: исполняемый файл или статическая библиотека. Тем же меню создаётся проект на CMake (шаблоны Executable и Static Library). Микроконтроллер у готового проекта мастер сменить не позволяет. Поэтому статические библиотеки, которые собирают под разные STM32, ST советует создавать как обычный CDT-проект (File → New → C/C++ Project): в нём целевой микроконтроллер выбирается отдельно для каждой конфигурации сборки (Properties → C/C++ Build → Settings → Tool Settings → MCU Settings → Select…).

По руководству UM2553 такой проект уже содержит всё, чтобы собрать и записать программу, включая файл syscalls.c, но кода инициализации периферии в нём нет.

Проект из STM32CubeMX

Обычный путь для проекта с HAL выглядит так:

1. В STM32CubeMX выбрать микроконтроллер, плату или пример, настроить выводы, тактирование, периферию и middleware. Всё это сохраняется в файле .ioc — один такой файл на проект.
2. На вкладке Project Manager указать в поле Toolchain/IDE значение STM32CubeIDE и нажать GENERATE CODE.
3. В STM32CubeIDE выполнить File → STM32 Project Create/Import → Import STM32 Project, выбрать «STM32CubeMX project» (или STM32CubeMX2), ввести имя и папку проекта STM32CubeMX.

Функции инициализации периферии в сгенерированном коде начинаются с MX_: MX_GPIO_Init(), MX_I2S2_Init() и так далее — по одной на каждый включённый блок периферии. Чтобы изменить настройки, правят .ioc в STM32CubeMX и генерируют код заново — поэтому важно, где лежит ваш собственный код.

Секции USER CODE: что переживёт повторную генерацию

STM32CubeMX расставляет в сгенерированных файлах пары комментариев:

int main(void)
{
  /* USER CODE BEGIN 1 */
  uint32_t counter = 0;          /* saved on regeneration */
  /* USER CODE END 1 */

  HAL_Init();
  SystemClock_Config();
  MX_GPIO_Init();

  /* Infinite loop */
  /* USER CODE BEGIN WHILE */
  while (1)
  {
    /* USER CODE END WHILE */

    /* USER CODE BEGIN 3 */
    HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
    HAL_Delay(500);
    counter++;
  }
  /* USER CODE END 3 */
}

Правила из руководства UM1718:

• код внутри секций сохраняется при следующей генерации, код вне их перезаписывается;
• секции нельзя переносить и переименовывать — иначе их содержимое теряется;
• сохраняются только секции, которые расставил сам STM32CubeMX; придуманные пользователем пары BEGIN/END игнорируются;
• бесконечный цикл while (1) тоже находится внутри секции, поэтому тело цикла пишут между USER CODE BEGIN 3 и USER CODE END 3;
• опция «Keep user code when regenerating» касается только секций в сгенерированных файлах, а не ваших отдельных файлов; папки Middlewares и Utilities внутри проекта зарезервированы — при регенерации их содержимое удаляется или меняется.

Надёжнее всего крупный собственный код держать в своих .c и .h файлах, а в секции main.c оставлять только вызовы.

Сборка: Debug и Release

В каждом новом проекте две конфигурации сборки:

Активную конфигурацию выбирают стрелкой рядом с кнопкой Build на панели инструментов или через контекстное меню проекта Build Configurations → Set Active. Результат сборки (.elf и карта памяти .map) кладётся в папку с именем активной конфигурации; в конце сборки окно Console печатает размеры секций. Можно создать свои конфигурации на основе существующих, а Build Configurations → Build All соберёт все сразу. Форматы файлов прошивки разобраны в статье о файлах прошивки.

Для сборки на сервере без графического интерфейса в папке установки есть скрипт headless-build.bat. Пример для Windows из руководства:

headless-build.bat -data C:\Users\Name\STM32CubeIDE\workspace -cleanBuild NUCLEO-F401RE

Перед запуском workspace должен быть закрыт в STM32CubeIDE, иначе скрипт не сможет его открыть.

Скрипт компоновщика и startup-файл

Проект собирается командой вида arm-none-eabi-gcc … -T"STM32F401RETX_FLASH.ld" --specs=nosys.specs -Wl,--gc-sections; в примере из руководства для платы NUCLEO-F401RE скрипт компоновщика STM32F401RETX_FLASH.ld лежит в корне папки проекта. В нём:

• блок MEMORY с адресами и размерами флеш-памяти и ОЗУ;
• точка входа ENTRY(Reset_Handler);
• размещение секций .isr_vector, .text, .rodata, .data, .bss;
• символы _estack, _sidata, _sdata, _edata, _sbss, _ebss, по которым startup-код ставит указатель стека, копирует .data из флеш-памяти в ОЗУ и обнуляет .bss;
• _Min_Heap_Size и _Min_Stack_Size — минимальные размеры кучи и стека. Компоновщик лишь проверяет, что они помещаются в ОЗУ; реальный стек во время работы может оказаться больше.

Таблица векторов g_pfnVectors и функция Reset_Handler находятся в ассемблерном файле startup_stm32xxxx.s. Если его нет в сборке, GNU ld по умолчанию лишь предупреждает «cannot find entry symbol Reset_Handler» и всё равно создаёт неработающий .elf. Чтобы такие предупреждения останавливали сборку, в Properties → C/C++ Build → Settings → MCU GCC Linker → Miscellaneous добавляют флаг -Wl,--fatal-warnings. Как устроены MEMORY, SECTIONS, адреса загрузки и выполнения, — в статье о скриптах компоновщика; карта флеш-памяти STM32 и загрузчик — в статье о флеш-памяти и загрузчике STM32.

Отладка через ST-LINK

Первая отладочная конфигурация создаётся из контекстного меню проекта: Debug As → STM32 C/C++ Application. При первом запуске среда собирает проект и открывает окно настроек; после нажатия Debug она запускает GDB-сервер, записывает программу и останавливается на первой строке main(), а затем предлагает перейти в перспективу Debug.

На вкладке Debugger выбирают программатор и сервер:

Все три сервера поддерживают обычную отладку, Live Expressions, SWV и отладку с учётом FreeRTOS и ThreadX. Основные настройки для ST-LINK:

• Interface — SWD или JTAG. ST рекомендует SWD; для SWV он обязателен. Распиновка разъёмов — на странице JTAG и SWD.
• Frequency (kHz) — частота SWD или JTAG; Auto означает максимум для данного ST-LINK. При длинных проводах и помехах частоту снижают.
• ST-LINK S/N — серийный номер, если к компьютеру подключено несколько программаторов; кнопка Scan показывает все найденные.
• Reset behaviour — как подключаться к микроконтроллеру (таблица ниже).
• Debug in low power modes и Suspend watchdog counters while halted — не терять связь в режимах сна и не получать сброс от сторожевого таймера, пока ядро остановлено.
• Shared ST-LINK — нужен, если во время отладки к тому же ST-LINK обращается другая программа, например STM32CubeProgrammer.
• Log to file — подробный журнал GDB-сервера на случай непонятных ошибок.

Если в отладочной конфигурации есть запись флеш-памяти, выбранный режим не действует: ST-LINK GDB server вызывает STM32_Programmer_CLI с параметрами mode=UR reset=hwRst, то есть всегда подключается под сбросом. Поэтому вывод NRST микроконтроллера должен быть соединён с выводом NRST программатора — у ST-LINK/V2 это контакт 15 20-контактного разъёма.

ST советует отлаживать код, собранный с оптимизацией -O0: с -Og отладка возможна, с более высокими уровнями переменные «пропадают», а шаги прыгают по строкам. В перспективе Debug доступны точки останова (щелчок по полосе слева от номера строки), окна Variables, Expressions, Memory, Registers, SFRs с регистрами периферии из файла SVD, Live Expressions — значения переменных, обновляемые без остановки программы, и Fault Analyzer, который после аварийного исключения показывает его причину, например деление на ноль. Кнопка Terminate and Relaunch останавливает сессию, пересобирает проект и запускает отладку заново.

Прошивка без отладки

Чтобы только записать программу и запустить её, создают конфигурацию запуска: Run As → STM32 C/C++ Application. Программа записывается, и сессия сразу закрывается. Для записи готовых .hex и .bin, работы с option bytes и загрузчиком через UART или USB есть отдельная программа STM32CubeProgrammer.

printf через SWV и ITM

Функция printf() из newlib вызывает _write() из файла syscalls.c, а та — __io_putchar() для каждого символа. Чтобы вывод шёл в окно отладчика без UART, используют модуль ITM ядра и вывод SWO. В примере ST для STM32F4 _write() переписывают так:

#include "stm32f4xx.h"
#include "core_cm4.h"

int _write(int file, char *ptr, int len)
{
  for (int i = 0; i < len; i++)
    ITM_SendChar(*ptr++);      /* stimulus port 0 */
  return len;
}

В syscalls.c функция _write() объявлена со слабым атрибутом weak, поэтому её можно переопределить в любом своём файле, не трогая сгенерированный. Дальше:

1. Run → Debug Configurations, вкладка Debugger: интерфейс SWD, включить Serial Wire Viewer (SWV).
2. В поле Core Clock ввести частоту ядра, которую устанавливает программа. Её можно подсмотреть в переменной SystemCoreClock в окне Expressions после инициализации тактирования (при необходимости вызвать SystemCoreClockUpdate()). Частоту SWO среда подберёт сама; для медленной разводки её ограничивают опцией Limit SWO clock.
3. Запустить отладку, открыть Window → Show View → SWV → SWV ITM Data Console, в настройках окна включить порт 0 и нажать красную кнопку Start Trace, затем продолжить выполнение программы.

По UM2609 запись байта в порт ITM занимает один цикл записи, но функция CMSIS ITM_SendChar() перед записью ждёт, пока порт освободится: при медленном SWO и большом объёме вывода printf тормозит программу. Если ITM не включён (отладчик не подключён), функция сразу возвращается. Ограничения: SWV обычно есть на Cortex-M3, M4, M7 и M33, но его нет на Cortex-M0 и M0+ (например, у STM32L053), а вывод SWO микроконтроллера должен быть подключён к программатору. Альтернативы — UART (например, через виртуальный COM-порт, который есть у ST-LINK/V2-1 и STLINK-V3) или SEGGER RTT, для которого нужен J-Link.

Если в консоли пусто, руководство UM2609 предлагает проверить: включён ли SWV именно в той конфигурации, которая запущена; нажата ли кнопка Start Trace; верна ли частота Core Clock (самая частая причина); не меняет ли программа частоту ядра на ходу; не переполнен ли SWO лишними данными трассировки; поддерживают ли SWV программатор, сервер и плата.

Частые проблемы

Текст «Target not halted» не встречается ни в UM2237, ни в просмотренных разделах UM2609 (полный поиск по UM2609 не проводился); в таблице — меры из описания режимов подключения в этих двух руководствах. Сами ST-LINK, их напряжения и скорости разобраны в обзоре программаторов и отладчиков; как подключить плату STM32 к компьютеру без ST-LINK — в статье о загрузчике STM32.