# davidgfnet/stm32-dfu-bootloader architecture

> Architecture diagram of the GitHub repository davidgfnet/stm32-dfu-bootloader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davidgfnet/stm32-dfu-bootloader
- Repository: https://github.com/davidgfnet/stm32-dfu-bootloader

## Overview

##### Project Type and Purpose
- This is an embedded‐firmware project: a minimal USB DFU bootloader for the STM32F103 microcontroller.
- Purpose: allow flashing of arbitrary user payloads over USB, enforce integrity checks and various protections, then jump to a validated user application.

##### File Structure Analysis
- Top‑level files:
- main.c, init.c, usb.c, watchdog.h, flash.h, reboot.h – core bootloader logic
- stm32f103.ld – linker script placing code at 0x08000000
- Makefile, .github/workflows/flavour-build.yml – build & CI
- checksum.py – helper for computing payload checksums
- upgrade/ – sample “client” project to bundle/send firmware via DFU
- .gitmodules → libopencm3 submodule under upgrade/libopencm3
- Patterns:
- Single binary bootloader <4 KB at flash base
- Linker‑script–driven memory mapping
- Compile‑time flags controlling features (DFU upload, write‑protect, etc.)
- Upgrade folder demonstrates how an external host tool interacts via DFU

##### Key Insights from README
- Boot strategy: on reset, read RAM magic or GPIO, watchdog reset, or NRST pin → DFU mode
- Protection: RDP, write‑protections, safe‑erase, checksum validation
- Payload format: vector table offset 0x1000, size @0x20, XOR checksum zero
- Config flags set compile‑time via Makefile

##### Components
a. Main Components
1. MCU Core (STM32F103)
- CPU, NVIC, VTOR
2. Memory Subsystems
- Flash[0x0800_0000–0x0800_1000): Bootloader region
- Flash[0x0800_1000–end): User application region
- SRAM[0x2000_0000–): RAM for stack + magic tag
- Option bytes / RDP protection registers
3. Peripherals
- USB DFU interface (USB FS peripheral)
- GPIO DFU‐boot pin
- Independent Watchdog (IWDG)
4. External Host
- PC running DFU client (e.g., upgrade/client.c or dfu-util)
b. Relationships & Data Flows
- On reset → Bootloader reads:
- Last 8 bytes of SRAM (magic tag)
- GPIO pin state or NRST cause
- If DFU mode:
- USB ←→ DFU state machine → erase/write flash → optional upload
- On valid payload:
- Check stack pointer, size, checksum
- If success → set VTOR to 0x0800_1000 → jump to app
- Watchdog timeout → reset → forced DFU
- Option bytes logic sets RDP/write‑protect → hardware block
c. Architectural Patterns & Principles
- Memory‑mapped bootloader vs. application
- State machine for DFU commands
- Minimalist code (<4 KB) for reliability and fit in protected region
- Compile‑time feature toggles for security/performance trade‑offs
d. Technologies & Frameworks
- C with libopencm3 (via submodule)
- GNU Make + linker scripts
- USB DFU protocol (USB descriptors in usb.c)
- Python helper for checksum (checksum.py)

##### Diagramming Conventions
- Use rectangles for major blocks (MCU, Memory, Host)
- Blue: bootloader logic
- Green: user application region
- Orange: hardware peripherals
- Gray: configuration/option bytes

##### Detailed Capture of Essential Elements
- Reset handler & init
- DFU state machine
- Protection enforcement (RDP, write‑prot)
- Jump logic to application
- Interactions:
- Magic‑tag in SRAM
- GPIO and NRST checks
- Watchdog service/reset
- Upgrade/client role as example host component that drives DFU sequence.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% MCU and Memory
    subgraph "STM32F103 MCU"
        direction TB
        subgraph "Core"
            CPU["CPU"]:::core
            NVIC["NVIC"]:::core
            VTOR["VTOR"]:::core
        end
        subgraph "Peripherals"
            USB["USB DFU Interface"]:::periph
            GPIO["GPIO DFU Pin"]:::periph
            IWDG["Independent Watchdog (IWDG)"]:::periph
        end
    end

    subgraph "Memory Map"
        direction TB
        BL_REGION["Bootloader<br/>0x0800_0000–0x0800_1000"]:::boot
        APP_REGION["User Application<br/>0x0800_1000–end"]:::app
        SRAM["SRAM<br/>0x2000_0000+"]:::mem
        OPT_BYTES["Option Bytes<br/>RDP/Write-Protect"]:::config
    end

    %% Bootloader Components
    subgraph "Bootloader Logic"
        direction TB
        Init["Reset Handler & Init"]:::boot
        DFU["USB DFU State Machine"]:::boot
        Prot["Protection Enforcement"]:::boot
        Jump["Reboot & Jump Logic"]:::boot
    end

    %% Host
    Host["External Host (PC DFU Client)"]:::external

    %% Build & CI
    subgraph "Build System & CI"
        direction TB
        Make["Makefile"]:::config
        CI[".github/workflows/flavour-build.yml"]:::config
        ChecksumHelper["checksum.py"]:::config
    end

    %% Upgrade Client
    subgraph "Sample DFU Client"
        direction TB
        CLI["upgrade/client.c"]:::external
        BUNDLE["upgrade/bundle.S"]:::external
        UPMake["upgrade/Makefile"]:::config
        UPReadme["upgrade/README"]:::config
        Submod["upgrade/libopencm3"]:::external
        LD_RAM["upgrade/stm32f103-ram.ld"]:::config
        LD_ROM["upgrade/stm32f103-rom.ld"]:::config
    end

    %% Core Flows
    CPU -->|uses| NVIC
    CPU -->|sets| VTOR

    %% Reset Sequence
    Init -->|reads| SRAM
    Init -->|checks| GPIO
    Init -->|checks| OPT_BYTES
    Init -->|triggers DFU?| DFU
    Init -->|or Jump| Jump

    %% DFU Flow
    Host -->|USB DFU| USB
    USB -->|DFU Commands| DFU
    DFU -->|erase/write| BL_REGION
    DFU -->|validate| Prot
    DFU -->|upload| BL_REGION

    %% Protection and Jump
    Prot -->|set RDP/protect| OPT_BYTES
    Prot -->|validate checksum| ChecksumHelper
    Prot -->|watchdog reset| IWDG
    Jump -->|set VTOR| VTOR
    Jump -->|jump to| APP_REGION

    %% Watchdog
    IWDG -->|timeout reset| Init

    %% Memory interactions
    CPU --> BL_REGION
    CPU --> APP_REGION

    %% Build & CI connections
    Make -->|compile| BL_REGION
    Make -->|linker| stm32f103.ld
    CI -->|trigger| Make

    %% Click Events
    click Init "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/init.c"
    click DFU "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/usb.c"
    click USB "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/usb.c"
    click USB "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/usb.h"
    click Prot "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/flash.h"
    click Jump "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/reboot.h"
    click IWDG "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/watchdog.h"
    click stm32f103.ld "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/stm32f103.ld"
    click ChecksumHelper "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/checksum.py"
    click Make "https://github.com/davidgfnet/stm32-dfu-bootloader/tree/master/Makefile"
    click CI "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/.github/workflows/flavour-build.yml"
    click CLI "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/upgrade/client.c"
    click BUNDLE "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/upgrade/bundle.S"
    click UPMake "https://github.com/davidgfnet/stm32-dfu-bootloader/tree/master/upgrade/Makefile"
    click UPReadme "https://github.com/davidgfnet/stm32-dfu-bootloader/tree/master/upgrade/README"
    click Submod "https://github.com/davidgfnet/stm32-dfu-bootloader/tree/master/upgrade/libopencm3"
    click LD_RAM "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/upgrade/stm32f103-ram.ld"
    click LD_ROM "https://github.com/davidgfnet/stm32-dfu-bootloader/blob/master/upgrade/stm32f103-rom.ld"

    %% Styles
    classDef boot fill:#cce5ff,stroke:#005cbf,color:#005cbf
    classDef app fill:#d4edda,stroke:#155724,color:#155724
    classDef mem fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef periph fill:#ffe5b4,stroke:#d39e00,color:#d39e00
    classDef core fill:#f0f8ff,stroke:#007bff,color:#007bff
    classDef config fill:#f8f9fa,stroke:#6c757d,color:#6c757d
    classDef external fill:#f5e6ff,stroke:#6f42c1,color:#6f42c1
```
