CMSIS Part 20: Tooling & Workflow — Professional Embedded Development

Static Analysis with cppcheck

Static analysis tools examine source code without executing it, finding bugs that testing may miss: null pointer dereferences, buffer overflows, use-after-free, uninitialized variables, and coding standard violations. For embedded firmware, they are especially valuable because hardware bugs are expensive to diagnose and reproduce.

cppcheck is the leading open-source C static analyser — free, fast, low false-positive rate, and integrates with GitHub Actions, VS Code, and CLion. The MISRA addon extends it to report MISRA-C:2012 rule violations. Commercial tools (PC-lint Plus, Polyspace, Coverity) have significantly lower false positive rates and better MISRA coverage, but cppcheck is the right starting point for most projects.

# Run cppcheck with MISRA-C:2012 addon
# Install: sudo apt-get install cppcheck

# Basic static analysis (all error types, fail on any error)
cppcheck \
    --enable=all \
    --error-exitcode=1 \
    --suppress=missingIncludeSystem \
    --inline-suppr \
    -I src/ \
    -I CMSIS/Core/Include/ \
    -I CMSIS/Device/ST/STM32F4xx/Include/ \
    --std=c11 \
    src/

# With MISRA-C:2012 addon (requires misra.py in cppcheck addons)
cppcheck \
    --addon=misra \
    --suppress=misra-c2012-2.3 \   # Suppress: unused type declaration
    --suppress=misra-c2012-2.4 \   # Suppress: unused tag declaration
    --enable=style,performance,portability \
    src/

# Generate XML report for CI integration
cppcheck \
    --enable=all \
    --xml \
    --xml-version=2 \
    src/ 2> cppcheck-report.xml

# Convert XML to HTML for human review
cppcheck-htmlreport \
    --file=cppcheck-report.xml \
    --report-dir=cppcheck-html \
    --source-dir=src/

MISRA-C Compliance

MISRA-C (Motor Industry Software Reliability Association) is the embedded C coding standard used in safety-critical systems — automotive (ISO 26262), aerospace (DO-178C), medical (IEC 62304), and industrial (IEC 61508). MISRA-C:2012 has 143 rules: 10 mandatory, 111 required, 22 advisory.

For firmware not in a formally safety-critical domain, MISRA compliance still provides value as a discipline: it bans the most dangerous C constructs (undefined behaviour, implicit conversions, goto, recursion, dynamic allocation). Think of it as a coding standard that forces you to write C the way experienced embedded engineers already do.

Code Coverage Gating in CI

Part 17 covered GCOV and gcovr for generating coverage reports. Here we focus on using coverage as a CI gate — blocking merges if coverage drops below the project threshold. This prevents the common pattern where developers add new code without writing tests, gradually eroding coverage over time.

The CMake CTest integration allows running unit tests as part of the CMake build system — making them accessible to any CI system via a standard interface, not just Ceedling.

# CMakeLists.txt — CTest integration for host-side unit tests
cmake_minimum_required(VERSION 3.20)
project(firmware_tests C)

# Enable CTest
enable_testing()

# Host test executable (GCC, not arm-none-eabi)
add_executable(test_ring_buffer
    test/test_ring_buffer.c
    src/ring_buffer.c
    vendor/unity/unity.c
)

target_include_directories(test_ring_buffer PRIVATE
    src/
    vendor/unity/
    test/support/
)

target_compile_options(test_ring_buffer PRIVATE
    --coverage
    -O0
    -DUNIT_TESTING
)

target_link_options(test_ring_buffer PRIVATE --coverage)

# Register with CTest
add_test(NAME ring_buffer_tests COMMAND test_ring_buffer)
set_tests_properties(ring_buffer_tests PROPERTIES
    PASS_REGULAR_EXPRESSION "OK"
    FAIL_REGULAR_EXPRESSION "FAIL"
)

# Run via: cmake --build . && ctest --output-on-failure
# Coverage: gcovr --root .. --html --html-details -o coverage.html

Doxygen API Documentation

Doxygen generates HTML, PDF, and LaTeX API documentation from structured comments in C source files. CMSIS itself is documented with Doxygen — the CMSIS-Core API reference you read online is generated from the same core_cm4.h comments. Following the CMSIS documentation style means your team's firmware documentation integrates seamlessly with the CMSIS reference.

/**
 * @file ring_buffer.h
 * @brief Lock-free ring buffer for embedded firmware.
 *
 * Provides a statically-allocated, ISR-safe ring buffer for byte data.
 * Suitable for UART receive buffers, audio sample FIFOs, and sensor data queues.
 *
 * @note Push is ISR-safe when only one ISR writes and the application reads.
 *       For multiple-writer scenarios use a mutex or disable interrupts.
 *
 * @author Wasil Zafar
 * @date   2026-03-31
 * @version 1.2.0
 */

/**
 * @brief Ring buffer instance structure.
 *
 * Initialise with ring_buffer_init() before use.
 * Do not access members directly — use the API functions.
 */
typedef struct {
    uint8_t  *storage;   /**< Pointer to backing storage array    */
    uint32_t  capacity;  /**< Total capacity in bytes             */
    uint32_t  head;      /**< Write index (modified by producer)  */
    uint32_t  tail;      /**< Read index (modified by consumer)   */
} ring_buffer_t;

/**
 * @brief Initialise a ring buffer.
 *
 * Associates the ring buffer instance with a caller-provided backing array.
 * The backing array must remain valid for the lifetime of the ring buffer.
 *
 * @param[out] rb       Pointer to uninitialised ring_buffer_t instance.
 * @param[in]  storage  Pointer to caller-allocated backing array.
 * @param[in]  capacity Size of backing array in bytes.
 *
 * @retval RING_BUFFER_OK     Initialisation successful.
 * @retval RING_BUFFER_ERROR  Invalid arguments (NULL pointer or zero capacity).
 *
 * @code
 * static uint8_t buf[64];
 * ring_buffer_t  rb;
 * ring_buffer_init(&rb, buf, sizeof(buf));
 * @endcode
 */
int32_t ring_buffer_init(ring_buffer_t *rb, uint8_t *storage, uint32_t capacity);

# Doxyfile configuration for embedded C project (key settings)
# Generate with: doxygen -g Doxyfile, then edit

PROJECT_NAME           = "My Firmware API"
PROJECT_NUMBER         = "v1.2.0"
PROJECT_BRIEF          = "CMSIS-based embedded firmware for SmartSensor v2"
OUTPUT_DIRECTORY       = docs/

# Source files
INPUT                  = src/ include/
FILE_PATTERNS          = *.c *.h
RECURSIVE              = YES
EXTRACT_ALL            = YES
EXTRACT_STATIC         = YES

# CMSIS-style: extract all groups and brief descriptions
JAVADOC_AUTOBRIEF      = YES
QT_AUTOBRIEF           = YES
MULTILINE_CPP_IS_BRIEF = YES

# Output formats
GENERATE_HTML          = YES
GENERATE_LATEX         = NO     # Set YES for PDF generation
HTML_OUTPUT            = html/
HTML_COLORSTYLE        = DARK
HTML_TIMESTAMP         = YES

# Call/caller graphs (requires Graphviz)
HAVE_DOT               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
DOT_IMAGE_FORMAT       = svg

# Build: doxygen Doxyfile
# Open: xdg-open docs/html/index.html

Semantic Versioning & Release Automation

Semantic versioning (MAJOR.MINOR.PATCH) gives firmware versions meaning: MAJOR increments on breaking API changes, MINOR on new backwards-compatible features, PATCH on bug fixes. For embedded firmware, version numbers are embedded in the binary image header — any firmware update mechanism can read the version from flash without executing the firmware.

/**
 * Firmware version embedded in the image header.
 * Placed in a named section so the bootloader and OTA manager can read it
 * at a fixed offset without executing the application.
 *
 * CMakeLists.txt sets VERSION_MAJOR/MINOR/PATCH via:
 *   project(firmware VERSION 1.4.2)
 *   target_compile_definitions(firmware.elf PRIVATE
 *       FW_VERSION_MAJOR=${PROJECT_VERSION_MAJOR}
 *       FW_VERSION_MINOR=${PROJECT_VERSION_MINOR}
 *       FW_VERSION_PATCH=${PROJECT_VERSION_PATCH}
 *   )
 */
#include 

/* Firmware image header — placed at fixed offset (e.g., 0x200 from flash start) */
typedef struct __attribute__((packed)) {
    uint32_t magic;            /* 0xDEADC0DE — identifies valid firmware image  */
    uint8_t  version_major;    /* Semantic version MAJOR                        */
    uint8_t  version_minor;    /* Semantic version MINOR                        */
    uint8_t  version_patch;    /* Semantic version PATCH                        */
    uint8_t  reserved;
    uint32_t build_timestamp;  /* Unix timestamp at build time                  */
    uint32_t image_size;       /* Size of application image in bytes            */
    uint32_t crc32;            /* CRC32 of the image for integrity verification */
    char     git_hash[8];      /* First 8 chars of git commit hash              */
} fw_image_header_t;

/* Static const — placed in read-only flash by linker */
__attribute__((section(".fw_header"), used))
static const fw_image_header_t g_fw_header = {
    .magic           = 0xDEADC0DEU,
    .version_major   = FW_VERSION_MAJOR,
    .version_minor   = FW_VERSION_MINOR,
    .version_patch   = FW_VERSION_PATCH,
    .build_timestamp = 0U,      /* Filled by post-build script */
    .image_size      = 0U,      /* Filled by post-build script */
    .crc32           = 0U,      /* Filled by post-build script */
    .git_hash        = GIT_HASH_SHORT,
};

Exercises

CI/CD Pipeline Planner

Use this tool to plan and document your embedded CI/CD pipeline — platform selection, static analysis tools, coding standards, coverage thresholds, documentation strategy, and deployment targets. Download as Word, Excel, PDF, or PPTX for team agreement or quality management documentation.

Conclusion — The Complete CMSIS Toolkit

In this final part we have completed the professional embedded development workflow:

• A complete GitHub Actions CI/CD pipeline — dual-compiler strategy (arm-none-eabi for firmware, host GCC for unit tests), parallel jobs, coverage gates, static analysis gates, and automated release artefact creation.
• cppcheck with MISRA addon — open-source static analysis that catches null dereferences, buffer overflows, and MISRA-C rule violations before code reaches review.
• MISRA-C:2012 — the embedded coding standard that bans the most dangerous C constructs; applied pragmatically with documented deviations rather than zero-tolerance all-or-nothing.
• CMake CTest integration — standardised unit test execution accessible to any CI system without Ceedling dependency.
• Doxygen with CMSIS-style comment conventions — API documentation that follows the same format as the CMSIS reference itself, deployed automatically to GitHub Pages.
• Semantic versioning in the firmware image header — version numbers embedded in flash, readable by the bootloader and OTA system without executing application code.