Repository navigation
stm: support the uf2-stm32f bootloader's reset signatures - #11903
Conversation
MakeCode Arcade consoles such as the ELECFREAKS Retro Arcade boot through the uf2-stm32f bootloader, which reads a signature from RTC->BKP0R on every reset. Without one it opens its UF2 drive and, once USB enumerates, stays there. So on these boards microcontroller.reset() and the reset into safe mode would stop in the bootloader. Add BOARD_UF2_STM32F_BOOTLOADER, off by default. With it set, reset_cpu() writes the bootloader's app signature just before resetting, and reset_to_bootloader() writes its boot signature instead of arming ST's ROM loader. RunMode.UF2 then works like RunMode.BOOTLOADER; both, and the 1200-baud touch, open the UF2 drive. microcontroller.reset() now goes through reset_cpu(), which is unchanged for boards without the flag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
@vegardw Is this really a bug that should be fixed in the bootloader?
@mmoskal is no longer at Microsoft, so the repo may be a dead end, but it could be forked. But I can understand that if a workaround is possible, that's fine.
|
@dhalbert I'll ask claude to help me investigate if something should be fixed in the bootloader. Thanks for merging. |
|
I looked into it with help from Claude Code, and I don't think it's a bootloader bug: it's how uf2-stm32f is meant to be used. uf2-stm32f sends every reset to its UF2 drive unless the app has first written an "app" signature to The bootloader could tell a software reset from the button by itself by checking While reading the code I did find one small real bug: it turns off the LSE on every boot ( |
Go ahead and fix it if it's a bug: one less cent of technical debt. |
Brings in the STM32F412Rx MCU support (adafruit#11896) and the uf2-stm32f bootloader support (adafruit#11903), both now merged upstream. The F412Rx pin tables conflicted: the merged version is main's, plus the FSMC entries from the display-bus commit. The resulting files are the same as before the merge. The tree is now main plus the display bus and board commits, the board README and Stage at the commit that adds this board. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The MCU, bootloader and display-bus support are now in main (adafruit#11896, adafruit#11903, adafruit#11908), as is the audiopwmio silent-source fix (adafruit#11889). Say so, update the base and free flash, and state briefly what was tested on the device and what wasn't. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds opt-in support for STM32 boards that boot through the
uf2-stm32f bootloader, as MakeCode Arcade consoles do.
No upstream board sets the new flag yet. The ELECFREAKS Retro Arcade (STM32F412RE) will, in its
board PR; its MCU support is #11896.
Problem
uf2-stm32f runs first after every reset and reads
RTC->BKP0R(itsmain_f4.candbl.c):RTC->BKP0R0x71a21877(boot signature)0x24a22d12(app signature)CircuitPython's resets leave
RTC->BKP0Ralone. So with USB connected,microcontroller.reset()and the reset into safe mode stop in the UF2 drive until someone presses reset.
RunMode.BOOTLOADERarms ST's ROM DFU loader instead of the UF2 drive these boards use, andRunMode.UF2is ignored on STM.Fix
A board flag,
BOARD_UF2_STM32F_BOOTLOADER, off by default. With it set:reset_cpu()writes the app signature just beforeNVIC_SystemReset(). That coversmicrocontroller.reset()and the reset into safe mode.reset_to_bootloader()writes the boot signature instead of arming ST's ROM loader, andRunMode.UF2is treated likeRunMode.BOOTLOADER. That covers both run modes and the1200-baud touch.
The signature is written just before each reset because
port_init()resets the backup domainat startup, after the bootloader has read it. The bootloader's own
resetIntoApp()andresetIntoBootloader()use the same two values.common_hal_mcu_reset()now callsreset_cpu()instead ofNVIC_SystemReset()directly, somicrocontroller.reset()takes the same path. For boards without the flag,reset_cpu()isjust
NVIC_SystemReset().This is the UF2 side that #11270 left open ("#3444 UF2 preference still unimplemented"): on
boards with this bootloader,
RunMode.BOOTLOADERnow opens the UF2 drive instead of ST's ROMloader.
Testing
On an ELECFREAKS Retro Arcade (STM32F412RE) with USB connected, using its board definition (not
yet upstream), on main
883e63fae6:microcontroller.reset()RunMode.UF2, thenreset()RunMode.BOOTLOADER, thenreset()RunMode.UF2The first row's "without the flag" result was observed with a test build that turns the flag
off: after
microcontroller.reset()the board stayed in the UF2 drive for the 40 s watched. Theother two follow from the code. The script below checked the "This PR" column on macOS, and on
Linux in an earlier run on an older main. The reset into safe
mode takes the
reset_cpu()path too; it came back in safe mode during an earlier fault, but thescript doesn't trigger it. Boards without the flag, one per STM family plus Meowbit
ru(thetightest image CI builds), all build on main
883e63fae6and are 32 bytes smaller.How to run the test
You need a board running uf2-stm32f with firmware that sets the flag, and pyserial
(
sudo apt install python3-serial). Start with an emptycode.py, so the board reaches the REPLafter each restart. Let the desktop mount the bootloader drive (or mount it when it appears),
then run the script with the CircuitPython UF2 to put back after each bootloader visit:
It finds the board again by its USB serial number after each reset, since Linux may give it a
new
ttyACMnumber. Expect PASS for all three checks.bootloader_test.pyTrade-offs and Alternatives
RTC->BKP0Ralso holds the STMalarmmodule's wake flag, and the bootloader clears thatregister on every boot, so deep-sleep wake reasons can't work behind it. The Retro Arcade board
turns
alarmoff. Moving the flag to another backup register would be a separate change.on a Meowbit, so this PR doesn't turn the flag on there.
peripherals and interrupts as they were. The signatures are the interface the bootloader
provides for this.
Generative AI
I used generative AI (Claude Code and Codex) to write and test this change. I have reviewed it,
and I am responsible for the code and this description.
🤖 Generated with Claude Code