Bootloader

Makefile

@@ -31,6 +31,36 @@ CLANG_INPUTS := $(filter-out $(IGNORED_CLANG_INPUTS), $(CLANG_INPUTS))
 MAKEFILE_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
 BEAR_ENABLE ?= 1
 
+# Firmware type selects the default memory map and flashing behavior.
+#   firmware   Standalone image at 0x08000000. This is the default.
+#   app        App image linked after the resident bootloader.
+#   bootloader Resident bootloader image at 0x08000000.
+ifeq ($(origin FIRMWARE_TYPE), undefined)
+ifeq ($(origin FIRMWARE_ROLE), undefined)
+FIRMWARE_TYPE := firmware
+else
+FIRMWARE_TYPE := $(FIRMWARE_ROLE)
+endif
+endif
+
+ifeq ($(filter $(FIRMWARE_TYPE),firmware app bootloader),)
+$(error FIRMWARE_TYPE must be one of: firmware, app, bootloader)
+endif
+
+# Keep legacy FIRMWARE_ROLE invocations working internally and for child makes.
+FIRMWARE_ROLE := $(FIRMWARE_TYPE)
+
+ifeq ($(origin BOOTLOADER_SIZE_KB), undefined)
+ifeq ($(FIRMWARE_TYPE),firmware)
+BOOTLOADER_SIZE_KB := 0
+else
+BOOTLOADER_SIZE_KB := 64
+endif
+endif
+
+FLASH_BASE ?= 0x08000000
+BOOTLOADER_APP_BASE ?= $(shell python3 -c 'base=int("$(FLASH_BASE)", 0); size=int("$(BOOTLOADER_SIZE_KB)"); print("0x%08x" % (base + size * 1024))')
+
 ######################################
 # target
 ######################################
@@ -47,27 +77,9 @@ SERIES_GENERIC_CAP = STM32$(SERIES_CAP)xx
 SERIES_LINE = stm32$(SERIES)$(LINE)
 SERIES_LINE_CAP = STM32$(SERIES_CAP)$(LINE)
 
-# Generate a list of STM32 variant patterns:
-# 1. Remove the '.h' extension from filenames.
-# 2. Replace 'x' with '.' for regex matching.
-MCU_MATCHES = $(shell ls stm/$(SERIES_GENERIC)/CMSIS/Device/ST/$(SERIES_GENERIC_CAP)/Include \
-                | sed 's/\.h//g; s/x/./g')
-
-# Find the generic STM32 series variant:
-# 1. Iterate over MCU_MATCHES.
-# 2. Check if the entry is exactly 11 characters long.
-# 3. Match it against the pattern 'stm32$(SERIES_LINE)$(EXTRA_CUT)'.
-# 4. Replace '.' with 'x' in the matched entry.
-# 5. Break on the first valid match.
-SERIES_LINE_GENERIC = $(shell \
-    for match in $(MCU_MATCHES); do \
-        if [ $${#match} -eq 11 ] && echo "stm32$(SERIES_LINE)$(EXTRA_CUT)" | grep -qE "$$match"; then \
-            echo "$${match//./x}"; \
-            break; \
-        fi; \
-    done)
-
-SERIES_LINE_GENERIC_CAP = $(shell echo $(SERIES_LINE_GENERIC) | sed 's/[^x]/\U&/g')
+SERIES_LINE_GENERIC = $(SERIES_LINE)xx
+
+SERIES_LINE_GENERIC_CAP = $(shell python3 -c 's="$(SERIES_LINE_GENERIC)"; print(s[:-2].upper() + s[-2:])')
 
 ifeq ($(strip $(SERIES_LINE_GENERIC)),)
 $(error SERIES_LINE_GENERIC is not found in stm/$(SERIES_GENERIC)/CMSIS/Device/ST/$(SERIES_GENERIC_CAP)/Include. Please check the target configuration.)
@@ -96,6 +108,17 @@ VERBOSE ?= 0
 #######################################
 # Build path
 BUILD_DIR = $(PROJECT_BUILD_DIR)
+ORIG_LDSCRIPT = stm/$(SERIES_GENERIC)/$(SERIES_LINE)/$(SERIES_LINE_CAP)$(EXTRA_CAP)x_FLASH.ld
+GENERATED_LDSCRIPT = $(BUILD_DIR)/$(TARGET)_$(FIRMWARE_ROLE).ld
+FLASH_SIZE_KB ?= $(shell python3 -c 'import pathlib,re,sys; ld=pathlib.Path("$(ORIG_LDSCRIPT)").read_text(); m=re.search(r"FLASH\s*\(rx\)\s*:\s*ORIGIN\s*=\s*0x[0-9a-fA-F]+,\s*LENGTH\s*=\s*([0-9]+)K", ld); sys.exit(1) if m is None else print(m.group(1))')
+BOOTLOADER_APP_MAX_SIZE ?= $(shell python3 -c 'flash=int("$(FLASH_SIZE_KB)"); boot=int("$(BOOTLOADER_SIZE_KB)"); print((flash - boot) * 1024)')
+
+ifneq ($(filter $(FIRMWARE_TYPE),app bootloader),)
+ifeq ($(shell python3 -c 'print(int("$(BOOTLOADER_SIZE_KB)") < int("$(FLASH_SIZE_KB)"))'),False)
+$(error BOOTLOADER_SIZE_KB ($(BOOTLOADER_SIZE_KB)) must be smaller than target flash size ($(FLASH_SIZE_KB) KB))
+endif
+endif
+
 # FreeRTOS path
 FREERTOS_PATH := middleware/FreeRTOS-Kernel
 FATFS_PATH := middleware/FatFs
@@ -104,19 +127,33 @@ FATFS_PATH := middleware/FatFs
 # source
 ######################################
 # C sources
-C_SOURCES =  \
-$(PROJECT_C_SOURCES) \
+COMMON_STM_SOURCES = \
 $(filter-out %template.c, $(wildcard stm/$(SERIES_GENERIC)/$(SERIES_GENERIC_CAP)_HAL_Driver/Src/*.c)) \
 stm/$(SERIES_GENERIC)/system_$(SERIES_GENERIC).c \
 stm/$(SERIES_GENERIC)/$(SERIES_GENERIC)_hal_init.c \
-stm/$(SERIES_GENERIC)/$(SERIES_GENERIC)_hal_timebase_tim.c \
+stm/$(SERIES_GENERIC)/$(SERIES_GENERIC)_hal_timebase_tim.c
+
+APP_ROLE_SOURCES = \
+$(PROJECT_C_SOURCES) \
 $(wildcard $(FREERTOS_PATH)/*.c) \
 $(FREERTOS_PATH)/portable/GCC/ARM_CM4F/port.c \
 $(wildcard common/Src/*.c) \
 $(wildcard driver/Src/*.c) \
 $(wildcard $(FATFS_PATH)/Src/*.c) \
 $(filter-out $(addprefix bsp/Src/,$(addsuffix .c,$(BSP_DISABLE))),$(wildcard bsp/Src/*.c))
 
+BOOTLOADER_ROLE_SOURCES = \
+$(wildcard bootloader/Src/*.c) \
+common/Src/hardfault.c \
+common/Src/uart_bootloader.c \
+common/Src/stubs.c
+
+ifeq ($(FIRMWARE_TYPE),bootloader)
+C_SOURCES = $(BOOTLOADER_ROLE_SOURCES) $(COMMON_STM_SOURCES)
+else
+C_SOURCES = $(APP_ROLE_SOURCES) $(COMMON_STM_SOURCES)
+endif
+
 
 # ASM sources
 ASM_SOURCES =  \
@@ -171,6 +208,35 @@ USE_HAL_DRIVER \
 $(SERIES_LINE_GENERIC_CAP) \
 $(SERIES_GENERIC_CAP)
 
+ifeq ($(FIRMWARE_TYPE),bootloader)
+C_DEFS += FIRMWARE_ROLE_BOOTLOADER
+endif
+
+ifeq ($(FIRMWARE_TYPE),firmware)
+C_DEFS += FIRMWARE_TYPE_FIRMWARE
+else ifeq ($(FIRMWARE_TYPE),app)
+C_DEFS += FIRMWARE_TYPE_APP
+else ifeq ($(FIRMWARE_TYPE),bootloader)
+C_DEFS += FIRMWARE_TYPE_BOOTLOADER
+endif
+
+ifneq ($(filter $(FIRMWARE_TYPE),app bootloader),)
+C_DEFS += BOOTLOADER_APP_BASE=$(BOOTLOADER_APP_BASE)
+C_DEFS += BOOTLOADER_APP_MAX_SIZE=$(BOOTLOADER_APP_MAX_SIZE)
+endif
+
+ifeq ($(FIRMWARE_TYPE),app)
+ifneq ($(BOOTLOADER_SIZE_KB),0)
+C_DEFS += FIRMWARE_USES_BOOTLOADER
+endif
+endif
+
+ifeq ($(FIRMWARE_TYPE),app)
+ifeq ($(BOOTLOADER_SIZE_KB),0)
+$(error FIRMWARE_TYPE=app requires BOOTLOADER_SIZE_KB to be nonzero)
+endif
+endif
+
 C_DEFS := $(addprefix -D,$(C_DEFS))
 
 # AS includes
@@ -190,6 +256,10 @@ driver/Inc \
 bsp/Inc \
 middleware
 
+ifneq ($(filter $(FIRMWARE_TYPE),bootloader),)
+C_INCLUDES += bootloader/Inc
+endif
+
 C_INCLUDES := $(addprefix -I,$(C_INCLUDES))
 
 # compile gcc flags
@@ -208,7 +278,11 @@ CFLAGS += -MMD -MP -MF"$(@:%.o=%.d)"
 # LDFLAGS
 #######################################
 # link script
-LDSCRIPT = stm/$(SERIES_GENERIC)/$(SERIES_LINE)/$(SERIES_LINE_CAP)$(EXTRA_CAP)x_FLASH.ld
+LDSCRIPT = $(ORIG_LDSCRIPT)
+
+ifeq ($(FIRMWARE_TYPE),app)
+LDSCRIPT = $(GENERATED_LDSCRIPT)
+endif
 
 # libraries
 LIBS = 
@@ -274,7 +348,7 @@ else
 	@echo "AS $< -> $@"
 endif
 
-$(BUILD_DIR)/$(TARGET).elf: $(OBJECTS) Makefile
+$(BUILD_DIR)/$(TARGET).elf: $(OBJECTS) Makefile $(LDSCRIPT)
 	@if ls $(BUILD_DIR)/*.elf 1> /dev/null 2>&1; then \
 	rm -rf $(BUILD_DIR)/stm*.elf; \
 	fi
@@ -290,6 +364,7 @@ else
 	@$(CC) $(OBJECTS) $(LDFLAGS) -o $@
 	@echo "LD $@"
 endif
+	@echo "FIRMWARE_TYPE=$(FIRMWARE_TYPE) BOOTLOADER_SIZE_KB=$(BOOTLOADER_SIZE_KB) BOOTLOADER_APP_BASE=$(BOOTLOADER_APP_BASE) FLASH_ADDRESS=$(FLASH_ADDRESS)"
 	@$(SZ) $@
 	@echo "Finished compiling. Jolly good!"
 
@@ -320,6 +395,10 @@ endif
 $(BUILD_DIR):
 	mkdir -p $@		
 
+$(GENERATED_LDSCRIPT): $(ORIG_LDSCRIPT) Makefile | $(BUILD_DIR)
+	@python3 -c 'import pathlib,re,sys; ld_path=pathlib.Path("$(ORIG_LDSCRIPT)"); ld=ld_path.read_text(); size_kb=int("$(BOOTLOADER_SIZE_KB)"); flash_kb=int("$(FLASH_SIZE_KB)"); flash_origin=int("$(FLASH_BASE)", 0) + size_kb * 1024; flash_length_kb=flash_kb - size_kb; pattern=r"FLASH\s*\(rx\)\s*:\s*ORIGIN\s*=\s*0x[0-9a-fA-F]+,\s*LENGTH\s*=\s*[0-9]+K"; repl="FLASH (rx)      : ORIGIN = 0x%08x, LENGTH = %dK" % (flash_origin, flash_length_kb); ld, count=re.subn(pattern, repl, ld, count=1); sys.exit("Could not find FLASH region in %s" % ld_path) if count != 1 else pathlib.Path("$(GENERATED_LDSCRIPT)").write_text(ld)'
+	@echo "LD_SCRIPT $(ORIG_LDSCRIPT) -> $(GENERATED_LDSCRIPT) ($(FIRMWARE_TYPE), FLASH=$(BOOTLOADER_APP_BASE), LENGTH=$$(( $(FLASH_SIZE_KB)-$(BOOTLOADER_SIZE_KB) ))K)"
+
 #######################################
 # clean up
 #######################################
@@ -330,17 +409,31 @@ clean:
 #######################################
 # flash
 #######################################
-FLASH_ADDRESS ?= 0x8000000
-FLASH_FILE = $(shell find $(BUILD_DIR) -name 'stm*.bin' -exec basename {} \;)
+ifeq ($(FIRMWARE_TYPE),app)
+FLASH_ADDRESS ?= $(BOOTLOADER_APP_BASE)
+else
+FLASH_ADDRESS ?= $(FLASH_BASE)
+endif
+
+FLASH_FILE = $(notdir $(firstword $(wildcard $(BUILD_DIR)/stm*.bin)))
 
 .PHONY: flash
 flash:
 	@echo "🔦 Flashing $(FLASH_FILE) to $(FLASH_ADDRESS)"
 	st-flash write $(BUILD_DIR)/$(FLASH_FILE) $(FLASH_ADDRESS)
 
+# Optional extra args for uart_bootloader_flash.py (e.g. --enter, --boot). Parent makefiles may set this.
+UART_BOOTLOADER_FLASH_FLAGS ?=
+
 .PHONY: flash-uart
 flash-uart:
+ifeq ($(FIRMWARE_TYPE),bootloader)
+	./scripts/flash_bootloader.py --bin $(BUILD_DIR)/$(FLASH_FILE) --address $(FLASH_ADDRESS)
+else ifeq ($(FIRMWARE_TYPE),app)
+	./scripts/uart_bootloader_flash.py $(UART_BOOTLOADER_FLASH_FLAGS) --bin $(BUILD_DIR)/$(FLASH_FILE) --address $(FLASH_ADDRESS)
+else
 	./flash-uart.sh $(BUILD_DIR)/$(FLASH_FILE) $(FLASH_ADDRESS)
+endif
 
 #######################################
 # format
@@ -363,11 +456,17 @@ help:
 	@echo "Available targets:"
 	@echo "  all          - Build the project."
 	@echo "  clean        - Remove build artifacts."
-	@echo "  flash        - Flash the target device."
+	@echo "  flash        - Flash with ST-Link at the default address for FIRMWARE_TYPE."
+	@echo "  flash-uart   - Flash over UART using the default workflow for FIRMWARE_TYPE."
 	@echo "  tidy         - Run clang-tidy."
 	@echo "  tidy-fix     - Run clang-tidy with fixes."
 	@echo "  format       - Run clang-format."
 	@echo "  format-fix   - Run clang-format and apply fixes."
+	@echo ""
+	@echo "Firmware types:"
+	@echo "  FIRMWARE_TYPE=firmware   Standalone image at 0x08000000 (default)."
+	@echo "  FIRMWARE_TYPE=bootloader Bootloader image at 0x08000000."
+	@echo "  FIRMWARE_TYPE=app        App linked after bootloader."
 
 
 #######################################

bootloader/Inc/bootloader_board.h

@@ -0,0 +1,32 @@
+#ifndef BOOTLOADER_BOARD_H_
+#define BOOTLOADER_BOARD_H_
+
+#include "bootloader_hal.h"
+
+#if defined(STM32L432xx)
+#define BOOTLOADER_LED_PIN GPIO_PIN_3
+#define BOOTLOADER_LED_PORT GPIOB
+#elif defined(STM32L431xx)
+#define BOOTLOADER_LED_PIN GPIO_PIN_11
+#define BOOTLOADER_LED_PORT GPIOB
+#elif defined(STM32G473xx)
+#define BOOTLOADER_LED_PIN GPIO_PIN_3
+#define BOOTLOADER_LED_PORT GPIOC
+#else
+#define BOOTLOADER_LED_PIN GPIO_PIN_5
+#define BOOTLOADER_LED_PORT GPIOA
+#endif
+
+static inline void bootloader_board_enable_led_port_clock(void) {
+    if (BOOTLOADER_LED_PORT == GPIOA) {
+        __HAL_RCC_GPIOA_CLK_ENABLE();
+    } else if (BOOTLOADER_LED_PORT == GPIOB) {
+        __HAL_RCC_GPIOB_CLK_ENABLE();
+    } else if (BOOTLOADER_LED_PORT == GPIOC) {
+        __HAL_RCC_GPIOC_CLK_ENABLE();
+    } else if (BOOTLOADER_LED_PORT == GPIOD) {
+        __HAL_RCC_GPIOD_CLK_ENABLE();
+    }
+}
+
+#endif /* BOOTLOADER_BOARD_H_ */

bootloader/Inc/bootloader_config.h

@@ -0,0 +1,50 @@
+#ifndef BOOTLOADER_CONFIG_H_
+#define BOOTLOADER_CONFIG_H_
+
+#include "bootloader_hal.h"
+
+#ifndef BOOTLOADER_APP_BASE
+#define BOOTLOADER_APP_BASE (0x08010000UL)
+#endif
+
+#ifndef BOOTLOADER_APP_MAX_SIZE
+#define BOOTLOADER_APP_MAX_SIZE (448UL * 1024UL)
+#endif
+
+#ifndef BOOTLOADER_UART_BAUD
+#define BOOTLOADER_UART_BAUD (115200U)
+#endif
+
+#ifndef BOOTLOADER_UART_INSTANCE
+/* PSOM L431: same console USART as test UART apps (husart1 / PA9, PA10). */
+#if defined(STM32L431xx) && defined(USART1)
+#define BOOTLOADER_UART_INSTANCE USART1
+#elif defined(USART3)
+#define BOOTLOADER_UART_INSTANCE USART3
+#elif defined(USART2)
+#define BOOTLOADER_UART_INSTANCE USART2
+#elif defined(USART1)
+#define BOOTLOADER_UART_INSTANCE USART1
+#else
+#error "No supported UART instance available for bootloader."
+#endif
+#endif
+
+#ifndef BOOTLOADER_WRITE_CHUNK_MAX
+#define BOOTLOADER_WRITE_CHUNK_MAX (128U)
+#endif
+
+#ifndef BOOTLOADER_HANDSHAKE_TIMEOUT_MS
+#define BOOTLOADER_HANDSHAKE_TIMEOUT_MS (0U)
+#endif
+
+/* 0 = skip UART listen and boot app immediately when valid (see bootloader_main). */
+#ifndef BOOTLOADER_APP_STARTUP_WAIT_MS
+#define BOOTLOADER_APP_STARTUP_WAIT_MS (0U)
+#endif
+
+#ifndef BOOTLOADER_POST_FLASH_BOOT_DELAY_MS
+#define BOOTLOADER_POST_FLASH_BOOT_DELAY_MS (2000U)
+#endif
+
+#endif

bootloader/Inc/bootloader_hal.h

@@ -0,0 +1,14 @@
+#ifndef BOOTLOADER_HAL_H_
+#define BOOTLOADER_HAL_H_
+
+#if defined(STM32F4xx)
+#include "stm32f4xx_hal.h"
+#elif defined(STM32L4xx)
+#include "stm32l4xx_hal.h"
+#elif defined(STM32G4xx)
+#include "stm32g4xx_hal.h"
+#else
+#error "Unsupported STM32 series for bootloader."
+#endif
+
+#endif

bootloader/Inc/bootloader_indicator.h

@@ -0,0 +1,17 @@
+#ifndef BOOTLOADER_INDICATOR_H_
+#define BOOTLOADER_INDICATOR_H_
+
+#include <stdint.h>
+
+typedef enum {
+    BOOTLOADER_INDICATOR_NO_APP = 0,
+    BOOTLOADER_INDICATOR_APP_PRESENT,
+    BOOTLOADER_INDICATOR_CONNECTED,
+    BOOTLOADER_INDICATOR_ERROR,
+} bootloader_indicator_mode_t;
+
+void bootloader_indicator_init(void);
+void bootloader_indicator_set_mode(bootloader_indicator_mode_t mode);
+void bootloader_indicator_update(uint32_t tick_ms);
+
+#endif

bootloader/Inc/bootloader_runtime.h

@@ -0,0 +1,18 @@
+#ifndef BOOTLOADER_RUNTIME_H_
+#define BOOTLOADER_RUNTIME_H_
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+void bootloader_runtime_init(void);
+bool bootloader_runtime_wait_for_handshake(uint32_t timeout_ms);
+bool bootloader_runtime_poll_sync(uint32_t timeout_ms);
+bool bootloader_runtime_send_bytes(const uint8_t *data, uint16_t len);
+bool bootloader_runtime_read_bytes(uint8_t *data, uint16_t len, uint32_t timeout_ms);
+bool bootloader_runtime_erase_app(void);
+bool bootloader_runtime_write_app(uint32_t app_offset, const uint8_t *data, size_t len);
+bool bootloader_runtime_is_app_valid(void);
+void bootloader_runtime_jump_to_app(void);
+
+#endif