STM32 HAL and CubeMX skill for Codex

Done well means: the .ioc file is the single source for pins and clocks and can be regenerated at any time without losing code, every HAL call’s return value is handled, high-rate I/O runs on DMA or interrupts rather than polling, and the project builds and flashes from the command line.

Inspect first

1. Read AGENTS.md, then open the .ioc as text: MCU part (Mcu.UserName), CubeMX version, firmware package version (ProjectManager.FirmwarePackage), toolchain (ProjectManager.TargetToolchain).
2. Note the build: CMakeLists.txt plus cmake/stm32cubemx/ (CubeMX 6.11+ CMake export), .cproject (STM32CubeIDE) or a Makefile.
3. Find where application code lives. Anything outside /* USER CODE BEGIN ... */ and /* USER CODE END ... */ in generated files is overwritten on regeneration.

cmake --preset Debug && cmake --build --preset Debug        # CubeMX CMake projects
arm-none-eabi-size build/Debug/app.elf

The Arm GNU toolchain and STM32CubeCLT must be installed on the host; installing them needs network and admin rights, so ask rather than attempting it in the sandbox.

Project structure that survives regeneration

• Enable “Generate peripheral initialization as a pair of .c/.h files per peripheral” in CubeMX so main.c stays small.
• Put application code in App/ (or Core/Src/app_*.c) and call it from one USER CODE block in main.c: app_init(); before the loop, app_run(); inside it.
• Never fix a generated file outside a USER CODE block. If a generated setting is wrong, change the .ioc and regenerate. Commit the .ioc together with generated output.
• Changing pins or clocks: edit in CubeMX, regenerate, then git diff the generated files to confirm only the expected peripherals changed.

HAL call discipline

HAL_StatusTypeDef st = HAL_I2C_Mem_Read(&hi2c1, BME280_ADDR << 1, 0xD0,
                                        I2C_MEMADD_SIZE_8BIT, &id, 1, 50);
if (st != HAL_OK) {
    log_err("i2c read %d err 0x%lx", st, HAL_I2C_GetError(&hi2c1));
    i2c_recover(&hi2c1);                    /* deinit/init, toggle SCL if bus stuck */
    return st;
}

• HAL I2C takes the 7-bit address shifted left by one. Passing the raw 7-bit address is the most common “device not responding” bug.
• Always pass a finite timeout in milliseconds; HAL_MAX_DELAY hangs forever on a stuck bus.
• HAL_BUSY usually means a previous IT/DMA transfer on the same handle has not finished, or an error left the handle state stuck. Check huart->gState / RxState and the error callback.
• HAL callbacks (HAL_UART_RxCpltCallback, HAL_GPIO_EXTI_Callback, …) are weak functions called from interrupt context. Keep them short and defer work.

UART receive: idle-line DMA

Use ReceiveToIdle with DMA for variable-length input; polling and byte-by-byte interrupts drop data at higher baud rates.

#define RX_SZ 256
static uint8_t rx_buf[RX_SZ];

void uart_start(void) {
    HAL_UARTEx_ReceiveToIdle_DMA(&huart2, rx_buf, RX_SZ);
    __HAL_DMA_DISABLE_IT(huart2.hdmarx, DMA_IT_HT);   /* no half-transfer events */
}

void HAL_UARTEx_RxEventCallback(UART_HandleTypeDef *huart, uint16_t size) {
    if (huart->Instance == USART2) {
        rx_push(rx_buf, size);                           /* copy out or hand to a task */
        HAL_UARTEx_ReceiveToIdle_DMA(&huart2, rx_buf, RX_SZ);
        __HAL_DMA_DISABLE_IT(huart2.hdmarx, DMA_IT_HT);
    }
}

void HAL_UART_ErrorCallback(UART_HandleTypeDef *huart) {
    uart_start();                                        /* overrun/framing: restart */
}

For continuous high-rate streams use circular DMA and track the write position from size across callbacks instead of restarting.

Cache and DMA on Cortex-M7 (F7, H7)

• DMA does not see the D-cache. Before a DMA transmit, clean the buffer (SCB_CleanDCache_by_Addr); after a DMA receive, invalidate it (SCB_InvalidateDCache_by_Addr). Buffers must be 32-byte aligned and sized in multiples of 32 or the invalidate corrupts neighbours.
• Or place DMA buffers in a non-cacheable region configured by the MPU.
• On H7, DMA1/DMA2 cannot reach DTCM RAM (0x20000000). Put DMA buffers in AXI SRAM or SRAM1-3 with a linker section, or transfers silently do nothing.

Timebase, clocks and RTOS

• With FreeRTOS, CubeMX asks to move the HAL timebase off SysTick; pick a basic timer (TIM6/TIM7). SysTick belongs to the kernel.
• Clock tree changes affect UART baud, timer periods and ADC sampling. After changing SystemClock_Config, recheck every timer prescaler and the actual baud with a scope or logic analyser.
• Set NVIC_PRIORITYGROUP_4 and keep ISRs that call RTOS APIs at or below the RTOS syscall priority (freertos covers the rule).

printf over UART or SWO

int _write(int fd, char *ptr, int len) {
    (void)fd;
    HAL_UART_Transmit(&huart2, (uint8_t *)ptr, (uint16_t)len, 100);
    return len;
}

Float formatting with newlib-nano needs -u _printf_float at link time and costs several KB of flash. For high-rate logs prefer SWO/ITM or RTT over a blocking UART.

Flashing and debugging

STM32_Programmer_CLI -c port=SWD -w build/Debug/app.elf -v -rst
openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \
        -c "program build/Debug/app.elf verify reset exit"

Hardware is usually attached to the user’s machine, not the Codex sandbox: give the exact command and ask for its output.

Ask for explicit confirmation before any of these, and state the consequence:

• Full chip erase (-e all): wipes calibration or data stored in flash.
• Option bytes changes, especially read-out protection. RDP level 1 back to 0 mass-erases the chip; RDP level 2 is permanent and disables debug forever.
• Writing to the system memory or OTP areas.

HardFault triage

1. In the debugger read SCB->CFSR (0xE000ED28), HFSR (0xE000ED2C), MMFAR, BFAR.
2. Recover the stacked PC from the exception frame (MSP or PSP depending on bit 2 of LR) and map it with arm-none-eabi-addr2line -e app.elf 0x0800xxxx.

CFSR bit	Typical cause
PRECISERR with valid BFAR	Access to a disabled peripheral (clock not enabled) or bad pointer
IMPRECISERR	Buffered write fault; set DISDEFWBUF temporarily to make it precise
UNALIGNED / INVSTATE	Unaligned access with trapping on, or call through a bad function pointer
STKERR / MSTKERR	Stack overflow during exception entry

Verification

• Regenerate from .ioc; git diff shows no lost user code
• Command-line build clean at the release optimisation level
• Every HAL call result checked; error callbacks restart the peripheral
• Peak-rate test (max baud, back-to-back frames) without dropped bytes, from user logs
• On M7 parts, DMA buffers aligned and cache-maintained or in non-cacheable RAM

Report

**MCU:** STM32H743ZI, CubeMX 6.13, STM32CubeH7 1.12, CMake + Ninja
**Root cause:** UART RX buffer in DTCM, unreachable by DMA1; data stayed zero
**Change:** RX buffer moved to .dma_buffer in RAM_D2 (32-byte aligned); ReceiveToIdle DMA
**Verified:** 921600 baud, 10 min burst test, 0 dropped frames (user-provided log)