ms-bootloader

A reusable, chip agnostic CAN and UART bootloader for STM32 class MCUs, plus the host side flashing client and geometry tooling. It is designed to live as a git submodule inside a firmware repo (the host): the host supplies a thin hardware port and per board geometry, and gets back a discovery, flash, verify and jump pipeline that is identical across boards.

The portable core links only the 19 bl_port_* functions and standard C, with no ms-common dependency. On x86 it links port/x86 so the unit tests run with no hardware.

Layout

common/          portable core: status codes, CRC32, datagram, config record, identity, jump
bootloader/      DFU session state machine (metadata -> chunks -> verify -> record -> jump)
bootstrap/       first stage: validate the bootloader image and jump to it
entry/           app side: bl_entry_shim (drop back to bootloader) + bl_responder (discovery)
transport/can/   fragment and reassemble datagrams over classic CAN frames
transport/uart/  the same datagrams over UART (for gateways)
port/x86/        reference port used by the unit tests (the host supplies the ARM port)
client/          Rust host GUI that flashes boards over CAN (socketcan)
tools/           generate.py (linker map + flash params) and bl_manifest.py (artifact manifest)
examples/        a worked board.toml and the app side CAN integration snippet

Quickstart

The library has no standalone build of its own; a host repo compiles its layers. To exercise the portable core through the reference x86 port, build it from the host repo that mounts this submodule. The host side client builds on its own:

cd client
cargo run --release    # launch the flashing GUI
cargo test             # protocol parity tests (asserts wire sizes against the firmware)

Adopting this in a host repo

1. Add this repo as a submodule, then point your build at its layers and expose each inc/.
2. Implement the port profile(s) your role needs against your MCU HAL (PORTING.md).
3. Define the linker symbols and the .bl_noinit section (PORTING.md).
4. Provide a board.toml and generate the geometry artifacts (examples/board.toml).
5. Wire bl_entry_shim and bl_responder into your CAN receive path (examples/).

Documentation

• PORTING.md the bl_port_* contract, the three port profiles, app integration, linker symbols, board config
• PROTOCOL.md the versioned wire contract (datagram, identity, config record, CAN ids) and the client
• examples/ a complete board.toml and a reference Profile B CAN integration

The wire formats are versioned in PROTOCOL.md. A flashed board and the client/ interoperate only if they agree on it, so pin the submodule by commit and treat any protocol change as a coordinated client and firmware update.