CMSIS Part 7: CMSIS-Driver — UART, SPI & I2C Interfaces

UART (USART) Driver

The USART driver is the most commonly used CMSIS-Driver interface — almost every embedded project has at least one debug or communication UART. The key point to internalise is that Send() is non-blocking: it starts the transfer (via interrupt or DMA) and returns immediately. The actual completion is signalled by the ARM_USART_SignalEvent callback that you register during Initialize(). Your application must wait for this callback (via semaphore, event flag, or polling the GetStatus() function) before invoking the next Send().

/* ── uart_cmsis_driver.c ─────────────────────────────────────────────────
 * CMSIS-Driver USART usage: Initialize, PowerControl, Send with
 * callback, receive with ring buffer, error handling.
 * ──────────────────────────────────────────────────────────────────────── */
#include "Driver_USART.h"   /* ARM CMSIS-Driver header                 */
#include "cmsis_os2.h"      /* RTOS2 for semaphore                     */
#include 
#include 

/* Reference the driver instance exposed by the vendor BSP.
 * This is defined in the vendor's CMSIS-Driver implementation file.   */
extern ARM_DRIVER_USART Driver_USART2;
static ARM_DRIVER_USART *const pUSART = &Driver_USART2;

/* Semaphore released by TX-complete callback */
static osSemaphoreId_t g_uart_tx_sem;

/* RX ring buffer */
#define RX_BUF_SIZE 256U
static uint8_t g_rx_ring[RX_BUF_SIZE];
static volatile uint32_t g_rx_head = 0U, g_rx_tail = 0U;
static uint8_t g_rx_byte; /* single-byte DMA/interrupt receive target */

/* ── Signal event callback — called from driver ISR context ─────────── */
static void usart_callback(uint32_t event)
{
    if (event & ARM_USART_EVENT_SEND_COMPLETE) {
        /* TX done — release semaphore to unblock waiting thread */
        osSemaphoreRelease(g_uart_tx_sem);
    }
    if (event & ARM_USART_EVENT_RECEIVE_COMPLETE) {
        /* Single byte received — store in ring buffer */
        uint32_t next_head = (g_rx_head + 1U) % RX_BUF_SIZE;
        if (next_head != g_rx_tail) { /* not full */
            g_rx_ring[g_rx_head] = g_rx_byte;
            g_rx_head = next_head;
        }
        /* Re-arm receive for next byte */
        pUSART->Receive(&g_rx_byte, 1U);
    }
    if (event & ARM_USART_EVENT_RX_OVERFLOW) {
        /* RX hardware FIFO overrun — increment error counter, re-arm */
        pUSART->Receive(&g_rx_byte, 1U);
    }
}

/* ── Initialisation ──────────────────────────────────────────────────── */
int32_t uart_init(uint32_t baud_rate)
{
    int32_t status;

    g_uart_tx_sem = osSemaphoreNew(1U, 0U, NULL); /* initially unavailable */

    /* Step 1: Register callback and initialise driver hardware */
    status = pUSART->Initialize(usart_callback);
    if (status != ARM_DRIVER_OK) { return status; }

    /* Step 2: Power on the peripheral */
    status = pUSART->PowerControl(ARM_POWER_FULL);
    if (status != ARM_DRIVER_OK) { return status; }

    /* Step 3: Configure baud rate, 8N1, asynchronous UART */
    status = pUSART->Control(
        ARM_USART_MODE_ASYNCHRONOUS |
        ARM_USART_DATA_BITS_8       |
        ARM_USART_PARITY_NONE       |
        ARM_USART_STOP_BITS_1       |
        ARM_USART_FLOW_CONTROL_NONE,
        baud_rate);
    if (status != ARM_DRIVER_OK) { return status; }

    /* Step 4: Enable TX and RX */
    pUSART->Control(ARM_USART_CONTROL_TX, 1U);
    pUSART->Control(ARM_USART_CONTROL_RX, 1U);

    /* Step 5: Arm the first receive (starts DMA or interrupt) */
    pUSART->Receive(&g_rx_byte, 1U);

    return ARM_DRIVER_OK;
}

/* ── Blocking send — waits for TX-complete callback ─────────────────── */
int32_t uart_send_blocking(const uint8_t *p_data, uint32_t length,
                           uint32_t timeout_ms)
{
    int32_t status = pUSART->Send(p_data, length);
    if (status != ARM_DRIVER_OK) { return status; }

    /* Block until callback releases the semaphore */
    osStatus_t os_status = osSemaphoreAcquire(g_uart_tx_sem, timeout_ms);
    return (os_status == osOK) ? ARM_DRIVER_OK : ARM_DRIVER_ERROR_TIMEOUT;
}

SPI Driver

SPI is a full-duplex synchronous bus: every clock cycle the master shifts one bit out on MOSI and simultaneously shifts one bit in on MISO. CMSIS-Driver reflects this with a single Transfer() function that takes both a TX buffer and an RX buffer simultaneously. For write-only operations (e.g., driving an LCD), pass NULL as the RX buffer; for read-only operations (rare in practice), pass NULL as TX.

Chip-select management is deliberately not part of the CMSIS-Driver SPI specification — it is handled at the application level using GPIO. This gives you full control over CS timing, multi-device buses with shared SPI, and advanced protocols that require CS held low across multiple transfers.

/* ── spi_cmsis_driver.c ──────────────────────────────────────────────────
 * CMSIS-Driver SPI: master mode, DMA-backed Transfer, CS via GPIO.
 * Demonstrates full-duplex Transfer and blocking wrapper via semaphore.
 * ──────────────────────────────────────────────────────────────────────── */
#include "Driver_SPI.h"
#include "Driver_GPIO.h"   /* or use direct register access for CS pin */
#include "cmsis_os2.h"
#include 

extern ARM_DRIVER_SPI  Driver_SPI1;
static ARM_DRIVER_SPI *const pSPI = &Driver_SPI1;

static osSemaphoreId_t g_spi_done_sem;

/* ── SPI event callback ──────────────────────────────────────────────── */
static void spi_callback(uint32_t event)
{
    if (event & ARM_SPI_EVENT_TRANSFER_COMPLETE) {
        osSemaphoreRelease(g_spi_done_sem);
    }
    if (event & ARM_SPI_EVENT_DATA_LOST) {
        /* RX overrun or TX underrun — increment error counter */
    }
}

/* ── One-time initialisation ─────────────────────────────────────────── */
int32_t spi_init(uint32_t clock_hz)
{
    g_spi_done_sem = osSemaphoreNew(1U, 0U, NULL);

    pSPI->Initialize(spi_callback);
    pSPI->PowerControl(ARM_POWER_FULL);

    /* Configure: master, CPOL=0, CPHA=0 (Mode 0), MSB first */
    pSPI->Control(
        ARM_SPI_MODE_MASTER       |
        ARM_SPI_CPOL0_CPHA0       |   /* SPI Mode 0                   */
        ARM_SPI_MSB_LSB           |   /* MSB first                    */
        ARM_SPI_SS_MASTER_SW      |   /* CS managed by software (GPIO) */
        ARM_SPI_DATA_BITS(8),
        clock_hz);

    return ARM_DRIVER_OK;
}

/* ── Full-duplex Transfer with CS management ─────────────────────────── */
static void gpio_cs_assert(void)   { /* pull CS low via GPIO register */ }
static void gpio_cs_deassert(void) { /* pull CS high via GPIO register */ }

int32_t spi_transfer_blocking(const uint8_t *p_tx, uint8_t *p_rx,
                               uint32_t length, uint32_t timeout_ms)
{
    gpio_cs_assert();

    int32_t status = pSPI->Transfer(p_tx, p_rx, length);
    if (status != ARM_DRIVER_OK) {
        gpio_cs_deassert();
        return status;
    }

    /* Block until DMA transfer complete callback fires */
    osStatus_t os_st = osSemaphoreAcquire(g_spi_done_sem, timeout_ms);

    gpio_cs_deassert();

    return (os_st == osOK) ? ARM_DRIVER_OK : ARM_DRIVER_ERROR_TIMEOUT;
}

/* ── Read a sensor register: TX register address, RX data byte ───────── */
int32_t spi_read_register(uint8_t reg_addr, uint8_t *p_value)
{
    uint8_t tx_buf[2] = { reg_addr | 0x80U, 0x00U }; /* read flag = bit7 */
    uint8_t rx_buf[2] = { 0U, 0U };

    int32_t status = spi_transfer_blocking(tx_buf, rx_buf, 2U, 10U);
    if (status == ARM_DRIVER_OK) {
        *p_value = rx_buf[1]; /* first byte is dummy during address phase */
    }
    return status;
}

I2C Driver

I2C is a two-wire, multi-master, multi-slave bus with 7-bit (standard) or 10-bit (extended) device addressing. CMSIS-Driver separates master transmit and master receive into distinct calls: MasterTransmit() writes bytes to a slave, MasterReceive() reads bytes from a slave. For the common "write register address then read data" pattern, the two calls are combined with a repeated START condition — achieved by passing xfer_pending = true (value 1) to the first call, which suppresses the STOP condition and holds the bus, then xfer_pending = false (value 0) to the second call to release it.

/* ── i2c_cmsis_driver.c ──────────────────────────────────────────────────
 * CMSIS-Driver I2C: 7-bit and 10-bit addressing, combined format read.
 * Demonstrates MasterTransmit → MasterReceive with repeated START.
 * ──────────────────────────────────────────────────────────────────────── */
#include "Driver_I2C.h"
#include "cmsis_os2.h"
#include 

extern ARM_DRIVER_I2C Driver_I2C1;
static ARM_DRIVER_I2C *const pI2C = &Driver_I2C1;

static osSemaphoreId_t g_i2c_done_sem;

/* ── I2C event callback ──────────────────────────────────────────────── */
static void i2c_callback(uint32_t event)
{
    if (event & ARM_I2C_EVENT_TRANSFER_DONE) {
        osSemaphoreRelease(g_i2c_done_sem);
    }
    if (event & ARM_I2C_EVENT_TRANSFER_INCOMPLETE) {
        /* NACK from slave or lost arbitration — signal with error code */
        osSemaphoreRelease(g_i2c_done_sem);
    }
    if (event & ARM_I2C_EVENT_BUS_ERROR) {
        /* SDA/SCL glitch or timeout — log and reset bus */
        osSemaphoreRelease(g_i2c_done_sem);
    }
}

/* ── Initialisation ──────────────────────────────────────────────────── */
int32_t i2c_init(uint32_t bus_speed)
{
    g_i2c_done_sem = osSemaphoreNew(1U, 0U, NULL);

    pI2C->Initialize(i2c_callback);
    pI2C->PowerControl(ARM_POWER_FULL);

    /* bus_speed: ARM_I2C_BUS_SPEED_STANDARD (100 kHz)
     *            ARM_I2C_BUS_SPEED_FAST      (400 kHz)
     *            ARM_I2C_BUS_SPEED_FAST_PLUS (1 MHz)  */
    pI2C->Control(ARM_I2C_BUS_SPEED, bus_speed);
    pI2C->Control(ARM_I2C_BUS_CLEAR, 0U); /* release SDA if stuck low */

    return ARM_DRIVER_OK;
}

/* ── Combined format read: write register addr, repeated START, read data */
int32_t i2c_sensor_read(uint8_t  slave_addr_7bit,
                        uint8_t  reg_addr,
                        uint8_t *p_data,
                        uint32_t num_bytes,
                        uint32_t timeout_ms)
{
    int32_t   status;
    osStatus_t os_st;

    /* Phase 1: write register address with pending=true (no STOP) */
    status = pI2C->MasterTransmit(slave_addr_7bit, ®_addr, 1U,
                                  true /* xfer_pending: suppress STOP */);
    if (status != ARM_DRIVER_OK) { return status; }

    os_st = osSemaphoreAcquire(g_i2c_done_sem, timeout_ms);
    if (os_st != osOK) { return ARM_DRIVER_ERROR_TIMEOUT; }

    /* Check for NACK: slave didn't acknowledge register address */
    ARM_I2C_STATUS i2c_status = pI2C->GetStatus();
    if (i2c_status.bus_error || !i2c_status.busy == 0) {
        /* NACK received — wrong address or register */
        return ARM_DRIVER_ERROR;
    }

    /* Phase 2: repeated START + read (pending=false → send STOP after) */
    status = pI2C->MasterReceive(slave_addr_7bit, p_data, num_bytes,
                                 false /* xfer_pending: send STOP */);
    if (status != ARM_DRIVER_OK) { return status; }

    os_st = osSemaphoreAcquire(g_i2c_done_sem, timeout_ms);
    return (os_st == osOK) ? ARM_DRIVER_OK : ARM_DRIVER_ERROR_TIMEOUT;
}

/* ── 10-bit addressing example ───────────────────────────────────────── */
int32_t i2c_write_10bit(uint16_t slave_addr_10bit,
                        const uint8_t *p_data, uint32_t length)
{
    /* CMSIS-Driver uses bit 10 (0x0400) to signal 10-bit addressing */
    uint32_t addr = (uint32_t)slave_addr_10bit | ARM_I2C_ADDRESS_10BIT;

    int32_t status = pI2C->MasterTransmit((uint32_t)addr, p_data,
                                           length, false);
    if (status != ARM_DRIVER_OK) { return status; }

    osSemaphoreAcquire(g_i2c_done_sem, 100U);
    return ARM_DRIVER_OK;
}

Driver States & Events

Every CMSIS-Driver follows a well-defined state machine. Understanding this model is essential because violating the state sequence causes undefined behaviour — the vendor implementation may silently fail or corrupt hardware state. The states are: Uninitialized → Initialized → Powered → Configured → Active.

RTOS Integration

CMSIS-Driver is inherently asynchronous — every transfer function returns immediately and signals completion via callback. This is ideal for bare-metal polling loops, but RTOS applications usually want a simple blocking API: call a function, block the thread until done, return with the result. The bridge is a semaphore acquired in the calling thread and released in the driver callback.

The pattern from the UART and SPI sections above is the canonical approach. Below is a generic wrapper that codifies this pattern for any CMSIS-Driver that follows the callback convention — useful for building a BSP abstraction layer that all application modules consume.

/* ── cmsis_driver_rtos_wrapper.c ─────────────────────────────────────────
 * Generic RTOS-blocking wrapper around a CMSIS-Driver using osSemaphore.
 * The same pattern works for USART, SPI, I2C, and custom drivers.
 * ──────────────────────────────────────────────────────────────────────── */
#include "cmsis_os2.h"
#include 

/* ── Opaque driver context — one per peripheral instance ─────────────── */
typedef struct {
    osSemaphoreId_t  done_sem;    /* released by callback on completion */
    volatile int32_t last_event; /* last event code from callback       */
} DriverCtx_t;

/* ── Callback invoked by the CMSIS-Driver ISR/DMA handler ────────────── */
/* Application wraps this in a driver-specific callback that casts
 * arg back to DriverCtx_t and calls this function.                    */
void driver_ctx_signal(DriverCtx_t *ctx, int32_t event)
{
    ctx->last_event = event;
    osSemaphoreRelease(ctx->done_sem); /* unblock waiting thread */
}

/* ── Blocking wait — call after a non-blocking driver function ───────── */
int32_t driver_ctx_wait(DriverCtx_t *ctx, uint32_t timeout_ms)
{
    osStatus_t st = osSemaphoreAcquire(ctx->done_sem, timeout_ms);
    if (st != osOK) { return -1; /* timeout */ }
    return ctx->last_event;
}

/* ── Initialise a context ────────────────────────────────────────────── */
void driver_ctx_init(DriverCtx_t *ctx)
{
    ctx->done_sem   = osSemaphoreNew(1U, 0U, NULL);
    ctx->last_event = 0;
}

/* ── Example: I2C scanner using driver context ───────────────────────── */
/* Probes all 127 7-bit I2C addresses and logs which respond with ACK.  */
void i2c_scanner(ARM_DRIVER_I2C *pI2C, DriverCtx_t *ctx)
{
    uint8_t dummy = 0x00U;

    for (uint8_t addr = 1U; addr < 127U; addr++) {
        /* Attempt zero-length write — if slave ACKs, it exists */
        pI2C->MasterTransmit(addr, &dummy, 1U, false);
        int32_t event = driver_ctx_wait(ctx, 10U); /* 10 ms per probe */

        if (event >= 0 && (uint32_t)event & ARM_I2C_EVENT_TRANSFER_DONE) {
            /* Device responded — log address in hex */
            /* printf("I2C device at 0x%02X\r\n", addr); */
        }
        /* ARM_I2C_EVENT_TRANSFER_INCOMPLETE indicates NACK (no device) */
    }
}

Exercises

Peripheral Driver Specification

Use this tool to document your CMSIS-Driver peripheral configuration — interface type, baud/clock rate, DMA mode, callback events, RTOS integration approach, and error handling strategy. Download as Word, Excel, PDF, or PPTX for design documentation or BSP handoff.

Conclusion & Next Steps

In this article we have dissected the CMSIS-Driver abstraction layer from first principles to production usage:

• The ARM_DRIVER_xx struct-of-function-pointers pattern is the mechanism that decouples middleware from silicon — swap the struct pointer, recompile, run on new hardware.
• The USART driver lifecycle follows Initialize → PowerControl → Control → Send/Receive, with completion signalled asynchronously via the SignalEvent callback.
• SPI Transfer() is full-duplex; chip-select is managed externally by GPIO — this keeps the driver clean and gives you full control over CS timing for multi-device buses.
• I2C combined format reads use xfer_pending=true to suppress the STOP and issue a repeated START — the correct pattern for register-addressed sensor reads.
• The driver state machine (Uninitialized → Initialized → Powered → Configured → Active) must be respected; violating the sequence is undefined behaviour.
• A semaphore-based blocking wrapper turns asynchronous CMSIS-Driver into synchronous RTOS-friendly API calls — the canonical pattern for all production firmware.