Embedded C and the toolchain

C remains the main language of microcontroller firmware. It compiles to compact, fast code, it lets the programmer place data at exact addresses and manipulate individual bits, and every microcontroller vendor supplies a C compiler, headers and examples. C++ is common on larger projects, and Rust is growing, but the concepts in this lesson apply to all of them: how firmware reaches hardware registers, why the volatile keyword exists, how to set and clear bits safely, how source files become a binary image in flash, and what happens between reset and main. Jonah has written C before, but only for programs that run on a laptop. Embedded C looks the same and behaves differently in a dozen small ways that matter.

The NS-4 firmware is about 38,000 lines of C, built with an open-source cross-compiler. A cross-compiler runs on one machine, Jonah's laptop, and produces code for another, the NS-4's microcontroller. The build uses vendor-supplied register headers, a linker script, start-up code and a small hardware abstraction layer that Maren's team wrote years ago. The first week of the rework is spent understanding that build.

Reaching hardware registers from C

Lesson 2 showed that peripherals are controlled through registers at fixed addresses. C reaches them through pointers. A pointer to a 32-bit unsigned integer at address 0x4001 0814 lets firmware read and write the GPIO output register of port A. Vendor headers wrap such addresses in structures, one structure per peripheral type, with a member for each register in address order, so that code reads naturally: GPIOA->ODR for the output data register of port A, USART2->BRR for the baud-rate register of UART 2. The structure layout must match the hardware exactly, including reserved gaps, which is why these headers are generated from the vendor's register descriptions rather than written by hand.

#include <stdint.h>

/* One peripheral type described as a structure of registers */
typedef struct {
    volatile uint32_t MODER;    /* 0x00 mode: input, output, alternate, analog */
    volatile uint32_t OTYPER;   /* 0x04 output type: push-pull or open-drain   */
    volatile uint32_t OSPEEDR;  /* 0x08 output speed                           */
    volatile uint32_t PUPDR;    /* 0x0C pull-up / pull-down                    */
    volatile uint32_t IDR;      /* 0x10 input data (read only)                 */
    volatile uint32_t ODR;      /* 0x14 output data                            */
    volatile uint32_t BSRR;     /* 0x18 bit set/reset (write only)             */
} GPIO_TypeDef;

#define GPIOA ((GPIO_TypeDef *)0x40010800u)

void led_on(void)  { GPIOA->BSRR = (1u << 5); }          /* set pin 5         */
void led_off(void) { GPIOA->BSRR = (1u << (5 + 16)); }   /* reset pin 5       */
int  door_open(void) { return (GPIOA->IDR >> 3) & 1u; }  /* read pin 3        */

The fixed-width types from stdint.h, such as uint8_t, uint16_t and uint32_t, are essential. The size of a plain int depends on the compiler and target, while a hardware register has an exact width. Embedded code uses fixed-width types for registers, protocol fields and anything stored in flash, and reserves plain int for loop counters and arithmetic where size does not matter.

Why volatile matters

An optimizing compiler assumes that memory changes only when the program writes it. If a loop reads the same variable repeatedly without writing it, the compiler may read it once and keep the value in a register. For ordinary variables that is a valid and valuable optimization. For a hardware status register, whose bits change when a byte arrives or a conversion finishes, it is a disaster: the loop waits forever on a stale copy. The volatile qualifier tells the compiler that every read and every write must actually happen, in program order, because something outside the program can observe or change the value.

Three kinds of object need volatile: memory-mapped peripheral registers; global variables shared between an interrupt handler and the main program; and variables changed by another processor or a DMA controller. Volatile does not make an operation atomic, and it does not by itself order accesses between different volatile objects with respect to the hardware on every architecture; lesson 7 deals with shared data and critical sections, where volatile is necessary but not sufficient. Overusing volatile on ordinary variables simply makes code slower.

volatile uint32_t ticks;               /* incremented by the timer interrupt */

void delay_ms(uint32_t ms)
{
    uint32_t start = ticks;            /* volatile: read from memory each time */
    while ((ticks - start) < ms) {
        /* wait; without volatile the compiler may hoist the read out of the loop */
    }
}

The subtraction in that loop deserves a second look. Because ticks and start are unsigned 32-bit values, ticks − start gives the correct elapsed count even after ticks wraps from 4,294,967,295 back to zero, since unsigned arithmetic in C is defined modulo 2³². Writing the test as ticks < start + ms would break at the wrap. At one tick per millisecond the counter wraps after about 49.7 days, a bug that appears only in units that have been running for seven weeks, which is exactly the kind of bug the NS-4 had in its first year.

Bit manipulation

Registers pack many fields into one word: a mode field of two bits per pin, an enable bit, a three-bit prescaler, a flag. Firmware must change one field without disturbing the others. The standard idioms use masks. To set bit n, OR the register with 1 shifted left by n. To clear it, AND with the complement of that mask. To toggle, XOR. To test, AND and compare with zero. To write a multi-bit field, clear the field with a mask, then OR in the new value shifted into position. This read-modify-write sequence takes three steps, so if an interrupt handler changes the same register in between, one change can be lost; that is why many peripherals provide separate set and clear registers, such as the GPIO bit set/reset register above, which change bits in a single write.

# Register field helpers, mirroring the C idioms
def set_field(reg, shift, width, value):
    mask = (1 << width) - 1
    return (reg & ~(mask << shift) & 0xFFFFFFFF) | ((value & mask) << shift)

def get_field(reg, shift, width):
    return (reg >> shift) & ((1 << width) - 1)

moder = 0x28400000
moder = set_field(moder, 2 * 5, 2, 0b01)   # pin 5 output
moder = set_field(moder, 2 * 9, 2, 0b10)   # pin 9 alternate function
print(f"MODER = 0x{moder:08X}")
for pin in (5, 9, 13, 14):
    print(f"pin {pin:2d} mode = {get_field(moder, 2 * pin, 2):02b}")

# A baud-rate register with a 12-bit mantissa and 4-bit fraction (divide by 16 oversampling)
f_bus, baud = 24_000_000, 115_200
div = f_bus / (16 * baud)
mant, frac = int(div), round((div - int(div)) * 16)
print(f"divider {div:.4f} -> mantissa {mant}, fraction {frac}, BRR = 0x{(mant << 4) | frac:04X}")

MODER = 0x28480400
pin  5 mode = 01
pin  9 mode = 10
pin 13 mode = 10
pin 14 mode = 10
divider 13.0208 -> mantissa 13, fraction 0, BRR = 0x00D0

The baud-rate calculation at the end previews lesson 8. The program shows that pin 13 and 14 hold the original modes, 10 and 10, which were the bits already set in 0x2840 0000. Writing such helpers once, and testing them on a laptop as here, avoids a whole class of driver bugs.

From source to image: the toolchain

Building firmware is a pipeline. The preprocessor expands macros and include files. The compiler turns each C file into assembly and then an object file containing machine code and data in named sections, plus symbols and relocation records for addresses not yet known. The linker combines object files and libraries, decides where every section goes in the memory map according to a linker script, resolves the symbols and writes an executable, usually in ELF format with debug information. A final step extracts a raw binary or hex image that a programmer writes into flash. Alongside the image, the linker can produce a map file listing every function and variable with its address and size, the first place to look when flash or RAM runs short.

Four sections matter most. The text section holds machine code and goes in flash. Read-only data, such as constant tables and string literals, also goes in flash. The data section holds initialized global and static variables; because SRAM loses its contents when power is off, the initial values are stored in flash and copied into SRAM at start-up, so this section costs both flash and RAM. The bss section holds globals and statics with no initializer or a zero initializer; it costs only RAM, and start-up code clears it. The stack, and a heap if the design uses one, take the remaining RAM.

/* Excerpt from a linker script */
MEMORY
{
    FLASH (rx)  : ORIGIN = 0x08000000, LENGTH = 256K
    RAM   (rwx) : ORIGIN = 0x20000000, LENGTH = 64K
}
SECTIONS
{
    .isr_vector : { KEEP(*(.isr_vector)) } > FLASH
    .text       : { *(.text*) *(.rodata*) } > FLASH
    .data       : { _sdata = .; *(.data*) _edata = .; } > RAM AT > FLASH
    _sidata = LOADADDR(.data);
    .bss        : { _sbss = .; *(.bss*) *(COMMON) _ebss = .; } > RAM
    _estack = ORIGIN(RAM) + LENGTH(RAM);
}

Start-up code

Between reset and main, a short routine prepares the C environment. It runs before any C variable can be trusted, so it is often written in assembly or very careful C. It copies the data section's initial values from flash, starting at the load address the linker recorded, to their run addresses in SRAM. It fills the bss section with zeros. It may set up the floating-point unit, configure clocks and flash wait states, run C++ constructors for global objects, and finally call main. If main ever returns, which in firmware it should not, the start-up code loops forever or resets. A firmware engineer who understands this routine can debug the strange failures that happen before main, such as a hard fault caused by a stack placed outside RAM.

extern uint32_t _sidata, _sdata, _edata, _sbss, _ebss;
int main(void);
void system_init(void);       /* clocks and flash wait states */

void Reset_Handler(void)
{
    uint32_t *src = &_sidata, *dst = &_sdata;
    while (dst < &_edata) *dst++ = *src++;     /* copy .data from flash to RAM */
    for (dst = &_sbss; dst < &_ebss; ) *dst++ = 0u;   /* clear .bss */
    system_init();
    main();
    for (;;) { }                               /* main must not return */
}

Memory budgets and the map file

Flash and RAM are budgets, and the build should report how much of each is used. The NS-4's first rework build reports 182 KB of text and read-only data, 2.1 KB of initialized data and 41.3 KB of bss, with a 4 KB stack reserved. That leaves room in flash but less than it seems: the field-update scheme keeps two copies of the application, so the usable application area is half the flash, 128 KB, and the build no longer fits. Maren's first instruction to Jonah is to find what grew.

# Flash and RAM use from section sizes (bytes), as a build script might report them
sections = {"text": 176_400, "rodata": 9_970, "data": 2_150, "bss": 42_290}
stack = 4096
flash_total, ram_total = 256 * 1024, 64 * 1024
app_slot = flash_total // 2          # two application copies for safe updates

flash_used = sections["text"] + sections["rodata"] + sections["data"]   # data initializers live in flash
ram_used = sections["data"] + sections["bss"] + stack
print(f"flash used {flash_used/1024:6.1f} KB of {app_slot/1024:.0f} KB slot  ({100*flash_used/app_slot:.0f}%)")
print(f"RAM used   {ram_used/1024:6.1f} KB of {ram_total/1024:.0f} KB        ({100*ram_used/ram_total:.0f}%)")
print("over the slot by", round((flash_used - app_slot) / 1024, 1), "KB")

flash used  184.1 KB of 128 KB slot  (144%)
RAM used     47.4 KB of 64 KB        (74%)
over the slot by 56.1 KB

The map file showed the culprit: a debugging printf with floating-point formatting pulled in about 40 KB of library code, used only by one diagnostic command. Replacing it with a small integer formatter brought the image down to about 144 KB, still over the slot, and removing two obsolete radar drivers brought it to 118 KB. Floating-point formatting, unused library features and duplicated lookup tables are the usual suspects when an embedded image is too large.

Habits of embedded C

A few habits prevent most embedded C bugs. Avoid dynamic memory allocation after start-up, because fragmentation can make an allocation fail after months of running, and the worst case is hard to bound. Size every buffer from a named constant and check every index. Know which operations are undefined behaviour in C, such as signed overflow, shifting by the width of the type or more, and reading an uninitialized variable, because the optimizer may assume they never happen and produce code that surprises you. Turn on all compiler warnings and treat them as errors. Prefer static functions and file-scope variables to global ones. And read the generated assembly for time-critical routines; it is the only way to know what the compiler actually did.