Electronics Guide

Memory Sections

Embedded C programs divide memory into distinct sections, each serving specific purposes:

Text section (.text): Contains executable code, typically stored in flash memory. This section is read-only during execution, protecting code from accidental modification.

Read-only data (.rodata): Stores constant data such as string literals and const-qualified variables. Like the text section, this typically resides in flash memory.

Initialized data (.data): Contains global and static variables with non-zero initial values. The initial values are stored in flash and copied to RAM during startup.

Uninitialized data (.bss): Holds global and static variables without explicit initializers. The startup code zeroes this section in RAM, requiring no flash storage for initial values.

Stack: Provides storage for local variables, function parameters, and return addresses. The stack grows and shrinks as functions are called and return.

Heap: Optional memory region for dynamic allocation. Many embedded systems avoid heap usage due to fragmentation concerns and the unpredictable nature of dynamic allocation.

Linker Scripts

Linker scripts define how the linker places program sections in memory. Understanding linker scripts is essential for embedded development, as incorrect memory placement causes immediate program failure.

A typical linker script specifies memory regions available on the target device, assigns sections to appropriate regions, defines symbols for the startup code to use when initializing data sections, and configures stack and heap locations and sizes.

Developers must ensure their linker scripts accurately reflect the target hardware's memory map. Attempting to place code in non-existent memory or data in read-only memory results in systems that fail to boot or exhibit mysterious runtime errors.

Stack Management

Stack overflow is a common source of embedded system failures. Unlike desktop systems where the operating system may detect and handle stack overflow, bare-metal embedded systems typically crash without warning when the stack exceeds its allocated space.

Preventing stack overflow requires allocating sufficient stack space based on maximum call depth, avoiding deeply recursive algorithms, minimizing large local arrays that consume stack space, and using static analysis tools to estimate maximum stack usage.

Stack painting or stack monitoring techniques can help detect stack overflow during development. These approaches fill the stack with a known pattern at startup and later scan for the highest address still holding that pattern, which reveals the high-water mark of actual usage. Hardware assistance is available on many parts: Arm Cortex-M processors with a memory protection unit can place a guarded region below the stack so that an overflow raises a fault instead of silently corrupting adjacent data, and the Cortex-M33 and later cores add a dedicated stack limit register.

Dynamic Memory Allocation

Many embedded projects prohibit malloc and free outright, and safety-oriented coding standards such as MISRA C restrict dynamic allocation for good reasons. Repeated allocation and release of varied block sizes fragments the heap, so an allocation can fail even when the total free space is ample. Allocation time is data-dependent and therefore difficult to bound, which conflicts with hard real-time deadlines. Worst of all, a heap exhaustion failure surfaces long after the code that caused it, typically in the field rather than on the bench.

The common alternatives trade generality for determinism. Static allocation gives every buffer and object a fixed home at link time, so the linker reports an over-committed memory map as a build failure instead of a runtime one. Fixed-block memory pools, in which each pool serves objects of one size, allocate and free in constant time and cannot fragment. Where variable-size storage really is needed, allocating all of it once during initialization and never releasing it preserves determinism during steady-state operation.

When to Use Volatile

The volatile qualifier is essential in three primary situations:

Hardware registers: Memory-mapped hardware registers can change value due to hardware events, independent of program execution. Reading a status register might return different values on successive reads as hardware state changes. Similarly, writing to a control register causes hardware side effects beyond simply storing a value.

Variables shared with interrupt handlers: When main code and interrupt service routines share variables, the compiler cannot see that interrupts modify those variables. Without volatile, the compiler might optimize away seemingly redundant reads, causing the main code to miss changes made by interrupts.

Variables modified by a signal handler or by DMA: Buffers that a DMA controller fills or drains change outside the processor's view of memory, exactly like a hardware register. Cache maintenance may also be required on processors with data caches, because volatile prevents compiler caching but says nothing about hardware caches.

One further case attracts volatile incorrectly. Sharing data between threads or between cores is not what volatile is for: it neither guarantees atomicity nor establishes the ordering relationships that a multi-core memory model requires. The correct tools are the C11 atomic types and operations in stdatomic.h, or the mutexes and semaphores supplied by a real-time operating system. On a single-core system with a cooperative or preemptive scheduler, volatile plus a critical section is a workable idiom, but volatile by itself never is.

Volatile Semantics

The volatile qualifier provides specific guarantees: every read from a volatile object issues an actual load rather than reusing a value held in a register, every write issues an actual store rather than being coalesced or discarded, and volatile accesses are not reordered relative to one another. The C standard expresses this by making volatile accesses part of the observable behavior an implementation must preserve.

The limits matter as much as the guarantees. Volatile does not make an access atomic, does not order volatile accesses against ordinary memory accesses, and does not emit any hardware memory barrier. A processor with a write buffer or an out-of-order pipeline may still complete the accesses in a different order than the instruction stream suggests, which is why driver code that must enforce ordering at the bus level pairs volatile with an explicit barrier such as a data synchronization barrier instruction.

Proper Volatile Usage

Consider a hardware register at address 0x40000000 that provides status information. The correct way to access it:

#define STATUS_REG (*(volatile uint32_t *)0x40000000)

void wait_for_ready(void) {
    while ((STATUS_REG & READY_BIT) == 0) {
        // Wait for hardware to become ready
    }
}

Without volatile, the compiler might read STATUS_REG once before the loop, then test the same cached value forever, never detecting when hardware becomes ready.

Volatile Pointers versus Pointers to Volatile

The placement of volatile affects its meaning. Understanding the distinction is crucial:

volatile uint32_t *ptr declares a pointer to volatile data. The pointer itself is not volatile, but the data it points to is.

uint32_t * volatile ptr declares a volatile pointer to non-volatile data. The pointer value may change unexpectedly, but the data it points to is normal.

volatile uint32_t * volatile ptr declares a volatile pointer to volatile data. Both the pointer and the data may change unexpectedly.

For hardware registers, typically only the data is volatile; the register addresses are constants known at compile time.

Bitwise Operators

C provides six bitwise operators for manipulating individual bits:

AND (&): Produces 1 only where both operands have 1. Used to mask off bits or test whether specific bits are set.

OR (|): Produces 1 where either operand has 1. Used to set specific bits while preserving others.

XOR (^): Produces 1 where operands differ. Used to toggle bits or compare values.

NOT (~): Inverts all bits. Used to create masks for clearing bits.

Left shift (<<): Shifts bits toward higher positions, filling with zeros. Multiplies by powers of two.

Right shift (>>): Shifts bits toward lower positions. For unsigned types, the vacated positions fill with zeros. For a negative signed value, the result was implementation-defined through C17; C23 mandates two's complement representation and defines the operation as an arithmetic shift that replicates the sign bit. Shifting by an amount greater than or equal to the width of the promoted operand remains undefined behavior in every revision.

Two constraints apply to every bitwise operation. First, the operands undergo integer promotion, so narrow types are widened to int before the operation and the result is an int. Second, shifting a one into or past the sign bit of a signed type is undefined behavior. Both problems disappear when bitwise work is done on unsigned types, which is why the CERT C and MISRA C guidelines both restrict bitwise operators to unsigned operands.

Common Bit Operations

Several patterns appear repeatedly in embedded code. Each shift constant carries the u suffix, because 1 is a signed int and 1 << 31 is therefore undefined behavior on a 32-bit target, while 1u << 31 is well defined:

Setting a bit: Use OR with a mask containing 1 in the desired position:

register_value |= (1u << bit_position);

Clearing a bit: Use AND with the inverse of a mask:

register_value &= ~(1u << bit_position);

Toggling a bit: Use XOR with a mask:

register_value ^= (1u << bit_position);

Testing a bit: Use AND to isolate the bit, then test for non-zero:

if ((register_value & (1u << bit_position)) != 0u) {
    // Bit is set
}

Extracting a bit field: Shift right to align the field, then mask off unwanted bits:

field_value = (register_value >> field_start) & field_mask;

Inserting a bit field: Clear the field, then OR in the new value:

register_value = (register_value & ~(field_mask << field_start)) |
                 ((new_value & field_mask) << field_start);

The insertion pattern illustrates a second discipline worth adopting. Masking the incoming value before shifting it prevents an out-of-range argument from corrupting adjacent fields, a defect that is easy to introduce and difficult to find once the register controls real hardware.

Integer Promotion Pitfalls

Integer promotion is the most common source of subtle bit manipulation bugs. Operands narrower than int are promoted to int before any arithmetic or bitwise operation, and the result of that operation has the promoted type. Consider clearing the low bit of an eight-bit value:

uint8_t flags = 0xFFu;
flags &= ~0x01u;        // Correct: assignment truncates back to 8 bits
uint8_t mask  = ~0x01u; // Narrowing conversion the compiler may warn about

The expression ~0x01u has type unsigned int and the value 0xFFFFFFFE on a 32-bit target, not 0xFE. Assignment back into a uint8_t discards the upper bits and yields the intended result, but any intermediate comparison against the unpromoted value fails. A related trap appears when a promoted signed intermediate is compared with an unsigned operand: the usual arithmetic conversions may convert the signed value to unsigned, turning a negative number into a large positive one.

Three habits eliminate most of these defects: suffix every mask and shift constant with u, cast the final expression back to the destination width explicitly, and enable the compiler's conversion diagnostics (-Wconversion and -Wsign-conversion in GCC and Clang) so that implicit narrowing becomes visible at build time.

Bit Field Structures

C provides bit fields within structures for convenient access to individual bits:

typedef struct {
    uint32_t enable     : 1;
    uint32_t mode       : 3;
    uint32_t reserved   : 4;
    uint32_t prescaler  : 8;
    uint32_t count      : 16;
} timer_config_t;

While convenient, bit fields have portability concerns. The C standard leaves bit field layout implementation-defined, including bit ordering within storage units and whether bit fields can cross storage unit boundaries. For maximum portability, especially when accessing hardware registers, explicit masking and shifting is more reliable than bit fields.

Efficient Bit Manipulation

Several techniques improve bit manipulation efficiency:

Combine operations: When modifying multiple bits, combine them into single operations rather than modifying one bit at a time. This reduces the number of read-modify-write cycles.

Use constants for masks: Define bit masks as preprocessor constants or enumerations. The compiler can evaluate these at compile time, avoiding runtime computation.

Consider architecture-specific instructions: Many processors provide specialized bit manipulation instructions. Compilers often recognize common patterns and generate optimal code, but inline assembly may be necessary for unusual operations.

Memory-Mapped I/O

Most embedded processors access peripherals through memory-mapped I/O, where hardware registers appear at specific memory addresses. Reading or writing these addresses communicates with the hardware rather than accessing ordinary memory.

The fundamental technique for accessing a hardware register:

#define PERIPHERAL_BASE  0x40000000
#define CONTROL_OFFSET   0x00
#define STATUS_OFFSET    0x04
#define DATA_OFFSET      0x08

#define CONTROL_REG  (*(volatile uint32_t *)(PERIPHERAL_BASE + CONTROL_OFFSET))
#define STATUS_REG   (*(volatile uint32_t *)(PERIPHERAL_BASE + STATUS_OFFSET))
#define DATA_REG     (*(volatile uint32_t *)(PERIPHERAL_BASE + DATA_OFFSET))

This pattern casts the address to a pointer to volatile data, then dereferences it to create an lvalue that can be read or written.

Register Structures

For peripherals with many registers, structures provide cleaner organization:

typedef struct {
    volatile uint32_t CONTROL;
    volatile uint32_t STATUS;
    volatile uint32_t DATA;
    volatile uint32_t reserved[5];
    volatile uint32_t CONFIG;
} peripheral_regs_t;

#define PERIPHERAL ((peripheral_regs_t *)0x40000000)

// Usage:
PERIPHERAL->CONTROL = 0x01;
uint32_t status = PERIPHERAL->STATUS;

Structure-based access is cleaner and allows the compiler to compute offsets at compile time. However, the structure layout must exactly match the hardware register layout, including any reserved or padding registers.

Read-Modify-Write Hazards

When modifying specific bits in a register while preserving others, the typical pattern reads the current value, modifies the desired bits, and writes the result back. This read-modify-write sequence creates potential hazards:

Interrupt hazards: If an interrupt occurs between the read and write, and the interrupt handler modifies the same register, the main code will overwrite the interrupt's changes. Disabling interrupts around critical read-modify-write sequences prevents this.

Hardware hazards: Some registers have bits that hardware can modify while the processor is performing the read-modify-write. Careful study of hardware documentation reveals which registers have such hazards and how to handle them.

Write-only registers: Some registers are write-only; reading them returns undefined data or zero. Read-modify-write is impossible for these registers. Software must maintain shadow copies of the written values if bit manipulation is needed.

Access Width

Hardware registers often require specific access widths. A 32-bit register might require 32-bit accesses; attempting to write it as four separate bytes might not work correctly. Similarly, some peripherals have registers that must be accessed as 8-bit or 16-bit quantities.

Using appropriately sized types (uint8_t, uint16_t, uint32_t) and volatile qualification typically generates correct access widths. However, structure access and compiler optimizations can sometimes combine or split accesses unexpectedly. When access width is critical, verify the generated assembly code.

Common Optimization Techniques

Dead code elimination: The compiler removes code that cannot affect program output. This includes unreachable code and computations whose results are never used.

Constant folding: Expressions involving only constants are evaluated at compile time. This includes arithmetic, logical operations, and even function calls in some cases.

Common subexpression elimination: When the same expression appears multiple times, the compiler computes it once and reuses the result.

Loop optimizations: Compilers move invariant computations out of loops, unroll small loops, and sometimes vectorize loops using SIMD instructions.

Inlining: Small functions are expanded inline at call sites, eliminating function call overhead and enabling further optimization across the combined code.

Register allocation: Frequently used variables are kept in processor registers rather than memory, dramatically improving access speed.

Optimization Levels

Compilers provide optimization level flags that control the aggressiveness of optimization:

-O0: No optimization. Code is straightforward to debug but inefficient. Useful during initial development.

-O1: Basic optimization. Improves performance with minimal impact on compile time and code size.

-O2: Standard optimization. Good balance of performance, code size, and compilation time. Often the default for production code.

-O3: Aggressive optimization. Enables loop vectorization and more liberal inlining, which can increase code size substantially.

-Os: Optimize for size. Applies the -O2 optimizations that do not typically increase code size. Important for memory-constrained systems.

-Oz: Optimize for size aggressively, accepting a runtime penalty that -Os would refuse. Long available in Clang, it was added to GCC in version 12.

-Og: Optimize for debugging. Applies the optimizations that do not interfere with single-stepping and variable inspection, and is the recommended level for edit-compile-debug cycles.

Raising the optimization level occasionally appears to "break" working firmware. In almost every case the code already contained a latent defect that lower optimization levels happened to hide: a missing volatile qualifier, a race with an interrupt handler, reliance on undefined behavior, or a timing loop with no guaranteed duration. Higher optimization exposes the defect rather than causing it, so the correct response is to find the underlying fault, not to pin the project to -O0.

Link-time optimization (-flto) deserves separate mention. By deferring code generation until the whole program is visible, it enables inlining and dead-code elimination across translation units and often removes a meaningful fraction of a firmware image. It also makes symbol placement harder to reason about, so linker scripts that depend on specific section contents warrant re-verification after enabling it.

Function Attributes

Compiler-specific attributes provide fine-grained control over optimization:

inline: Suggests the compiler inline a function. The compiler may ignore this suggestion.

always_inline: Forces inlining (GCC/Clang attribute). Use sparingly as excessive inlining increases code size.

noinline: Prevents inlining. Useful for debugging or when function call overhead is acceptable and code size is critical.

pure: Indicates a function has no side effects and depends only on parameters and global memory. Enables additional optimization.

const: Stricter than pure; function depends only on parameters. Multiple calls with the same arguments can be eliminated.

noreturn: Indicates a function never returns. Allows optimization of code following calls to such functions.

Avoiding Optimization Barriers

Certain constructs prevent optimization or cause compilers to generate suboptimal code:

Function pointers: Calling through function pointers prevents inlining and limits interprocedural optimization.

Pointer aliasing: When the compiler cannot determine whether pointers alias (point to the same memory), it must assume they might, preventing certain optimizations. The restrict keyword helps in some cases.

Volatile accesses: Necessary for hardware access but prevent many optimizations. Use volatile only where required.

Memory barriers: Explicit memory barriers prevent instruction reordering across them, which may inhibit optimization.

When to Use Inline Assembly

Inline assembly is appropriate in limited circumstances:

Special instructions: Processor-specific instructions without C equivalents, such as interrupt enable/disable, cache control, or atomic operations.

Precise timing: When exact cycle counts matter and compiler-generated code varies unpredictably.

Critical performance: Hot spots where hand-optimized assembly significantly outperforms compiled code. This is increasingly rare with modern compilers.

Startup code: Processor initialization before the C runtime is operational.

GCC Extended Assembly Syntax

GCC and compatible compilers provide extended inline assembly with explicit specification of inputs, outputs, and clobbered registers:

uint32_t result;
uint32_t operand = 42;

asm volatile (
    "instruction %0, %1"
    : "=r" (result)          // Output operands
    : "r" (operand)          // Input operands
    : "memory"               // Clobbers
);

The constraint letters specify how operands are passed. Common constraints include "r" for any general register, "m" for memory operand, "i" for immediate value, and "=" prefix for output operands.

The clobber list tells the compiler which resources the assembly modifies beyond the declared outputs. The "memory" clobber indicates the assembly accesses memory in ways the compiler cannot track, and it doubles as a compiler barrier that prevents memory accesses from being reordered across the statement. The volatile qualifier on the asm statement itself serves a different purpose: it stops the optimizer from deleting or relocating a block whose outputs appear unused, which matters for instructions whose whole value lies in their side effects.

Note that the bare asm spelling is a GNU extension. Code compiled in a strict ISO conformance mode such as -std=c11 must use __asm__ __volatile__, which remains available regardless of the selected language dialect.

Portable Alternatives

Before resorting to inline assembly, consider alternatives:

Compiler intrinsics: Many compilers provide intrinsic functions that generate specific instructions while remaining C code. These are more portable than inline assembly.

CMSIS functions: For Arm Cortex-M processors, the CMSIS-Core layer provides standardized functions for common operations, including __disable_irq and __enable_irq for interrupt control, __WFI for entering sleep, __DSB and __ISB for memory and instruction barriers, and __REV for byte reversal. These compile to the same single instructions that inline assembly would emit, but they work across the Arm, GCC, and IAR toolchains without modification.

Compiler builtins: GCC provides __builtin functions for many common operations, from bit counting (__builtin_popcount, __builtin_clz) to byte swapping and atomic read-modify-write sequences.

Fixed-Width Integer Types

The stdint.h header provides integer types with guaranteed sizes: int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, and their 64-bit counterparts. These types are essential for embedded programming where data must match hardware register sizes or communication protocol requirements.

Using int or long for hardware-related code is risky because their sizes vary between platforms. A variable declared as int might be 16 bits on one compiler and 32 bits on another, causing subtle bugs when porting code.

Size and Alignment

Data structure layout affects both memory usage and access efficiency. Compilers typically align structure members to their natural boundaries, inserting padding between members to maintain alignment.

Understanding and controlling alignment matters for embedded systems:

Memory efficiency: Reordering structure members can reduce padding and decrease memory usage.

Hardware requirements: Some processors require aligned accesses; misaligned accesses cause exceptions or incorrect results.

Communication protocols: Data structures exchanged with external systems often require specific layouts that may not match the compiler's default packing.

The packed attribute forces structures to use no padding, essential for matching external data formats but potentially causing slower access or alignment faults on some processors.

Endianness

Endianness determines the byte order of multi-byte values in memory. Big-endian systems store the most significant byte at the lowest address; little-endian systems store the least significant byte first.

Endianness matters when interpreting data from external sources or writing data for external consumption. Network protocols typically use big-endian byte order (network byte order), while most modern processors are little-endian.

Converting between byte orders requires explicit code. The familiar htons() and htonl() functions come from the POSIX sockets interface rather than the C standard library, so a freestanding embedded toolchain generally does not provide them. Portable alternatives include assembling multi-byte values one byte at a time, which sidesteps both endianness and alignment questions, or calling a compiler builtin such as GCC's __builtin_bswap16 and __builtin_bswap32, which map to a single byte-reverse instruction on architectures that have one.

Interrupt Service Routine Structure

Compiler-specific attributes mark functions as interrupt handlers, instructing the compiler to generate appropriate prologue and epilogue code:

void __attribute__((interrupt)) timer_isr(void) {
    // Clear interrupt flag
    TIMER_STATUS = TIMER_FLAG;

    // Handle interrupt
    timer_ticks++;
}

The exact syntax varies by compiler and architecture. Arm Cortex-M processors use a simpler model in which interrupt handlers are ordinary C functions with no attribute at all: on exception entry the hardware automatically stacks the caller-saved registers that the procedure call standard requires, so a compiler-generated function prologue is already correct. The handler is bound to its vector by placing its address in the vector table rather than by any property of the function itself.

One consequence of clearing a peripheral flag deserves attention. On a write-buffered bus the write that clears the flag may still be in flight when the handler returns, causing the processor to re-enter the same interrupt. Clearing the flag early in the handler, or reading the register back before returning, forces the write to complete and avoids the spurious re-entry.

Shared Data Protection

Variables shared between interrupt handlers and main code require careful handling:

Volatile declaration: Shared variables must be volatile to prevent the compiler from caching values across interrupt boundaries.

Atomic access: Operations on shared variables must be atomic to prevent corruption. Atomicity depends on the machine, not on the source code: an aligned load or store no wider than the data bus usually compiles to a single instruction, while a 32-bit variable on an 8-bit microcontroller is read in four separate steps that an interrupt can split. Note that a read-modify-write such as counter++ is never atomic regardless of width, because it compiles to at least a load, an add, and a store. The C11 header stdatomic.h provides atomic types and the atomic_flag primitive where the toolchain supports them; on small parts without atomic instructions the compiler implements them by masking interrupts.

Critical sections: When atomic access is insufficient, disable interrupts around critical sections that access shared data:

uint32_t irq_state = disable_interrupts();
// Access shared data
critical_shared_variable++;
restore_interrupts(irq_state);

Interrupt Latency

Interrupt handlers should complete quickly to maintain system responsiveness. Long handlers increase interrupt latency for other interrupts and may cause missed events.

When significant processing is required in response to an interrupt, the handler should capture essential data, set a flag or post to a queue, and defer processing to main code or to a lower-priority task. This deferred processing pattern keeps handlers short while ensuring events are handled.

Two constructs in particular do not belong in an interrupt handler. Blocking calls, including waits on a semaphore or a busy-wait on a peripheral, stall every lower-priority interrupt for the duration. Floating-point arithmetic is also expensive on parts that lack a hardware floating-point unit, and on parts that have one it may force the handler to save and restore the floating-point register file. Where an interrupt must produce a scaled result, fixed-point arithmetic on integers is usually both faster and more predictable.

Input Validation

Functions should validate inputs before using them. This is especially important for values from external sources such as communication interfaces or sensors:

bool set_speed(uint16_t rpm) {
    if (rpm > MAX_RPM) {
        // Log error, return failure, or clamp value
        return false;
    }
    motor_speed = rpm;
    return true;
}

Assert and Static Assert

The assert macro catches programming errors during development. In embedded systems, assert behavior typically differs from desktop systems; rather than printing a message and exiting, embedded asserts might trigger a breakpoint, log the failing file and line to non-volatile memory, or force a reset. Because defining NDEBUG removes assertions entirely, an assertion must never contain an expression with side effects that the program depends on.

Static assertions catch errors at compile time and cost nothing at runtime, which makes them well suited to embedded work. C11 introduced the _Static_assert keyword along with a static_assert macro in assert.h; C23 promotes static_assert to a keyword and makes the diagnostic message optional. Typical uses verify that a structure matches an external wire format, that a buffer size is a power of two, or that a configuration constant lies within range:

static_assert(sizeof(packet_header_t) == 8,
              "packet header must match the wire format");
static_assert((RING_BUFFER_SIZE & (RING_BUFFER_SIZE - 1u)) == 0u,
              "ring buffer size must be a power of two");

Watchdog Integration

Watchdog timers reset the system if software fails to refresh them periodically. Effective watchdog usage requires refreshing only when the system is operating correctly, not merely when code executes:

void main_loop(void) {
    while (1) {
        if (check_sensors_valid() &&
            check_communication_active() &&
            check_state_machine_healthy()) {
            watchdog_refresh();
        }
        // Continue processing
    }
}

Error Handling Strategies

Embedded systems need clear strategies for handling errors. Options include returning error codes from functions, using global error flags, logging errors for later analysis, attempting recovery procedures, and failing safe when recovery is impossible.

The appropriate strategy depends on the application. Safety-critical systems may require immediate safe shutdown, while consumer devices might attempt recovery or graceful degradation.

Header File Organization

Header files should provide clean interfaces while hiding implementation details:

#ifndef MODULE_H
#define MODULE_H

#include <stdint.h>

// Public types
typedef struct {
    uint32_t value;
} module_handle_t;

// Public functions
void module_init(void);
module_handle_t *module_create(void);
void module_process(module_handle_t *handle);

#endif // MODULE_H

Include guards prevent multiple inclusion. Minimize dependencies by including only necessary headers. Declare, rather than define, in headers to avoid multiple definition errors.

Naming Conventions

Consistent naming improves code readability:

Functions: Use verb phrases describing actions: uart_send_byte(), timer_get_count().

Variables: Use descriptive names indicating purpose: bytes_received, motor_speed_rpm.

Constants: Use uppercase with underscores: MAX_BUFFER_SIZE, UART_BAUD_RATE.

Types: Use suffix conventions: _t for types, _e for enums, _s for structs.

Prefix module-specific identifiers with the module name to avoid name collisions in large projects.

Documentation

Embedded code documentation should explain the why, not just the what. Hardware interactions, timing requirements, and design decisions benefit from comments, because the reasoning behind a register write or a delay is rarely obvious from the code alone. Comments that merely restate what the code does add clutter without adding insight.

Documentation tools such as Doxygen extract structured comments to generate browsable API references, keeping interface documentation synchronized with the source. Beyond API documentation, embedded projects benefit from recording assumptions about the hardware, the expected execution context of interrupt handlers, and the units of physical quantities such as raw counts versus engineering values.

Unit Testing

Unit tests verify individual functions in isolation. Hardware abstraction layers enable testing application logic on development computers without target hardware, where tests run in seconds and debugging tools are unconstrained. Mocking frameworks substitute test implementations for hardware-dependent code, allowing a test to assert that a driver wrote the expected sequence of register values. Widely used options for C include Unity with its CMock companion, CppUTest, and the Ceedling build harness that ties them together.

Off-target testing has a known blind spot. The host compiler, its type widths, its endianness, and its optimizer all differ from the target's, so a test that passes on a workstation does not prove the same source behaves identically on the microcontroller. Off-target tests catch logic errors efficiently; they do not replace execution on the real device.

Static Analysis

Static analysis tools examine code without executing it, finding potential bugs, style violations, and security vulnerabilities. Commercial tools such as PC-lint Plus, Polyspace, Coverity, and Klocwork, alongside open-source alternatives like Cppcheck and the Clang Static Analyzer, catch issues that might escape code review and testing.

Many static analyzers also enforce coding standards. MISRA C, published by MISRA (originally the Motor Industry Software Reliability Association), defines a restricted "safe subset" of the language that avoids undefined and implementation-defined behavior. The third edition, MISRA C:2023, contains 221 guidelines and covers C90, C99, C11, and C18; the incremental MISRA C:2025 release that followed raised the total to 225. Originally created for automotive software and referenced by the ISO 26262 functional-safety standard, MISRA C is now widely applied across automotive, aerospace, medical, and industrial systems. The CERT C Coding Standard addresses overlapping ground with a stronger emphasis on security. Static analysis tools flag deviations from either standard automatically, and both expect deviations to be documented and justified rather than silently ignored.

On-Target Testing

Testing on actual hardware remains essential, because only the target exercises the real peripherals, the real interrupt timing, and the real compiler output. Hardware-in-the-loop testing combines the real device with a simulated environment that supplies sensor stimuli and captures actuator responses, enabling repeatable testing of scenarios that would be dangerous or impractical to stage physically.

On-target verification also draws on instrumentation that off-target testing cannot offer. Debug probes expose live memory and register state without halting the processor, single-wire trace outputs such as Arm's Instrumentation Trace Macrocell carry printf-style diagnostics with minimal intrusion, and code coverage measured on the target demonstrates which paths the test suite actually exercised on the shipped binary.