Bootloader design

/* Bootloader linker script — STM32G431RB example
   Bootloader: 0x08000000 – 0x08007FFF (32 kB, sectors 0–15)
   Shared config region: 0x08008000 – 0x08009FFF (8 kB, sector 16)
   App Bank A: 0x0800A000 – 0x0803FFFF (216 kB)
   App Bank B: 0x08040000 – 0x08077FFF (224 kB)           */

MEMORY {
    FLASH_BL  (rx)  : ORIGIN = 0x08000000, LENGTH = 32K
    FLASH_CFG (r)   : ORIGIN = 0x08008000, LENGTH = 8K
    FLASH_APP (rx)  : ORIGIN = 0x0800A000, LENGTH = 216K
    RAM       (rwx) : ORIGIN = 0x20000000, LENGTH = 32K
    RAM_BKP   (rw)  : ORIGIN = 0x40024000, LENGTH = 4K   /* backup SRAM */
}

SECTIONS {
    .text : {
        KEEP(*(.isr_vector))      /* vector table must be first */
        *(.text*)
        *(.rodata*)
    } > FLASH_BL

    /* Bootloader metadata in a fixed location — app can read this */
    .bl_version : {
        KEEP(*(.bl_version))
    } > FLASH_BL

    .data : {
        __data_start_vma = .;
        *(.data*)
        __data_end_vma = .;
    } > RAM AT> FLASH_BL   /* VMA in RAM, LMA in flash */

    .bss : {
        __bss_start = .;
        *(.bss*)
        *(COMMON)
        __bss_end = .;
    } > RAM

    /* Boot flags in backup SRAM — survives warm reset */
    .boot_flags (NOLOAD) : {
        KEEP(*(.boot_flags))
    } > RAM_BKP
}

/* Application firmware header — at the very start of app flash region */
typedef struct {
    uint32_t stack_pointer;     /* initial MSP — loaded from APP_START+0 */
    uint32_t reset_handler;     /* reset vector  — loaded from APP_START+4 */
    uint32_t magic;             /* 0xDEADC0DE — validity marker            */
    uint32_t version;           /* firmware version: major<<24|minor<<16|patch */
    uint32_t length;            /* firmware length in bytes                */
    uint32_t crc32;             /* CRC32 over [APP_START+32 .. APP_START+length] */
    uint32_t reserved[2];       /* padding to 32 bytes                     */
} FirmwareHeader_t;

#define APP_START   0x0800A000UL
#define HDR_MAGIC   0xDEADC0DEUL

bool Bootloader_IsAppValid(void) {
    const FirmwareHeader_t *hdr = (const FirmwareHeader_t *)APP_START;
    if (hdr->magic != HDR_MAGIC)       return false;
    if (hdr->stack_pointer < 0x20000000UL) return false;  /* must point to RAM */
    if (hdr->reset_handler < APP_START)    return false;  /* must be in app flash */
    uint32_t crc = CRC32_Compute((uint8_t *)APP_START + 32, hdr->length - 32);
    return (crc == hdr->crc32);
}

__attribute__((noreturn)) void Bootloader_JumpToApp(void) {
    const FirmwareHeader_t *hdr = (const FirmwareHeader_t *)APP_START;

    /* 1. Disable all interrupts and peripheral clocks before jumping */
    __disable_irq();
    SysTick->CTRL = 0;         /* disable SysTick */
    /* De-init any peripherals your bootloader enabled */
    HAL_RCC_DeInit();
    HAL_DeInit();

    /* 2. Relocate vector table to application */
    SCB->VTOR = APP_START;
    __DSB();
    __ISB();

    /* 3. Set stack pointer and jump — must be in assembly to be safe */
    __asm volatile (
        "msr msp, %0       \n"  /* set main stack pointer */
        "bx  %1            \n"  /* branch to reset handler */
        :
        : "r" (hdr->stack_pointer),
          "r" (hdr->reset_handler)
        : "memory"
    );
    __builtin_unreachable();
}

/* Placed in backup SRAM — survives warm reset, lost on power cycle  */
typedef struct __attribute__((packed)) {
    uint32_t magic;           /* 0xB007F1A6 — valid if this matches */
    uint8_t  active_bank;     /* 0 = Bank A, 1 = Bank B             */
    uint8_t  boot_count;      /* incremented each boot, reset on success */
    uint8_t  update_pending;  /* 1 = bootloader should enter update mode */
    uint8_t  reserved;
    uint32_t last_fault_pc;   /* PC at last HardFault, 0 if none    */
    uint32_t last_fault_lr;   /* LR at last HardFault                */
    uint32_t crc;             /* CRC32 of this struct (all above fields) */
} BootFlags_t;

#define BOOT_FLAGS_MAGIC  0xB007F1A6UL

__attribute__((section(".boot_flags")))
volatile BootFlags_t g_boot_flags;

void BootFlags_Init(void) {
    uint32_t crc = CRC32_Compute((uint8_t *)&g_boot_flags,
                                  sizeof(BootFlags_t) - 4);
    if (g_boot_flags.magic != BOOT_FLAGS_MAGIC || crc != g_boot_flags.crc) {
        /* Corrupt or first boot — initialise to defaults */
        g_boot_flags.magic         = BOOT_FLAGS_MAGIC;
        g_boot_flags.active_bank   = 0;   /* Bank A */
        g_boot_flags.boot_count    = 0;
        g_boot_flags.update_pending= 0;
        g_boot_flags.last_fault_pc = 0;
        g_boot_flags.last_fault_lr = 0;
        BootFlags_UpdateCRC();
    }
}

void BootFlags_CommitBank(uint8_t bank) {
    g_boot_flags.active_bank = bank;
    g_boot_flags.boot_count  = 0;    /* reset on successful update */
    BootFlags_UpdateCRC();
    __DSB();   /* ensure write completes before reset */
}

void Bootloader_Main(void) {
    BootFlags_Init();

    /* Check if update was requested by application */
    if (g_boot_flags.update_pending) {
        g_boot_flags.update_pending = 0;
        BootFlags_UpdateCRC();
        Update_Run();   /* blocking — returns only on abort or completion */
    }

    /* Increment boot counter — application must confirm boot to reset it */
    g_boot_flags.boot_count++;
    BootFlags_UpdateCRC();

    uint8_t bank = g_boot_flags.active_bank;

    /* Try active bank */
    if (Bootloader_IsAppValid(bank)) {
        Bootloader_JumpToApp(bank);
        /* never returns */
    }

    LOG_WARN("Active bank %d invalid. Trying other bank.", bank);

    /* Try other bank */
    uint8_t other = bank ^ 1u;
    if (Bootloader_IsAppValid(other)) {
        BootFlags_CommitBank(other);
        NVIC_SystemReset();
        /* never returns */
    }

    LOG_ERROR("Both banks invalid. Booting golden image.");

    /* Last resort: jump to golden image (write-protected, always valid) */
    Bootloader_JumpToGolden();
    /* never returns */
}

#!/usr/bin/env python3
"""
build_image.py — append firmware header to a .bin file for bootloader consumption

Usage: python build_image.py input.bin output_with_header.bin --version 1.2.3
"""
import struct, zlib, argparse, pathlib, datetime

MAGIC       = 0xDEADC0DE
HEADER_SIZE = 32   # bytes (must match FirmwareHeader_t in C)

def crc32(data: bytes) -> int:
    return zlib.crc32(data) & 0xFFFFFFFF

def build_image(input_path: str, output_path: str, version: str) -> None:
    fw_bytes = pathlib.Path(input_path).read_bytes()

    major, minor, patch = (int(x) for x in version.split('.'))
    ver_word = (major << 24) | (minor << 16) | patch

    # CRC covers everything AFTER the header
    fw_crc = crc32(fw_bytes)
    total_len = HEADER_SIZE + len(fw_bytes)

    # Pack the header (matches FirmwareHeader_t, first two fields from linker)
    # stack_pointer and reset_handler come from the binary's first 8 bytes
    sp     = struct.unpack_from('<I', fw_bytes, 0)[0]
    reset  = struct.unpack_from('<I', fw_bytes, 4)[0]

    header = struct.pack('<IIIIIII2I',
        sp,          # stack_pointer
        reset,       # reset_handler
        MAGIC,       # magic
        ver_word,    # version
        total_len,   # length
        fw_crc,      # crc32
        0, 0         # reserved
    )

    output = header + fw_bytes
    pathlib.Path(output_path).write_bytes(output)
    print(f"Image built: {output_path}")
    print(f"  Version : {version}")
    print(f"  Size    : {total_len} bytes ({total_len/1024:.1f} kB)")
    print(f"  CRC32   : 0x{fw_crc:08X}")
    print(f"  SP      : 0x{sp:08X}")
    print(f"  Reset   : 0x{reset:08X}")

if __name__ == '__main__':
    p = argparse.ArgumentParser()
    p.add_argument('input')
    p.add_argument('output')
    p.add_argument('--version', default='0.1.0')
    args = p.parse_args()
    build_image(args.input, args.output, args.version)

#!/usr/bin/env python3
"""
flash_uart.py — flash firmware to STM32 bootloader over UART

Usage: python flash_uart.py --port /dev/ttyUSB0 --baud 115200 firmware.fwu
"""
import serial, struct, zlib, time, sys, argparse
from pathlib import Path

SOH, EOT = 0x01, 0x04
ACK, NAK  = 0x06, 0x15
CMD_START, CMD_DATA, CMD_END, CMD_ABORT = 0x01, 0x02, 0x03, 0xFF

CHUNK_SIZE = 256   # bytes per CMD_DATA payload

def crc16(data: bytes) -> int:
    crc = 0xFFFF
    for b in data:
        crc ^= b << 8
        for _ in range(8):
            crc = (crc << 1) ^ 0x1021 if crc & 0x8000 else crc << 1
    return crc & 0xFFFF

def crc32(data: bytes) -> int:
    return zlib.crc32(data) & 0xFFFFFFFF

def build_frame(cmd: int, payload: bytes) -> bytes:
    body = bytes([cmd]) + struct.pack('<H', len(payload)) + payload
    return bytes([SOH]) + body + struct.pack('<H', crc16(body)) + bytes([EOT])

def send_recv(ser: serial.Serial, frame: bytes, timeout: float = 2.0) -> tuple[int, bytes]:
    ser.write(frame)
    ser.flush()
    deadline = time.time() + timeout
    buf = b''
    while time.time() < deadline:
        chunk = ser.read(ser.in_waiting or 1)
        buf += chunk
        if len(buf) >= 1:
            resp_code = buf[0]
            if resp_code == ACK:
                payload = buf[1:] if len(buf) > 1 else b''
                return ACK, payload
            elif resp_code == NAK:
                err = buf[1] if len(buf) > 1 else 0
                return NAK, bytes([err])
    return 0xFF, b''   # timeout

def flash(port: str, baud: int, image_path: str) -> bool:
    data = Path(image_path).read_bytes()
    total = len(data)
    img_crc = crc32(data)
    chunks = [data[i:i+CHUNK_SIZE] for i in range(0, total, CHUNK_SIZE)]

    print(f"Image  : {image_path} ({total} bytes, CRC=0x{img_crc:08X})")
    print(f"Port   : {port} @ {baud} baud")
    print(f"Chunks : {len(chunks)} × {CHUNK_SIZE}B")
    print()

    with serial.Serial(port, baud, timeout=0.1) as ser:
        # CMD_START
        payload = struct.pack('<II', total, img_crc)
        code, _ = send_recv(ser, build_frame(CMD_START, payload), timeout=30.0)
        if code != ACK:
            print(f"[FAIL] CMD_START rejected (NAK 0x{(_ or b'')[0]:02X})")
            return False
        print("[OK]  START — erase complete")

        # CMD_DATA
        for i, chunk in enumerate(chunks):
            offset = i * CHUNK_SIZE
            payload = struct.pack('<I', offset) + chunk
            for attempt in range(3):
                code, _ = send_recv(ser, build_frame(CMD_DATA, payload))
                if code == ACK:
                    break
                print(f"  Retry {attempt+1}/3 at offset 0x{offset:06X}")
            else:
                print(f"[FAIL] CMD_DATA at offset 0x{offset:06X} after 3 retries")
                return False

            pct = (i + 1) / len(chunks) * 100
            bar = '#' * int(pct / 2) + '.' * (50 - int(pct / 2))
            print(f"\r  [{bar}] {pct:5.1f}%", end='', flush=True)

        print("\n[OK]  Transfer complete")

        # CMD_END
        payload = struct.pack('<I', img_crc)
        code, _ = send_recv(ser, build_frame(CMD_END, payload), timeout=5.0)
        if code != ACK:
            print(f"[FAIL] CMD_END rejected — CRC mismatch on target?")
            return False

    print("[OK]  Image verified and committed — target rebooting")
    return True

if __name__ == '__main__':
    p = argparse.ArgumentParser()
    p.add_argument('--port',  default='/dev/ttyUSB0')
    p.add_argument('--baud',  type=int, default=115200)
    p.add_argument('image')
    args = p.parse_args()
    sys.exit(0 if flash(args.port, args.baud, args.image) else 1)

/* In the bootloader, a HardFault during update is a catastrophic event.
   The goal: log what happened, invalidate the partially-written image,
   and reboot cleanly to the active bank.                                */

void HardFault_Handler_C(uint32_t *frame) {
    /* Save fault context to boot flags (backup SRAM — survives reset) */
    g_boot_flags.last_fault_pc = frame[6];   /* stacked PC */
    g_boot_flags.last_fault_lr = frame[5];   /* stacked LR */
    BootFlags_UpdateCRC();

    /* If we were in the middle of an update: mark inactive bank as invalid
       so the bootloader won't try to boot a partially-written image      */
    uint8_t inactive = g_boot_flags.active_bank ^ 1u;
    Flash_EraseSector(Bank_GetFirstSector(inactive));   /* wipe header */

    /* Try to log over UART before resetting */
    LOG_ERROR("BL HardFault PC=0x%08X LR=0x%08X CFSR=0x%08X",
              frame[6], frame[5], SCB->CFSR);

    NVIC_SystemReset();
}

__attribute__((naked)) void HardFault_Handler(void) {
    __asm volatile (
        "tst lr, #4     \n"
        "ite eq         \n"
        "mrseq r0, msp  \n"
        "mrsne r0, psp  \n"
        "b HardFault_Handler_C \n"
    );
}