# stmicroelectronics/stm32-mw-mcuboot architecture

> Architecture diagram of the GitHub repository stmicroelectronics/stm32-mw-mcuboot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stmicroelectronics/stm32-mw-mcuboot
- Repository: https://github.com/stmicroelectronics/stm32-mw-mcuboot

## Overview

MCUboot is a secure bootloader and firmware-upgrade system for 32-bit MCUs. Its runtime entry point initializes the platform and security counters, then hands boot decisions to the boot utility; flash mapping, image selection/update state, and platform handoff support execution. The repository also includes imgtool for preparing, signing, inspecting, and verifying images. The excerpts establish the entry-point setup, counter updates, flash abstraction, and imgtool command wiring; some runtime calls and unsampled subsystems are not directly shown, so those links are omitted or marked unverified.

Main entry points: [`scripts/imgtool/main.py`](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/scripts/imgtool/main.py) (imgtool CLI), [`bl2/ext/mcuboot/bl2_main.c`](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/ext/mcuboot/bl2_main.c) (BL2 entry), [`boot/bootutil/src/loader.c`](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/loader.c) (Boot loader), [`bl2/src/security_cnt.c`](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/src/security_cnt.c) (Security counters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and handoff"]
  node_bl2_main["BL2 entry<br/>[bl2_main.c]"]
end

subgraph group_core["Image boot utility"]
  node_loader["Boot loader<br/>[loader.c]"]
  node_image_validate["Image validation<br/>[image_validate.c]"]
  node_image_crypto["Image crypto<br/>[image_ec.c]"]
  node_swap["Swap handling<br/>[swap_move.c]"]
  node_swap_scratch["Scratch swap<br/>[swap_scratch.c]"]
  node_boot_record["Boot record<br/>[boot_record.c]"]
  node_image_format["Image format<br/>[image.h]"]
end

subgraph group_platform["Platform services"]
  node_flash_map["Flash mapping<br/>[flash_map.c]"]
  node_flash_device["Flash driver<br/>[Driver_Flash.h]"]
  node_security_counter["Security counters<br/>[security_cnt.c]"]
  node_nv_counter["NV counter API<br/>[plat_nv_counters.h]"]
  node_shared_data["Shared boot data<br/>[shared_data.c]"]
  node_boot_hal["Platform handoff<br/>[boot_hal.h]"]
end

subgraph group_tool["Image tooling"]
  node_imgtool_cli["imgtool CLI<br/>[main.py]"]
  node_image_builder["Image builder<br/>[image.py]"]
  node_key_ops["Key operations<br/>[ecdsa.py]"]
  node_image_dump["Image inspection<br/>[dumpinfo.py]"]
end

node_device(("MCU device"))
node_image_input["Firmware image"]

node_device -.->|"starts"| node_bl2_main
node_bl2_main -.->|"delegates boot"| node_loader
node_loader -->|"updates counter"| node_security_counter
node_security_counter -->|"uses counter API"| node_nv_counter
node_flash_map -->|"uses driver"| node_flash_device
node_shared_data -->|"reads image metadata"| node_image_format
node_bl2_main -->|"initializes platform"| node_boot_hal
node_image_input -.->|"provides image"| node_imgtool_cli
node_imgtool_cli -->|"creates image"| node_image_builder
node_imgtool_cli -->|"uses keys"| node_key_ops
node_imgtool_cli -->|"dispatches inspect"| node_image_dump

click node_bl2_main "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/ext/mcuboot/bl2_main.c"
click node_loader "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/loader.c"
click node_image_validate "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/image_validate.c"
click node_image_crypto "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/image_ec.c"
click node_swap "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/swap_move.c"
click node_swap_scratch "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/swap_scratch.c"
click node_boot_record "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/boot_record.c"
click node_image_format "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/include/bootutil/image.h"
click node_flash_map "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/src/flash_map.c"
click node_flash_device "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/platform/ext/driver/Driver_Flash.h"
click node_security_counter "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/src/security_cnt.c"
click node_nv_counter "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/platform/include/plat_nv_counters.h"
click node_shared_data "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/src/shared_data.c"
click node_boot_hal "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/include/boot_hal.h"
click node_imgtool_cli "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/scripts/imgtool/main.py"
click node_image_builder "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/scripts/imgtool/image.py"
click node_key_ops "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/scripts/imgtool/keys/ecdsa.py"
click node_image_dump "https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/scripts/imgtool/dumpinfo.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bl2_main toneBlue
class node_loader,node_image_validate,node_image_crypto,node_swap,node_swap_scratch,node_boot_record,node_image_format toneAmber
class node_flash_map,node_flash_device,node_security_counter,node_nv_counter,node_shared_data,node_boot_hal toneMint
class node_imgtool_cli,node_image_builder,node_key_ops,node_image_dump toneRose
class node_device,node_image_input toneIndigo
```

## Components

### Boot and handoff

- [BL2 entry](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/ext/mcuboot/bl2_main.c): `bl2/ext/mcuboot/bl2_main.c`

### Image boot utility

- [Boot loader](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/loader.c): `boot/bootutil/src/loader.c`
- [Image validation](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/image_validate.c): `boot/bootutil/src/image_validate.c`
- [Image crypto](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/image_ec.c): `boot/bootutil/src/image_ec.c`
- [Swap handling](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/swap_move.c): `boot/bootutil/src/swap_move.c`
- [Scratch swap](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/swap_scratch.c): `boot/bootutil/src/swap_scratch.c`
- [Boot record](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/src/boot_record.c): `boot/bootutil/src/boot_record.c`
- [Image format](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/boot/bootutil/include/bootutil/image.h): `boot/bootutil/include/bootutil/image.h`

### Platform services

- [Flash mapping](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/src/flash_map.c): `bl2/src/flash_map.c`
- [Flash driver](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/platform/ext/driver/Driver_Flash.h): `platform/ext/driver/Driver_Flash.h`
- [Security counters](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/src/security_cnt.c): `bl2/src/security_cnt.c`
- [NV counter API](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/platform/include/plat_nv_counters.h): `platform/include/plat_nv_counters.h`
- [Shared boot data](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/src/shared_data.c): `bl2/src/shared_data.c`
- [Platform handoff](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/bl2/include/boot_hal.h): `bl2/include/boot_hal.h`

### Image tooling

- [imgtool CLI](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/scripts/imgtool/main.py): `scripts/imgtool/main.py`
- [Image builder](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/scripts/imgtool/image.py): `scripts/imgtool/image.py`
- [Key operations](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/scripts/imgtool/keys/ecdsa.py): `scripts/imgtool/keys/ecdsa.py`
- [Image inspection](https://github.com/stmicroelectronics/stm32-mw-mcuboot/blob/main/scripts/imgtool/dumpinfo.py): `scripts/imgtool/dumpinfo.py`

### Other components

- **MCU device**
- **Firmware image**

## Connections

- MCU device → BL2 entry: starts
- BL2 entry → Boot loader: delegates boot
- Boot loader → Security counters: updates counter (evidence: `boot/bootutil/src/loader.c`)
- Security counters → NV counter API: uses counter API (evidence: `bl2/src/security_cnt.c`)
- Flash mapping → Flash driver: uses driver (evidence: `bl2/src/flash_map.c`)
- Shared boot data → Image format: reads image metadata (evidence: `bl2/src/shared_data.c`)
- BL2 entry → Platform handoff: initializes platform (evidence: `bl2/ext/mcuboot/bl2_main.c`)
- Firmware image → imgtool CLI: provides image
- imgtool CLI → Image builder: creates image (evidence: `scripts/imgtool/main.py`)
- imgtool CLI → Key operations: uses keys (evidence: `scripts/imgtool/main.py`)
- imgtool CLI → Image inspection: dispatches inspect (evidence: `scripts/imgtool/main.py`)
