CMSIS Part 10: Portable Firmware — Multi-Vendor CMSIS Projects

HAL vs CMSIS Trade-offs

There is no universally correct answer to "should I use a vendor HAL or go CMSIS-only?" The right choice depends on your project's portability requirements, schedule constraints, performance budget, and maintainability needs. Understanding the trade-offs lets you make an informed decision rather than defaulting to whichever approach you learned first.

Portability Approach Comparison

Designing a HAL Interface in C

A C hardware abstraction layer uses function pointers to achieve runtime polymorphism — the same technique used internally by CMSIS-Driver. The interface is a struct of function pointers; each platform provides a static instance that fills in the pointers with its platform-specific implementations. The application holds a pointer to the interface struct and calls through it without knowing which implementation is active.

/**
 * Portable GPIO HAL — function-pointer-based interface in C.
 * The application uses only hal_gpio_t; platform code fills the pointers.
 *
 * header: bsp/hal_gpio.h
 */
#ifndef HAL_GPIO_H
#define HAL_GPIO_H

#include <stdint.h>
#include <stdbool.h>

/** Opaque pin handle — platform defines what this actually is */
typedef struct hal_gpio_pin_t hal_gpio_pin_t;

/** GPIO direction */
typedef enum {
    HAL_GPIO_INPUT  = 0,
    HAL_GPIO_OUTPUT = 1
} hal_gpio_dir_t;

/** GPIO HAL interface — a vtable of function pointers */
typedef struct {
    /** Initialise a GPIO pin */
    void (*init)(hal_gpio_pin_t *pin, hal_gpio_dir_t dir);
    /** Set the output level (true = high, false = low) */
    void (*set)(hal_gpio_pin_t *pin, bool level);
    /** Toggle the output level */
    void (*toggle)(hal_gpio_pin_t *pin);
    /** Read the current input level */
    bool (*read)(const hal_gpio_pin_t *pin);
} hal_gpio_t;

#endif /* HAL_GPIO_H */

/* ─────────────────────────────────────────────────────────────────────────── */

/**
 * STM32F4 implementation of hal_gpio_t
 * file: bsp/stm32f4/bsp_gpio_stm32f4.c
 */
#include "hal_gpio.h"
#include "stm32f4xx.h"   /* CMSIS device header */

/* Concrete pin definition for STM32F4 */
typedef struct hal_gpio_pin_t {
    GPIO_TypeDef *port;
    uint32_t      pin_mask;   /* e.g. GPIO_BSRR_BS5 for PA5 */
    uint32_t      pin_pos;    /* bit position                 */
} hal_gpio_pin_t;

static void stm32_gpio_init(hal_gpio_pin_t *pin, hal_gpio_dir_t dir) {
    /* Enable AHB1 clock for the GPIO port — port address encodes the index */
    uint32_t port_idx = ((uint32_t)pin->port - GPIOA_BASE) / 0x400UL;
    RCC->AHB1ENR |= (1UL << port_idx);
    __DSB();
    /* Set MODER bits: 0b01 = output, 0b00 = input */
    pin->port->MODER &= ~(0x3UL << (pin->pin_pos * 2U));
    if (dir == HAL_GPIO_OUTPUT) {
        pin->port->MODER |= (0x1UL << (pin->pin_pos * 2U));
    }
}

static void stm32_gpio_set(hal_gpio_pin_t *pin, bool level) {
    /* BSRR: lower 16 bits = set, upper 16 bits = reset */
    if (level) {
        pin->port->BSRR = (1UL << pin->pin_pos);          /* Set   */
    } else {
        pin->port->BSRR = (1UL << (pin->pin_pos + 16U));  /* Reset */
    }
}

static void stm32_gpio_toggle(hal_gpio_pin_t *pin) {
    pin->port->ODR ^= (1UL << pin->pin_pos);
}

static bool stm32_gpio_read(const hal_gpio_pin_t *pin) {
    return (pin->port->IDR & (1UL << pin->pin_pos)) != 0U;
}

/* Static vtable instance — the BSP exports this */
const hal_gpio_t HAL_GPIO_STM32F4 = {
    .init   = stm32_gpio_init,
    .set    = stm32_gpio_set,
    .toggle = stm32_gpio_toggle,
    .read   = stm32_gpio_read,
};

/* ─────────────────────────────────────────────────────────────────────────── */

/**
 * Application code — zero vendor dependency.
 * Works on any platform that provides a hal_gpio_t implementation.
 * file: app/main.c
 */
#include "hal_gpio.h"
#include "cmsis_os2.h"  /* CMSIS-RTOS2 — also portable */

/* Forward declarations — defined in the active BSP */
extern const hal_gpio_t     HAL_GPIO_IMPL;
extern       hal_gpio_pin_t BSP_LED_STATUS_PIN;

void led_blink_task(void *arg) {
    (void)arg;
    HAL_GPIO_IMPL.init(&BSP_LED_STATUS_PIN, HAL_GPIO_OUTPUT);
    for (;;) {
        HAL_GPIO_IMPL.toggle(&BSP_LED_STATUS_PIN);
        osDelay(500U);  /* 500 ms — CMSIS-RTOS2 API, also portable */
    }
}

Cross-Platform Firmware Patterns

The key to successful cross-platform firmware is identifying exactly which lines of code change between targets and isolating them behind a stable interface. In practice, the delta between MCU families affects only four areas: the startup file and linker script (handled by CMSIS-Pack); the clock initialisation sequence; the peripheral register initialisation; and the pin-to-peripheral mapping. Everything above the BSP layer — RTOS task logic, communication protocols, application state machines — is genuinely portable.

Abstract GPIO Toggle on Two MCU Families

/**
 * Same application code running LED blink on STM32F4 AND NXP LPC55S69
 * via the abstract BSP interface. The only file that changes between
 * targets is bsp_impl.c (linked differently per board).
 *
 * BSP interface header: bsp/bsp_led.h  (shared, board-independent)
 */

/* ── bsp/bsp_led.h ──────────────────────────────────────────── */
#ifndef BSP_LED_H
#define BSP_LED_H
#include <stdbool.h>

typedef enum { LED_GREEN = 0, LED_RED, LED_BLUE, BSP_LED_COUNT } bsp_led_id_t;

void BSP_LED_Init(void);
void BSP_LED_Set(bsp_led_id_t led, bool on);
void BSP_LED_Toggle(bsp_led_id_t led);
#endif

/* ── app/main.c — IDENTICAL for both targets ────────────────── */
#include "bsp_led.h"
#include "cmsis_os2.h"

void app_init(void) { BSP_LED_Init(); }

void app_led_task(void *arg) {
    (void)arg;
    for (;;) {
        BSP_LED_Toggle(LED_GREEN);
        osDelay(500U);
        BSP_LED_Toggle(LED_RED);
        osDelay(250U);
    }
}

/* ── bsp/stm32f4/bsp_led_stm32f4.c — STM32F4 implementation ─── */
#ifdef BOARD_STM32F407_DISCO
#include "bsp_led.h"
#include "stm32f407xx.h"

/* PA5 = Green LED, PD14 = Red LED, PD15 = Blue LED on Discovery */
static const struct { GPIO_TypeDef *port; uint8_t pin; } leds[BSP_LED_COUNT] = {
    [LED_GREEN] = { GPIOA, 5  },
    [LED_RED]   = { GPIOD, 14 },
    [LED_BLUE]  = { GPIOD, 15 },
};

void BSP_LED_Init(void) {
    RCC->AHB1ENR |= RCC_AHB1ENR_GPIOAEN | RCC_AHB1ENR_GPIODEN;
    __DSB();
    for (int i = 0; i < BSP_LED_COUNT; i++) {
        leds[i].port->MODER &= ~(3UL << (leds[i].pin * 2U));
        leds[i].port->MODER |=  (1UL << (leds[i].pin * 2U));  /* Output */
    }
}
void BSP_LED_Set(bsp_led_id_t led, bool on) {
    if (on) leds[led].port->BSRR = (1UL << leds[led].pin);
    else    leds[led].port->BSRR = (1UL << (leds[led].pin + 16U));
}
void BSP_LED_Toggle(bsp_led_id_t led) {
    leds[led].port->ODR ^= (1UL << leds[led].pin);
}
#endif /* BOARD_STM32F407_DISCO */

/* ── bsp/lpc55s69/bsp_led_lpc55s69.c — NXP LPC55 implementation */
#ifdef BOARD_NXP_LPC55S69_EVK
#include "bsp_led.h"
#include "LPC55S69_cm33_core0.h"  /* NXP CMSIS device header */

/* LPC55S69-EVK: PIO1_4 = Blue, PIO1_6 = Red, PIO1_7 = Green */
static const struct { uint8_t port; uint8_t pin; } leds[BSP_LED_COUNT] = {
    [LED_GREEN] = { 1, 7 },
    [LED_RED]   = { 1, 6 },
    [LED_BLUE]  = { 1, 4 },
};

void BSP_LED_Init(void) {
    /* Enable IOCON and GPIO clocks via SYSCON — NXP-specific */
    SYSCON->AHBCLKCTRL0 |= SYSCON_AHBCLKCTRL0_IOCON_MASK
                         |  SYSCON_AHBCLKCTRL0_GPIO1_MASK;
    for (int i = 0; i < BSP_LED_COUNT; i++) {
        GPIO->DIR[leds[i].port] |= (1UL << leds[i].pin);  /* Output */
        GPIO->SET[leds[i].port]  = (1UL << leds[i].pin);  /* LED off (active low) */
    }
}
void BSP_LED_Set(bsp_led_id_t led, bool on) {
    /* LPC55 EVK LEDs are active-low */
    if (on) GPIO->CLR[leds[led].port] = (1UL << leds[led].pin);
    else    GPIO->SET[leds[led].port] = (1UL << leds[led].pin);
}
void BSP_LED_Toggle(bsp_led_id_t led) {
    GPIO->NOT[leds[led].port] = (1UL << leds[led].pin);
}
#endif /* BOARD_NXP_LPC55S69_EVK */

MCU Family Porting Delta

Conditional Compilation

When the BSP layer cannot fully isolate a platform dependency — for example, when a performance-critical path needs direct register access on each platform — conditional compilation with preprocessor defines provides a clean escape hatch. The key discipline is: keep conditionals in the BSP layer, never in the application layer.

#ifdef Board Patterns

/**
 * BSP clock initialisation — conditional compilation pattern.
 * Board defines are passed via CMake target_compile_definitions.
 * Never use these #ifdefs in application code.
 *
 * file: bsp/bsp_clocks.c
 */

#include "bsp_clocks.h"

#if defined(BOARD_STM32F407_DISCO)
    #include "stm32f407xx.h"
    #include "system_stm32f4xx.h"

    void BSP_Clock_Init(void) {
        /* STM32F407 Discovery: configure PLL for 168 MHz from 8 MHz HSE */
        /* Use CMSIS SystemInit() as starting point, then fine-tune */
        SystemInit();
        /* Enable HSE */
        RCC->CR |= RCC_CR_HSEON;
        while (!(RCC->CR & RCC_CR_HSERDY)) {}
        /* Configure PLL: VCO = 8 MHz * (336/8) = 336 MHz; SYSCLK = 336/2 = 168 MHz */
        RCC->PLLCFGR = (8U  << RCC_PLLCFGR_PLLM_Pos)   /* /8  */
                     | (336U << RCC_PLLCFGR_PLLN_Pos)   /* x336 */
                     | (0U  << RCC_PLLCFGR_PLLP_Pos)    /* /2   */
                     | RCC_PLLCFGR_PLLSRC_HSE;
        RCC->CR |= RCC_CR_PLLON;
        while (!(RCC->CR & RCC_CR_PLLRDY)) {}
        /* Set flash latency for 168 MHz (5 wait states) */
        FLASH->ACR = FLASH_ACR_LATENCY_5WS | FLASH_ACR_PRFTEN | FLASH_ACR_DCEN | FLASH_ACR_ICEN;
        /* Switch to PLL */
        RCC->CFGR |= RCC_CFGR_SW_PLL;
        while ((RCC->CFGR & RCC_CFGR_SWS_Msk) != RCC_CFGR_SWS_PLL) {}
        SystemCoreClock = 168000000U;
    }

#elif defined(BOARD_NXP_LPC55S69_EVK)
    #include "LPC55S69_cm33_core0.h"

    void BSP_Clock_Init(void) {
        /* LPC55S69 EVK: switch to FRO 96 MHz (internal oscillator) */
        /* SYSCON MAINCLKSELA: select FRO_HF (96 MHz) */
        SYSCON->MAINCLKSELA = 3U;   /* FRO 96 MHz output */
        SYSCON->MAINCLKSELB = 0U;   /* MAINCLKSELA directly */
        SystemCoreClock = 96000000U;
    }

#elif defined(BOARD_NRF52840_DK)
    #include "nrf52840.h"

    void BSP_Clock_Init(void) {
        /* nRF52840: start HFXO (external 32 MHz crystal) */
        NRF_CLOCK->EVENTS_HFCLKSTARTED = 0U;
        NRF_CLOCK->TASKS_HFCLKSTART    = 1U;
        while (!NRF_CLOCK->EVENTS_HFCLKSTARTED) {}
        SystemCoreClock = 64000000U;  /* CPU runs at 64 MHz (PLL from 32 MHz HFXO) */
    }

#else
    #error "Unknown board — define BOARD_STM32F407_DISCO, BOARD_NXP_LPC55S69_EVK, or BOARD_NRF52840_DK"
#endif

CMake Board Selection via -DBOARD=

# CMakeLists.txt — board-aware firmware build
cmake_minimum_required(VERSION 3.21)
project(portable_firmware C ASM)

# ── Board selection ─────────────────────────────────────────────────────────
# Usage: cmake -DBOARD=stm32f407_disco ..
#        cmake -DBOARD=lpc55s69_evk ..
#        cmake -DBOARD=nrf52840_dk ..

if(NOT DEFINED BOARD)
    message(FATAL_ERROR "BOARD is not set. Use -DBOARD=")
endif()

# ── Per-board configuration ─────────────────────────────────────────────────
if(BOARD STREQUAL "stm32f407_disco")
    set(CPU_FLAGS "-mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard")
    set(LINKER_SCRIPT "${CMAKE_SOURCE_DIR}/bsp/stm32f4/STM32F407VGTx_FLASH.ld")
    set(BSP_SOURCES
        bsp/stm32f4/bsp_clocks.c
        bsp/stm32f4/bsp_led_stm32f4.c
        bsp/stm32f4/bsp_uart_stm32f4.c
    )
    set(BSP_DEFINES BOARD_STM32F407_DISCO STM32F407xx)
    set(BSP_INCLUDES bsp/stm32f4 ${CMSIS_PACK_ROOT}/Keil/STM32F4xx_DFP/2.17.1/Device/Include)

elseif(BOARD STREQUAL "lpc55s69_evk")
    set(CPU_FLAGS "-mcpu=cortex-m33 -mthumb -mfpu=fpv5-sp-d16 -mfloat-abi=hard")
    set(LINKER_SCRIPT "${CMAKE_SOURCE_DIR}/bsp/lpc55s69/LPC55S69_flash.ld")
    set(BSP_SOURCES
        bsp/lpc55s69/bsp_clocks.c
        bsp/lpc55s69/bsp_led_lpc55s69.c
        bsp/lpc55s69/bsp_uart_lpc55s69.c
    )
    set(BSP_DEFINES BOARD_NXP_LPC55S69_EVK CPU_LPC55S69JBD100)
    set(BSP_INCLUDES bsp/lpc55s69 ${CMSIS_PACK_ROOT}/NXP/LPC55S6x_DFP/18.0.0/device/include)

elseif(BOARD STREQUAL "nrf52840_dk")
    set(CPU_FLAGS "-mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard")
    set(LINKER_SCRIPT "${CMAKE_SOURCE_DIR}/bsp/nrf52840/nrf52840_xxaa.ld")
    set(BSP_SOURCES
        bsp/nrf52840/bsp_clocks.c
        bsp/nrf52840/bsp_led_nrf52840.c
        bsp/nrf52840/bsp_uart_nrf52840.c
    )
    set(BSP_DEFINES BOARD_NRF52840_DK NRF52840_XXAA)
    set(BSP_INCLUDES bsp/nrf52840 ${CMSIS_PACK_ROOT}/NordicSemiconductor/nRF_DeviceFamilyPack/8.0.0/Device/Include)
else()
    message(FATAL_ERROR "Unknown BOARD: ${BOARD}")
endif()

# ── Common sources (application + CMSIS) ────────────────────────────────────
add_executable(firmware.elf
    app/main.c
    app/app_tasks.c
    ${BSP_SOURCES}
)

target_include_directories(firmware.elf PRIVATE
    app/
    bsp/
    ${BSP_INCLUDES}
    ${CMSIS_PACK_ROOT}/ARM/CMSIS/6.1.0/CMSIS/Core/Include
)

target_compile_definitions(firmware.elf PRIVATE ${BSP_DEFINES})

separate_arguments(CPU_FLAGS_LIST NATIVE_COMMAND "${CPU_FLAGS}")
target_compile_options(firmware.elf PRIVATE
    ${CPU_FLAGS_LIST}
    -O2 -Wall -Wextra -ffunction-sections -fdata-sections
)

target_link_options(firmware.elf PRIVATE
    ${CPU_FLAGS_LIST}
    -T${LINKER_SCRIPT}
    -Wl,--gc-sections -Wl,-Map=firmware.map
)

# Build example:
# mkdir build-stm32 && cd build-stm32
# cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../arm-none-eabi.cmake -DBOARD=stm32f407_disco ..
# ninja

Reusable BSP Design

A well-designed BSP is more than a collection of platform-specific .c files. It is a structured library with a versioned public API, a clear file organisation, and a documented porting guide. When designed correctly, adding a new board variant requires only adding a new BSP directory and selecting it in CMake — the application and middleware layers remain untouched.

BSP Directory Structure

firmware/
├── app/                          # Application layer — BOARD-INDEPENDENT
│   ├── main.c                    # Entry point, RTOS init
│   ├── app_sensor.c              # Sensor acquisition logic
│   └── app_comms.c               # Communication protocol handler
├── bsp/
│   ├── bsp_gpio.h                # PUBLIC: Abstract GPIO interface
│   ├── bsp_uart.h                # PUBLIC: Abstract UART interface
│   ├── bsp_i2c.h                 # PUBLIC: Abstract I2C interface
│   ├── bsp_led.h                 # PUBLIC: Abstract LED interface
│   ├── stm32f4/                  # STM32F4 BSP implementation
│   │   ├── bsp_gpio_stm32f4.c
│   │   ├── bsp_uart_stm32f4.c
│   │   ├── bsp_clocks.c
│   │   ├── STM32F407VGTx_FLASH.ld
│   │   └── bsp_board_config.h    # Pin mappings for specific board revision
│   ├── lpc55s69/                 # NXP LPC55S69 BSP implementation
│   │   ├── bsp_gpio_lpc55s69.c
│   │   ├── bsp_uart_lpc55s69.c
│   │   ├── bsp_clocks.c
│   │   └── LPC55S69_flash.ld
│   └── nrf52840/                 # Nordic nRF52840 BSP implementation
│       ├── bsp_gpio_nrf52840.c
│       └── nrf52840_xxaa.ld
├── drivers/                      # Reusable device drivers — BOARD-INDEPENDENT
│   ├── bme280/                   # BME280 temperature/humidity sensor
│   │   ├── bme280.h
│   │   └── bme280.c              # Uses bsp_i2c.h — works on any platform
│   └── ssd1306/                  # OLED display driver
│       ├── ssd1306.h
│       └── ssd1306.c             # Uses bsp_i2c.h
└── CMakeLists.txt                # Board selection via -DBOARD=

Sensor Driver Portability via BSP I2C Abstraction

The real payoff of the BSP approach is that peripheral device drivers (sensor ICs, display controllers, wireless modules) become completely board-independent. A BME280 temperature sensor driver that depends on bsp_i2c.h will work on any board that provides a conforming I2C BSP implementation — whether that implementation uses CMSIS-Driver underneath, or a vendor HAL, or direct register access.

/**
 * Portable BME280 driver — uses bsp_i2c.h, not any vendor API.
 * file: drivers/bme280/bme280.c
 */
#include "bme280.h"
#include "bsp_i2c.h"   /* Abstract I2C: BSP_I2C_Write(), BSP_I2C_Read() */

#define BME280_ADDR     0x76U  /* Default I2C address (SDO = GND) */
#define BME280_REG_ID   0xD0U
#define BME280_REG_CTRL 0xF4U

static void bme280_write_reg(uint8_t reg, uint8_t value) {
    uint8_t buf[2] = { reg, value };
    BSP_I2C_Write(BSP_I2C_BUS0, BME280_ADDR, buf, 2U);
}

static uint8_t bme280_read_reg(uint8_t reg) {
    uint8_t val = 0U;
    BSP_I2C_Write(BSP_I2C_BUS0, BME280_ADDR, &reg, 1U);
    BSP_I2C_Read(BSP_I2C_BUS0, BME280_ADDR, &val, 1U);
    return val;
}

bool BME280_Init(void) {
    uint8_t chip_id = bme280_read_reg(BME280_REG_ID);
    if (chip_id != 0x60U) return false;  /* Not a BME280 */
    /* Force mode, osrs_t=x1, osrs_p=x1 */
    bme280_write_reg(BME280_REG_CTRL, 0x27U);
    return true;
}

Exercises

BSP Design Planner

Use this tool to document your portable firmware architecture — the primary and secondary MCU targets, abstracted peripherals, HAL layers, CMake board defines, and porting notes. Generate a Word, Excel, PDF, or PPTX document for architecture reviews, team knowledge transfer, or project proposals.

Conclusion & Next Steps

Portable firmware is not a luxury — it is a professional engineering standard that pays dividends throughout a product's lifetime. The key architectural principles from this article:

• The three-layer model (Application / BSP / Platform) creates a clean boundary: everything above BSP is board-agnostic, everything below is intentionally platform-specific. Never let silicon-specific code leak upward across this boundary.
• Function-pointer HAL interfaces in C achieve runtime portability with minimal overhead — the same mechanism CMSIS-Driver uses internally. The vtable struct pattern is the canonical C approach to interface-based design.
• CMake board variables (-DBOARD=) make platform selection explicit, reproducible, and CI/CD-friendly. Every team member and every pipeline build starts from the same clean state by specifying a single variable.
• The porting delta between Cortex-M MCU families is smaller than it appears: CMSIS provides a stable processor-level API, and the actual platform-specific code is confined to clock initialisation, GPIO model differences, and linker script memory regions.
• Sensor and middleware drivers written against the BSP interface are the ultimate test of portability: a BME280 driver that works on STM32, NXP, Nordic, and Renesas without modification demonstrates that the BSP abstraction is correctly designed.