STM32F4 flash stub

A small RAM monitor that installs, checks and backs up the internal flash of the STM32F405 radios behind the vendor bootloader, one image for all of them. A running RadioFoundry loads it through the debug link (debuglink.md 3.18) and jumps to it with no power cycle. The host then sends the radio's board record (section 5.2), and only then can the stub write. It does for the STM32 radios what the HR_C7000 stub does for those radios (stub/README.md).

Status (2026-10-22): built, host tested and run on an HR_C6000 board (section 11, with protocol 2). Protocol 4 (the board record) is host tested only (tested = false in each board's [flash.stub]).

1. Why

The bootloader route costs three things:

2. Feasibility

2.1 Options compared

3. Entry

1. The host sends STUB INFO, BEGIN, DATA and ENTER (debuglink.md 3.18). INFO reports the run address 0x20000000 and the 8 KB span. The data goes into RadioFoundry's staging buffer (stub_region), which lies anywhere in RadioFoundry's .bss.
2. ENTER is refused with busy (3) while the radio transmits. Otherwise the reply goes out, the banner "PC Loader Connected" is drawn with the backlight at full (the generic entry code in core/stubentry/stub_entry.c, so a dimmed or switched-off backlight does not hide it), and enter_stub runs in the host link task:

Clocks stay as RadioFoundry set them (72 MHz, USB 48 MHz on every STM32F4 radio; the reduced clock is never active while USB is configured). GPIO levels stay, so the power latch holds. The option bytes select the software watchdog, so the IWDG runs only when RadioFoundry started it (CONFIG_WATCHDOG). Once started only a reset stops it, so the stub feeds it: first thing in stub_main, in stub_ms(), which every wait loop reads (the main loop, the flash and SPI busy waits, the USB waits, the delays), and from the protocol engine at every request, before each erase or program and once per 4 KB block of SUMS and READ (stubeng_port_t.feed). A feed does nothing while the IWDG isn't running. The image header (3.1) says so; RadioFoundry with its IWDG running refuses a stub whose header doesn't (watchdog.md 3.1).

Handoff flags in r0:

3.1 Image header

16 bytes at offset 0x10 of the image (0x20000010 once copied), right after the 12-byte entry code; the linker script puts section .stub_header there and fails the build if the entry code grows past it. Little endian. One definition, stub/stm32f4/f4stub_header.h, shared by the stub and RadioFoundry (platform/stm32f4/stub_entry.c); f4stub.py and the web flasher (f4stub.js) read the same layout, and their self-tests check their numbers against that file.

Versions: 1 the first stub, 2 the SPI flash, 3 the header and the IWDG feeds (F4STUB_VERSION_FEEDS_IWDG), 4 the shared engine with CONFIG and the board record (section 5). Stubs before version 3 have no header: those bytes are code. While its IWDG runs, RadioFoundry enters a stub only when all three hold: the magic, a version of at least 3 and the feed flag (f4stub_image_ok). Otherwise ENTER is refused with reason 1 (debuglink.md 3.18). With the IWDG not running any stub is entered. stubtool.py --rfoundry-enter and the web flasher print the version from the header before they send the image.

4. USB in the stub

A CDC-ACM device on the OTG_FS core in slave mode (no DMA, no interrupt line): bulk OUT 0x01 and IN 0x81 (64 bytes), interrupt IN 0x82 (8 bytes), VID 0x1FC9, PID 0x0094, the serial number RadioFoundry uses (the 96-bit UID in hex, lowest byte first), product "RadioFoundry flash stub".

After a fresh enumeration Linux may give the port the next number (/dev/ttyACM1) while it still holds the old name. stubtool.py waits up to 20 s for the stub. It tries the port name it was given for the first 10 s (a /dev/serial/by-path/… name stays valid across this). After that it also tries a port with the stub's USB ID, taken only from the same USB location as the port RadioFoundry was on, or, if the location is unknown, the one port with RadioFoundry's serial number or USB ID. Two candidates are never guessed between: it stops and says so.

The stub handles a bus reset at any time, so a host that resets the port gets a fresh enumeration. FIFO RAM in cold start: RX 128 words, EP0 TX 16, EP1 TX 64, EP2 TX 16. A transfer that ends on a full 64-byte packet gets a zero-length packet after it. HELLO's flags byte says which start happened.

None of this is a board fact. OTG_FS on PA11 / PA12 is the STM32F405's only full speed port, and RadioFoundry has set its pins up before the jump. Every STM32F4 radio runs it with VBUS sensing off and gives RadioFoundry's serial number from the UID, so the stub carries no USB settings per radio.

Web Serial note: after a re-enumeration the page has to reopen the port. Chrome keeps the permission for the same USB IDs and serial number, so navigator.serial.getPorts() returns it without a new prompt.

5. Protocol

The HR_C7000 stub's framing, unchanged, so the host tools share it:

All numbers are big endian (as in the HR_C7000 stub; the debug link is little endian). The sum is the low byte of the payload's byte sum. USB has its own CRC per packet; every flash block also carries a CRC-32. A request that stops arriving for 200 ms is dropped. The largest payload is 4104 bytes (STUBENG_MAX_PAYLOAD).

The magic is 0x46345342 ("F4SB").

5.1 Shared with the HR_C7000 stub, and what differs

5.2 The board record

The stub image is the same for every radio; what differs goes in a 24-byte record the host sends with CONFIG (layout in stub/stm32f4/f4stub.h, the values from the board registry, read into stub/f4stub.py BOARDS). The host picks the profile from the running RadioFoundry's VERSION board= (or --board), sends it, reads HELLO again and checks that the echo is byte for byte what it sent and that the application base is 0x0800C000. Only then does it write.

Where each field comes from:

tools/boards.py get <board> flash.stub prints a board's values; the radio's hardware page says where they come from. The crystal only sets the stub's own timing (time-outs, the 200 ms idle rule): the stub reads the clock tree RadioFoundry left and needs the HSE to turn it into Hz. Until a record arrives it assumes 8 MHz.

The record matters most on a radio whose flash is not on the SPI1 wiring a protocol 2 stub had built in (stub/f4stub.py V2_WIRING): there those pins may reach another chip, and a stub with that wiring built in would send flash commands to it. A stub before protocol 4 serves only a board whose record matches V2_WIRING.

tools/boards.py check holds each profile to the board's sources: every pin it names must be in pins.h in the GPIOx, GPIO_PIN_n form, the bus must have an alternate function, and the crystal must be set.

Why the host sends the record

The other way considered: RadioFoundry passes a pointer to a board record in a register at the jump, as it passes the USB flag.

The HR_C7000 stub made the same choice.

stubtool.Radio holds the shared parts (frames, retries, the debug link loader, the READ record decoder) and f4stub.F4Radio subclasses it. The web flasher splits the same way: f4stub.js extends stub.js, and the flasher updates and backs up a radio running RadioFoundry with stub entry through it (website.md). It sends the records config_record() makes, carried in the site's data/flash-boards.json, and builds none itself.

6. Safety rules

The stub enforces these, so a host bug can't break them:

6.1 The SPI flash

The wiring comes from the board record (section 5.2). At CONFIG the stub drives the chip select and the held-high pins high as outputs, puts SCK, MISO and MOSI on their alternate function, and sets the SPI block up from scratch (master, the record's mode, DMA requests off) at the slowest prescaler at or under the record's rate, from the APB clock of that block (APB2 for SPI1, APB1 for SPI2 and SPI3). It wakes the chip (0xAB), reads its JEDEC ID (0x9F), takes the size from the ID's capacity byte, up to 16 MB (3 address bytes), and waits while the chip reports busy, in case RadioFoundry handed over during an erase. Reads use 0x03, erases 0x20 (4 KB), programs 0x02 in pages, each behind write enable (0x06) with the status register (0x05) polled. A chip that doesn't answer gives size 0, and every SPI request is then refused.

On an HR_C6000 board on the bench (2026-10-16): JEDEC ef4018, the whole 16 MB read in 59 s (about 280 KB/s) and verified, and a pattern written to a blank sector, read back and erased again, after which the whole chip matched the first read.

7. Update order and recovery

The bootloader stays in DFU mode when the application's initial stack pointer at 0x0800C000 fails (SP & 0x2FFE0000) == 0x20000000; an erased word does. The host uses that as the commit flag:

1. HELLO; the board from the radio's VERSION reply before the entry.
2. SUMS over every sector that holds firmware-owned flash; plan the new content (section 8). Stop if nothing changed.
3. Save any sector that also holds bytes the firmware doesn't own (an HR_C5000 board's sector 6) to a file outside git.
4. ERASE sector 3. From here on the bootloader stays in DFU at every power-on.
5. ERASE and PROGRAM every other changed sector (4 KB pieces, blank pieces skipped).
6. PROGRAM sector 3 from 0x0800C004.
7. SUMS over everything written, with the first word expected erased.
8. PROGRAM the first word (the commit). SUMS of its block.
9. RESET, or leave it to a power cycle.

The bootloader (sectors 0-2) is never touched, so the bootloader route always stays.

HR_C5000 boards: whether the bootloader checks the stack pointer the same way is unverified. If it does not, an interrupted update makes the radio jump to an erased vector. The power-on key combination still reaches DFU, so recovery is the same with the keys held.

8. The codec and the other bytes in a sector

The host knows which flash the firmware owns (f4stub.BOARDS, from the board registry: the linker script's application region):

Inside an owned range, bytes past the image end become 0xFF, so an older, longer build leaves nothing behind. An image merged with the codec (rfoundry_<board>_codec.bin) runs to the end of flash; the tool splits it into the application and the codec sectors and writes both whole (codec-placement.md, "STM32 radios"). Any other image that reaches outside the owned range (the wrong board) is refused before anything is erased.

No radio shares a sector between the firmware and the codec. The rule for one that would stays in the code: a sector that is rewritten and holds bytes the firmware doesn't own is read back and written again with those bytes unchanged.

The stub only runs on a radio that already runs RadioFoundry. A first install, on a radio still on its original firmware, goes through the bootloader with rfoundry's merge mode.

9. Backups and read protection

So the stub buys updates and post-install backups. It does not buy a pre-install backup of a radio on its original firmware. A dump holds the proprietary bootloader and codec: the tool refuses to write one inside a git work tree, and dumps are never committed.

10. Size and cost

The switch is on by default. The command hands the whole SoC to whatever image the host sends, guarded by the magic, the length and the CRC-32; a signed or hash-pinned stub would close that (section 12).

11. First hardware test (HR_C6000 board)

Nothing below transmits. Build, then flash once through the bootloader:

make BOARD=<id> CONFIG_STUB_ENTRY=y -j8
make -C stub/stm32f4
python3 tools/release.py --board <id> --version v0.0.0-stub --out build/dist
(radio in the bootloader: PTT + side key 1 at power-on)
cd tools/rfoundry && python3 -m rfoundry flash ../../build/dist/rfoundry-<id>-v0.0.0-stub.bin --yes   (key or --stock as usual)

Then, with RadioFoundry running (PORT is its USB serial port, /dev/cu.usbmodem… on macOS):

Steps 4 and 5 write the dump outside the repository. Step 9 needs rfoundry and the stock firmware file at hand. The HIL suite can gain a test for steps 2 and 3 (opt-in, reads only).

Results on an HR_C6000 board (2026-10-16, RDP level 1): steps 1 to 8 and 10 to 12 pass. The stub reads the bootloader's vector table from SRAM (so code running from RAM reads flash at RDP 1), a 1 MB read takes 2 s and matches the image flashed through the bootloader, an unchanged image writes 0 sectors, a changed one writes 5 sectors in 8 s, and the codec sectors stay (the radio still finds its codec). Step 9 is still to do.

12. Open points

• Step 9 of section 11 (an interrupted write and the recovery) on hardware.
• Protocol 4 (the board record) on hardware: section 11 again on an HR_C6000 board.
• HR_C5000 boards: the bootloader's stack pointer check, and the stub on a real radio.
• rfoundry: use the stub when the radio runs a CONFIG_STUB_ENTRY build, with the bootloader as the fallback.
• Release use: pin the stub image (the radio could refuse a stub whose SHA-256 is not built in), then turn the switch on by default.

13. The shared engine

The protocol engine (stub/common/stubeng.h, stubeng.c) knows no chip. It holds the framing, every op, the safety rules of section 6, CRC-32 SUMS and block READ, and the board record's copy for the HELLO echo. A target supplies a stubeng_port_t and its glue: the STM32F4 target is stub/stm32f4 (USB, flash controller, SPI, entry); a Kinetis K22F target would be another directory with the same shape. The wire protocol (section 5) is the same for every target; only the HELLO name, the op magic and the board record's layout are the target's.

The engine checks the application base configure returns: a sector start, not sector 0, at or above min_app_base. The commit word is at that base, and the commit sector (the interlock's) is the sector holding it. The engine keeps 2 x 4 KB frame buffers and a 4 KB word buffer (stubeng_t, about 12.3 KB of RAM) and needs no heap. It calls nothing but the port, memcpy, memmove, memset and memcmp.

A new target needs: the port, a receive loop that feeds bytes with stubeng_feed and calls stubeng_idle after 200 ms of silence, its board record layout and check (host tested, as f4stub_board.c), its host-side profiles, and the host tests: tests/host/f4stubTest.c already runs the engine with a uniform 2 KB sector map and 8-byte program units.

Sources: STM32F405/407 reference manual (embedded flash interface: unlock, sector erase, programming parallelism, read protection levels; OTG_FS device programming model), STM32F405 data sheet (flash erase and program times), USB 2.0 chapter 9, USB CDC 1.2 and PSTN 1.2.

View the source of this page