Most people use technology. Very few actually control it.

I want to change that. You're going to learn embedded programming by building something fun. Together, we'll build 'Light Chaser', a classic arcade game where a light bounces back and forth. Time your button press right to hit the centre. Miss and you lose.

Seems easy enough, right? But making it work means nailing the 'Big Three' of electronics: timing, inputs, outputs.

Before we wire up our first virtual LED though, we need to sort out your workshop. Most beginners grab basic tools they'll outgrow in a month. We're skipping that. Going straight to a professional setup that actual developers use: VS Code and Wokwi. Like learning to drive in a simulator before hitting actual roads. Safer, faster, way more fun when nothing can break.

The Magic Smoke Problem

Here's how it usually goes when you're starting out.

Order a microcontroller board online. Wait a week for shipping. Wire something wrong and components let out this thing hobbyists call 'magic smoke'. They stop working after that. Order replacements, wait another week.

Hardware doesn't forgive mistakes. Connect power backwards and you've got a dead board. Too much current kills the LED. Short two pins and everything dies. I've done all of these.

This isn't about embedded development being hard. It's about learning it being hard. Professionals screw these things up too, difference is they know why it failed and how to figure it out. Beginners just see smoke and confusion.

Simulators fix this. Mistakes are free. Wire something wrong and you just reset, try again. Want to see what happens when you push 500mA through a pin rated for 20mA? Go for it. The simulated chip won't die. You learn what would happen without spending £15 on replacements or waiting a week for shipping.

Why Not Just Use the Browser Simulator?

If you've looked for Arduino tutorials, you've probably seen Wokwi already. Great browser simulator. Build circuits, write code, run everything in your browser. Perfect for quick experiments.

We're taking it further using VS Code. Not just here to blink LEDs. We're learning professional embedded development from day one.

The browser's fine for messing about. VS Code's where real work happens.

Here's what you get with VS Code that the browser can't match:

A real IDE. The browser editor's fine for basics. VS Code's different. Autocomplete that actually understands your code. Jump to function definitions with one click. Refactoring tools rename variables across your whole project. Errors show up before you even compile. These aren't luxuries, this is how people actually write code. Learning with proper tools now means no bad habits to unlearn later.

Version control. Browser projects live in browser storage. Clear your cache, switch computers, crash at the wrong moment and it's gone. VS Code stores your projects as files on your computer. Stick them in Git repositories, track every change, experiment on branches. How actual software gets developed.

Offline work. Once you've installed everything and grabbed dependencies, internet becomes optional. On a train, in a cabin somewhere, wherever. The browser simulator needs connectivity. Your local setup doesn't.

PlatformIO integration. The Arduino IDE's alright for getting started but hides too much. PlatformIO's widely used in the industry for embedded toolchains. Runs inside VS Code, manages libraries, handles different board configs. Scales from hobby projects to professional firmware. You'll probably face PlatformIO or something like it when you work on real embedded stuff later.

Debugging. This is the big one. Browser simulator runs your code. VS Code extension lets you stop time. Set a breakpoint on any line and when execution hits it, everything freezes. Every variable's there to inspect. Step through code one line at a time, watch values change. You see exactly what's happening inside your microcontroller at that moment.

I'll cover debugging properly later. Here's what matters now. It changes how you think about code. Problems that'd take hours of print statements take minutes with a debugger.

The Goal of This Series

By the end you'll have a complete, playable Light Chaser game in simulation. Clean, modular code organised like professional stuff. You'll understand GPIO, timing, state machines, I2C. Enough to build this on real hardware if you want.

What actually matters though is understanding why things work, not just that they work.

When you see pinMode(13, OUTPUT), you'll know what's happening at the register level. When you use millis() for timing, you'll understand the overflow behaviour and why it doesn't matter. Read a button and you'll understand pull-up resistors, active-low logic, switch bounce.

What You'll Need

A computer before the next post. Windows, Mac, Linux, doesn't matter. Internet for initial setup and downloading packages. About 2GB of disk space for VS Code, PlatformIO, and Wokwi.

No prior programming experience needed. Knowing variables and loops helps, but I'll explain as we go. Never programmed before? Just learn C alongside embedded concepts. Plenty of people do it that way.

No hardware needed either. That's the whole point of Wokwi. Build and test everything in simulation first. Want to build the physical version later? I'll put a shopping list at the end. Optional though.

Why This Approach Works

Learning embedded programming's tricky for one reason: too many things at once.

A programming language. How microcontrollers work. Electronics. Reading datasheets. Debugging techniques nothing like web or desktop stuff.

Most tutorials throw all this at you with real hardware. Overwhelming. Something breaks and you don't know if it's your code, your wiring, a fried component, or plain not understanding how the chip works.

Simulation strips out the hardware variables. Something doesn't work and it's your code or your understanding. Much smaller problem. The debugger shows you exactly what your code's doing. Makes finding bugs way easier.

Once you've got the software side down, adding real hardware's straightforward. Concepts transfer directly, code's the same. Just pick up a few practical bits like soldering and reading resistor colours.

A Note on Arduino vs 'Real Embedded'

Some people think Arduino's just a toy. They'll tell you to learn 'real' embedded programming with bare-metal register stuff from the start.

They're not wrong. Arduino hides a lot. That digitalWrite() function you'll use compiles into code that's roughly 18-50 times slower than direct register access. For professional work, that matters.

But they're missing the point about learning.

Arduino's abstractions let you focus on concepts without drowning in processor-specific details. Once you know what digitalWrite() does, learning how to do it faster with registers becomes straightforward. The other way round doesn't work. Start with registers and you're fighting syntax whilst trying to grasp fundamental concepts at the same time. Recipe for giving up.

We'll peek behind Arduino's curtain later anyway. You'll see what those friendly functions actually do. By then you'll have context for it.

What's Next

Next post we're installing VS Code, PlatformIO, and the Wokwi extension. I'll walk through every step. By the end you'll have a working setup ready for building embedded stuff.

Post after that? You'll write your first embedded program.

Then we build the game. See you next time!

What's a Byte Order?

Consider the 32-bit integer 0x12345678. It has four bytes: 0x12, 0x34, 0x56, and 0x78. When stored in memory, these bytes occupy four consecutive addresses. The question is: in what order?

Big endian stores the most significant byte first, at the lowest memory address. The most significant byte is the one that affects the value the most, just like the leftmost digit in a decimal number. In 0x12345678, that's 0x12. Changing it from 0x12 to 0x13 adds 16 million to the value. Changing the least significant byte (0x78) by the same amount only adds 1.

If our integer starts at address 0x1000, memory looks like this:

Address:  0x1000  0x1001  0x1002  0x1003
Value:      12      34      56      78

The "big end", the byte with the most weight, comes first. This matches how we write numbers: left to right, most significant digit first.

Little endian stores the least significant byte first:

Address:  0x1000  0x1001  0x1002  0x1003
Value:      78      56      34      12

The "little end" comes first. If you're staring at a memory dump trying to find 0x12345678, you'll see 78 56 34 12 and wonder if something has gone horribly wrong (it hasn't).

The terms themselves come from Gulliver's Travels, where two factions go to war over whether to crack eggs at the big end or the little end. The computer science usage is a deliberate joke about arbitrary, religious disputes. Fitting, given how much trouble byte order has caused over the decades.

Which Processors Use Which?

Most processors you'll encounter in embedded work are little endian. The entire x86 and x86-64 family is little endian. ARM processors are predominantly little endian, though many ARM chips can operate in either mode (they're "bi-endian"). Most microcontrollers, including AVR, ESP32, STM32, and others based on ARM Cortex-M cores, are little endian.

Big endian is less common but far from extinct. Network protocols standardised on big endian decades ago, which is why it's often called "network byte order." This was arguably the right call since big endian matches how humans write numbers, but it means that virtually every little-endian machine (which is most of them) has to byte-swap data at the network boundary. Every TCP/IP stack in the world is doing this constantly.

Some PowerPC systems are big endian. Certain Motorola processors are big endian. And you'll encounter it in many file formats and communication protocols regardless of what processor you're running on.

Why This Matters in Embedded Programming

In high-level application programming, you can often ignore endianness entirely. The compiler handles it, and your integers just work. Embedded programming is different. You're frequently dealing with situations where byte order becomes explicit.

When you read data from a sensor over I2C or SPI, the sensor sends bytes in a specific order defined by its datasheet. If the sensor is big endian and your microcontroller is little endian, you can't just cast the received bytes to an integer and expect the right answer.

When you're parsing a binary protocol, say, reading packets from a GPS module or a CAN bus, the protocol specification defines the byte order. You need to decode the bytes correctly regardless of your processor's native order.

When you're writing to hardware registers that span multiple bytes, the peripheral's documentation will tell you the expected byte order. Get it wrong and you'll write garbage.

When you're storing data to flash or EEPROM that might be read by a different system, or sending data over a network, you need to agree on a byte order with the other end.

Detecting Endianness

You can determine your system's endianness at runtime:

int is_little_endian(void) {
    uint16_t value = 0x0001;
    uint8_t *byte = (uint8_t *)&value;
    return byte[0] == 0x01;  // If the first byte is 0x01, we're little endian
}

This works by storing a known value and then examining the first byte. In little endian, the least significant byte (0x01) is at the lowest address. In big endian, the most significant byte (0x00) would be there.

For compile-time detection, most compilers provide predefined macros. GCC and Clang offer __BYTE_ORDER__, and many embedded toolchains have their own equivalents.

Converting Between Byte Orders

The standard approach is to convert to a known byte order when data crosses a boundary, then convert back on the other side. Network programming uses htons, htonl, ntohs, and ntohl (host-to-network and network-to-host for short and long integers), but these aren't always available in embedded environments. You'll often write your own.

Here's a simple byte swap for a 16-bit value:

uint16_t swap16(uint16_t value) {
    return (value << 8) | (value >> 8);
}

And for 32-bit:

uint32_t swap32(uint32_t value) {
    return ((value >> 24) & 0x000000FF) |
           ((value >> 8)  & 0x0000FF00) |
           ((value << 8)  & 0x00FF0000) |
           ((value << 24) & 0xFF000000);
}

Many compilers provide built-in functions for this. GCC has __builtin_bswap16, __builtin_bswap32, and __builtin_bswap64. What looks like a mess of shifts and masks becomes a single REV instruction on ARM, or BSWAP on x86.

Building Values from Bytes: The Portable Way

Rather than relying on casts and hoping the byte order works out, you can construct multi-byte values explicitly from their component bytes. This approach is portable and makes the byte order obvious in the code.

Reading a big-endian 16-bit value from a byte buffer:

uint16_t read_be16(const uint8_t *buffer) {
    return ((uint16_t)buffer[0] << 8) | buffer[1];
}

Reading a little-endian 16-bit value:

uint16_t read_le16(const uint8_t *buffer) {
    return ((uint16_t)buffer[1] << 8) | buffer[0];
}

The same pattern extends to larger values:

uint32_t read_be32(const uint8_t *buffer) {
    return ((uint32_t)buffer[0] << 24) |
           ((uint32_t)buffer[1] << 16) |
           ((uint32_t)buffer[2] << 8)  |
           buffer[3];
}

uint32_t read_le32(const uint8_t *buffer) {
    return ((uint32_t)buffer[3] << 24) |
           ((uint32_t)buffer[2] << 16) |
           ((uint32_t)buffer[1] << 8)  |
           buffer[0];
}

And for writing:

void write_be16(uint8_t *buffer, uint16_t value) {
    buffer[0] = (value >> 8) & 0xFF;
    buffer[1] = value & 0xFF;
}

void write_le16(uint8_t *buffer, uint16_t value) {
    buffer[0] = value & 0xFF;
    buffer[1] = (value >> 8) & 0xFF;
}

This might look like extra work, but it's actually cleaner than scattering byte-swap calls throughout your code, and it makes the expected byte order explicit at the point where data is read or written.

A Practical Example: Parsing a Sensor Reading

Say you're reading from a temperature sensor that sends a 16-bit signed value in big-endian format over I2C. The raw bytes arrive in a buffer:

uint8_t buffer[2];
i2c_read(SENSOR_ADDR, buffer, 2);  // Read two bytes from the sensor

// Wrong approach on a little-endian system:
int16_t temp_wrong = *(int16_t *)buffer;  // Byte order is reversed!

// Correct approach:
int16_t temp_correct = (int16_t)((buffer[0] << 8) | buffer[1]);

The cast approach treats the bytes in the processor's native order, which gives you a garbage value if that order doesn't match what the sensor sent. The explicit approach constructs the value correctly regardless of the processor's endianness.

For signed values, you might need to handle sign extension explicitly if you're building up from unsigned bytes:

int16_t read_be_int16(const uint8_t *buffer) {
    uint16_t raw = ((uint16_t)buffer[0] << 8) | buffer[1];
    return (int16_t)raw;  // Cast handles sign correctly
}

Keeping It Sane

Endianness bugs are nasty because they're silent. The code compiles. It runs. It doesn't crash. It just produces garbage, and sometimes that garbage looks almost plausible: off by a factor of 256 here, sign-flipped there. You can stare at the code for hours without seeing it.

A few practices help keep things manageable. Be explicit about byte order in code that crosses system boundaries. Use functions like read_be32 instead of pointer casts. Document the expected byte order in comments or function names. Use fixed-width types (uint16_t, int32_t) rather than int or short when dealing with binary data, so you know exactly how many bytes you're working with. And when parsing a protocol or file format, keep the specification handy and double-check your byte order assumptions.

Byte order is one of those things that feels like it shouldn't matter in 2025. We've abstracted away so much complexity in computing. Surely we could have standardised this by now. But we haven't, and in embedded work, you're close enough to the metal that the abstraction isn't there to save you. Know your byte order. Be explicit about it in code. And when something's giving you impossible values, check endianness before you tear apart your hardware.

There is. It's called RAII—"Resource Acquisition Is Initialisation." The pattern originated in C++, where it's built into the language. C doesn't have the language features that make RAII automatic, but the underlying concept is still valuable and you can apply it with a bit of discipline.

The core idea is simple: tie the lifetime of a resource to the lifetime of an object. When the object is created, it acquires the resource. When the object is destroyed, it releases the resource. No separate cleanup step to forget, no resources left dangling.

The Problem RAII Solves

Consider a function that opens a file, does some work, and closes it:

int process_config(const char *filename) {
    FILE *f = fopen(filename, "r");
    if (!f) return -1;

    // Do some work...
    if (parse_failed) {
        return -1;  // Oops! We forgot to close the file.
    }

    // Do more work...
    if (validation_failed) {
        return -1;  // Forgot again.
    }

    fclose(f);
    return 0;
}

Every early return is a potential resource leak. You have to remember to call fclose() on every exit path. As functions grow more complex, with more error conditions and nested resources, this becomes a maintenance nightmare. You either end up with deeply nested code trying to avoid early returns, or a tangle of goto statements jumping to cleanup labels.

RAII addresses this by making cleanup automatic. The resource is released when execution leaves the scope, regardless of how it leaves—normal return, early return, or error.

RAII in C++: The Automatic Version

In C++, destructors make RAII straightforward. When an object goes out of scope, its destructor runs automatically:

// C++ version - destructor handles cleanup
void process_config(const char *filename) {
    std::ifstream file(filename);  // Constructor opens the file

    if (parse_failed) return;      // Destructor closes file automatically
    if (validation_failed) return; // Destructor closes file automatically

    // Normal exit - destructor still closes file automatically
}

You literally cannot forget to close the file. The language handles it.

C Doesn't Have Destructors

C doesn't have destructors, so we can't get truly automatic cleanup. But we can still apply the RAII principle by being disciplined about how we structure code. The goal is to make resource lifetimes obvious and cleanup hard to forget.

There are a few approaches, each with trade-offs.

Approach 1: The Cleanup Label Pattern

This isn't pure RAII, but it's a common C idiom that achieves similar goals. You use a single cleanup section at the end of the function and goto to reach it from any error path:

int process_config(const char *filename) {
    int result = -1;          // Assume failure
    FILE *f = NULL;           // Initialise to NULL so cleanup is safe
    char *buffer = NULL;

    // Acquire resources
    f = fopen(filename, "r");
    if (!f) goto cleanup;

    buffer = malloc(1024);
    if (!buffer) goto cleanup;

    // Do work...
    if (parse_failed) goto cleanup;

    // More work...
    if (validation_failed) goto cleanup;

    // Success
    result = 0;

cleanup:
    // Release resources in reverse order of acquisition
    free(buffer);       // free(NULL) is safe, does nothing
    if (f) fclose(f);   // fclose(NULL) is not safe, so we check

    return result;
}

This centralises cleanup in one place. You can't accidentally skip it because every exit path goes through the same label. The resources are initialised to safe values (NULL) at the top, so cleanup code can run safely even if acquisition failed partway through.

If you've ever looked at kernel code and wondered why Linus Torvalds, a man with strong opinions about code quality, tolerates goto statements everywhere, this is why. It's a deliberate pattern that's survived decades of battle-testing in one of the most critical codebases on Earth.

Approach 2: Wrapper Structs with Init/Destroy Functions

A more structured approach is to create types that bundle a resource with functions to acquire and release it. This is closer to the spirit of RAII:

// file_handle.h
typedef struct {
    FILE *fp;
    int valid;
} FileHandle;

// Initialise the handle and open the file (acquisition)
int file_handle_init(FileHandle *handle, const char *filename, const char *mode) {
    handle->fp = fopen(filename, mode);
    handle->valid = (handle->fp != NULL);
    return handle->valid ? 0 : -1;
}

// Close the file and clean up (release)
void file_handle_destroy(FileHandle *handle) {
    if (handle->valid && handle->fp) {
        fclose(handle->fp);
        handle->fp = NULL;
        handle->valid = 0;
    }
}

// Helper to check if the handle is usable
int file_handle_is_valid(const FileHandle *handle) {
    return handle->valid;
}

Now your function looks like this:

int process_config(const char *filename) {
    FileHandle handle;

    if (file_handle_init(&handle, filename, "r") != 0) {
        return -1;
    }

    // Do work with handle.fp...

    file_handle_destroy(&handle);  // You still have to remember this
    return 0;
}

This is cleaner, but you still have to remember to call the destroy function. The benefit is that the pairing is obvious—init and destroy go together, and code review can easily spot a missing destroy.

Approach 3: Scope-Bound Resource Management with GCC/Clang

If you're using GCC or Clang, there's a feature that almost nobody talks about, buried in the compiler documentation, that gives you proper RAII in C. It's been there for years. I'm genuinely not sure why it isn't more widely known.

It's the cleanup attribute. It lets you specify a function to call automatically when a variable goes out of scope:

// Define a cleanup function
static void auto_close_file(FILE **fp) {
    if (*fp) {
        fclose(*fp);
    }
}

// Macro to make it easy to use
#define AUTO_CLOSE __attribute__((cleanup(auto_close_file)))

int process_config(const char *filename) {
    AUTO_CLOSE FILE *f = fopen(filename, "r");
    if (!f) return -1;

    if (parse_failed) {
        return -1;  // f is automatically closed!
    }

    if (validation_failed) {
        return -1;  // f is automatically closed!
    }

    // Normal return - f is automatically closed!
    return 0;
}

This is proper RAII in C. The file is closed automatically when f goes out of scope, no matter how that happens.

Notice the cleanup function takes FILE **, not FILE *. That trips people up the first time. The cleanup function receives a pointer to the variable itself, so it can access (and modify) the variable's value.

You can create a family of these for different resource types:

// For malloc'd memory
static void auto_free(void **ptr) {
    free(*ptr);
}
#define AUTO_FREE __attribute__((cleanup(auto_free)))

// For file descriptors
static void auto_close_fd(int *fd) {
    if (*fd >= 0) close(*fd);
}
#define AUTO_CLOSE_FD __attribute__((cleanup(auto_close_fd)))

// For mutexes
static void auto_unlock(pthread_mutex_t **mutex) {
    pthread_mutex_unlock(*mutex);
}
#define AUTO_UNLOCK __attribute__((cleanup(auto_unlock)))

Usage becomes very clean:

int do_something(void) {
    AUTO_FREE char *buffer = malloc(1024);
    AUTO_CLOSE FILE *f = fopen("data.txt", "r");
    AUTO_CLOSE_FD int sock = socket(AF_INET, SOCK_STREAM, 0);

    if (!buffer || !f || sock < 0) {
        return -1;  // Everything cleaned up automatically
    }

    // Work with resources...

    return 0;  // Everything cleaned up automatically
}

The catch? It's a compiler extension, not standard C. If your code needs to compile on some obscure embedded compiler from 2003, you're out of luck. But if you're targeting GCC or Clang—which covers Linux, macOS, BSDs, and most ARM toolchains—you've had this superpower available the whole time.

Approach 4: Scope Guards with Macros

This next technique is either brilliant or cursed, depending on your tolerance for macro wizardry. I'll show it to you, but I'm not sure I'd recommend it.

You can use macros to create a scope that handles cleanup:

#define SCOPED_FILE(var, filename, mode) \
    for (FILE *var = fopen(filename, mode), *_once = (FILE*)1; \
         _once && var; \
         _once = NULL, fclose(var))

void process_config(const char *filename) {
    SCOPED_FILE(f, filename, "r") {
        // Use f here...
        // File is closed when this block exits
    }
    // f no longer exists here
}

The for loop runs exactly once (controlled by the _once variable), and the cleanup happens in the loop's increment expression. It works, but I'd reach for the cleanup attribute if it's available.

The Underlying Principle

Whichever approach you use, the principle remains the same: make resource lifetimes explicit, tie acquisition and release together, and structure your code so that cleanup is hard to skip. In C++, the language enforces this through destructors. In C, you enforce it through convention, discipline, and sometimes compiler extensions.

The cleanup attribute gives you the closest thing to automatic RAII in C. The goto-cleanup pattern is portable and battle-tested. Wrapper structs with init/destroy functions make the resource lifecycle explicit even if the calls aren't automatic. Pick the approach that fits your constraints and stick with it consistently.

C doesn't hold your hand. It never has. But that doesn't mean you have to juggle resources manually and hope you never drop one. RAII is a principle, not a language feature, and with a bit of structure, you can make cleanup something you rarely think about because it's already handled.

As always, thanks for joining me on this journey into embedded development!

But how does writing to an address actually do something?

The Core Idea

Your microcontroller has an address space. On a 32-bit chip, this runs from 0x00000000 to 0xFFFFFFFF. Some addresses point to RAM, where your variables live. Some point to flash, where your program code lives.

And some addresses don't point to memory at all. They point to hardware. Read that again if you're coming from application development (as I am), because this probably sounds strange.

When you read from or write to one of these special addresses, you're communicating with a peripheral. Writing a value might turn on an LED, change a timer's speed, or send a byte out of a serial port. Reading a value might tell you whether a button is pressed or whether a transmission has completed.

This is memory-mapped I/O. Hardware peripherals are "mapped" into the memory address space, and you interact with them using ordinary reads and writes.

A Concrete Example: Turning on an LED

Say you have an LED connected to pin 5 of GPIO port A on an STM32 microcontroller. The GPIO peripheral has several registers, and the datasheet tells you that GPIO port A's registers start at address 0x40020000. A register is just a small piece of memory inside the peripheral that controls or reflects some aspect of its behaviour. The Output Data Register (ODR), which controls the pin states, is at offset 0x14 from that base.

In C:

// The ODR register for GPIOA is at address 0x40020014.
// We cast this address to a pointer, then dereference it so we can
// read and write it like a variable.
#define GPIOA_ODR (*(volatile uint32_t *)0x40020014)

// Turn on the LED by setting bit 5
GPIOA_ODR |= (1 << 5);

// Turn off the LED by clearing bit 5
GPIOA_ODR &= ~(1 << 5);

When you write GPIOA_ODR |= (1 << 5), the compiler generates a read from address 0x40020014, an OR operation, and a write back to that address. That write physically changes the voltage on pin 5, which lights up your LED.

Why "Volatile" Matters

Notice the volatile keyword. This is critical for MMIO, and leaving it out will cause bugs.

The compiler tries to optimise your code. One optimisation is caching values in CPU registers rather than reading from memory repeatedly. Without volatile, the compiler becomes an overly helpful optimiser that's about to ruin your day.

Consider this loop that waits for a button press:

// Wait until bit 0 of the input register goes high
while ((GPIOA_IDR & (1 << 0)) == 0) {
    // Waiting...
}

The compiler looks at your loop, sees you reading the same address repeatedly, and thinks: "Why read this a thousand times? I'll just cache it." Reasonable! Except the hardware doesn't care what the compiler thinks. Your code effectively becomes:

// BAD: Compiler "optimises" by caching the value
uint32_t cached_value = GPIOA_IDR;  // Read once
while ((cached_value & (1 << 0)) == 0) {
    // This loops forever! cached_value never updates,
    // even when the button is pressed.
}

But GPIOA_IDR is a hardware register. Its value changes when someone presses the button. Your code would never see that change because it's looking at a stale copy.

The volatile keyword tells the compiler: "This value can change outside the program's control. Read it fresh every single time." With volatile, the compiler generates an actual memory read on every loop iteration.

Structuring Register Access

Writing raw addresses everywhere gets messy. A cleaner approach is to define a struct that matches the peripheral's register layout:

// This struct must match the hardware register layout exactly.
// Each field corresponds to a register at a specific offset.
// The order matters: the compiler lays out fields sequentially,
// so MODER is at offset 0, OTYPER at offset 4, and so on.
typedef struct {
    volatile uint32_t MODER;    // Offset 0x00: Mode register
    volatile uint32_t OTYPER;   // Offset 0x04: Output type register
    volatile uint32_t OSPEEDR;  // Offset 0x08: Output speed register
    volatile uint32_t PUPDR;    // Offset 0x0C: Pull-up/pull-down register
    volatile uint32_t IDR;      // Offset 0x10: Input data register
    volatile uint32_t ODR;      // Offset 0x14: Output data register
    volatile uint32_t BSRR;     // Offset 0x18: Bit set/reset register
    volatile uint32_t LCKR;     // Offset 0x1C: Lock register
    volatile uint32_t AFRL;     // Offset 0x20: Alternate function low
    volatile uint32_t AFRH;     // Offset 0x24: Alternate function high
} GPIO_TypeDef;

// Create pointers to each GPIO port at their base addresses
#define GPIOA ((GPIO_TypeDef *)0x40020000)
#define GPIOB ((GPIO_TypeDef *)0x40020400)
#define GPIOC ((GPIO_TypeDef *)0x40020800)

Now you can write:

GPIOA->ODR |= (1 << 5);   // Set pin 5 high

if (GPIOB->IDR & (1 << 0)) {
    // Pin 0 on port B is high
}

This is exactly what vendor-provided header files like stm32f4xx.h give you. The manufacturer has already turned the datasheet into C structures—which, when you think about it, is a pretty wild artefact. Thousands of pages of hardware documentation, distilled into structs and macros.

Read-Modify-Write: A Subtle Trap

When you write GPIOA->ODR |= (1 << 5), three things happen: read the current value, OR in your bit, write the result back. This is called read-modify-write, and it can cause problems.

If an interrupt fires between the read and the write, and the interrupt handler modifies the same register, your write will overwrite the handler's changes.

The read-modify-write trap catches everyone eventually. My first encounter was a motor controller that would occasionally ignore commands, but only when the system was under load. Took me ages to realise an interrupt was racing against my main loop.

Many peripherals provide registers that avoid this. On STM32, the GPIO has a Bit Set/Reset Register (BSRR) that lets you set or clear individual pins with a single write:

// Set pin 5 high. This is a single write, no read required.
// Only pin 5 is affected; other pins are unchanged.
GPIOA->BSRR = (1 << 5);

// Set pin 5 low. The lower 16 bits of BSRR set pins,
// the upper 16 bits clear pins. Pin 5's clear bit is bit 21 (5 + 16).
GPIOA->BSRR = (1 << 21);

This is faster and avoids race conditions with interrupt handlers. There's something deeply satisfying when hardware designers give you atomic operations like this. They've been bitten by the same bugs and decided to solve them in silicon.

A Complete Example: Blinking an LED

Here's a standalone example showing what it takes to blink an LED on PA5 (port A, pin 5) on an STM32F4:

#include <stdint.h>

// Register structures (simplified from the full definitions)
typedef struct {
    volatile uint32_t CR;
    volatile uint32_t PLLCFGR;
    volatile uint32_t CFGR;
    volatile uint32_t CIR;
    volatile uint32_t AHB1RSTR;
    volatile uint32_t AHB2RSTR;
    volatile uint32_t AHB3RSTR;
    volatile uint32_t RESERVED0;
    volatile uint32_t APB1RSTR;
    volatile uint32_t APB2RSTR;
    volatile uint32_t RESERVED1[2];
    volatile uint32_t AHB1ENR;   // Offset 0x30: enables clocks to peripherals
} RCC_TypeDef;

typedef struct {
    volatile uint32_t MODER;
    volatile uint32_t OTYPER;
    volatile uint32_t OSPEEDR;
    volatile uint32_t PUPDR;
    volatile uint32_t IDR;
    volatile uint32_t ODR;
    volatile uint32_t BSRR;
} GPIO_TypeDef;

#define RCC   ((RCC_TypeDef *)0x40023800)
#define GPIOA ((GPIO_TypeDef *)0x40020000)

// Simple delay loop. The 'volatile' prevents the compiler from
// optimising away the entire loop.
void delay(volatile uint32_t count) {
    while (count--);
}

int main(void) {
    // Step 1: Enable the clock to GPIO port A.
    // Peripherals are powered down by default to save energy.
    // Bit 0 of AHB1ENR controls the GPIOA clock.
    // Note: This is a read-modify-write, but there's no atomic alternative
    // for clock enables. Safe here since interrupts aren't enabled yet.
    RCC->AHB1ENR |= (1 << 0);

    // Step 2: Configure PA5 as a general-purpose output.
    // The MODER register uses 2 bits per pin:
    //   00 = input
    //   01 = general-purpose output
    //   10 = alternate function
    //   11 = analog
    // Pin 5 is controlled by bits 10 and 11 (pin number * 2).
    GPIOA->MODER &= ~(0x3 << 10);  // Clear both bits first
    GPIOA->MODER |= (0x1 << 10);   // Set to output mode

    // Step 3: Blink forever
    while (1) {
        // Set PA5 high (LED on).
        // Writing to the lower 16 bits of BSRR sets pins.
        GPIOA->BSRR = (1 << 5);
        delay(500000);

        // Set PA5 low (LED off).
        // Writing to the upper 16 bits of BSRR clears pins.
        // Bit 21 = bit 5 + 16.
        GPIOA->BSRR = (1 << 21);
        delay(500000);
    }

    return 0;
}

Every step here is a write to a memory-mapped register. Enabling the clock, configuring the pin mode, toggling the output. It's all done by writing specific values to specific addresses.

Why This Matters

Understanding MMIO is foundational. When you use a HAL function like HAL_GPIO_WritePin(), it's doing exactly this underneath. When you configure a timer, a DMA controller, or an ADC, you're manipulating registers through MMIO.

Knowing what's really happening lets you configure peripherals that your HAL doesn't support, debug problems when abstractions behave unexpectedly, optimise critical code paths, and understand why details like volatile and register access order matter.

The address space is your interface to the hardware. Every peripheral you'll ever configure, every sensor you'll read, it all comes down to reading and writing specific addresses. Memory-mapped I/O isn't just a technique. It's the bridge between your code and the physical world.

As always, thanks for joining me on this journey into embedded development!

The Problem We're Solving

Imagine you've written a useful function for calculating distances:

// In geometry.c
float distance(float x1, float y1, float x2, float y2) {
    float dx = x2 - x1;
    float dy = y2 - y1;
    return sqrt(dx * dx + dy * dy);
}

Now you want to use this function in another file, main.c. The C compiler processes each file independently before the linker combines them, so when it compiles main.c, it has no idea that distance exists over in geometry.c. You need to tell the compiler about the function before you can call it.

You could just copy the declaration into main.c:

// In main.c
float distance(float x1, float y1, float x2, float y2);  // Declaration

int main(void) {
    float d = distance(0, 0, 3, 4);  // Now the compiler knows about it
    return 0;
}

This works, but it doesn't scale. If you use distance in ten different files, you've got ten copies of the declaration. If you later change the function signature — say, adding a third dimension — you have to update all ten files. Miss one and you've got a bug that might not show up until runtime.

Header files solve this by giving you one place to put declarations that multiple files can share.

Headers: The Public Interface

A header file (.h) contains declarations: function prototypes, type definitions, macros, and extern variable declarations. It describes what exists without providing the actual implementation.

// geometry.h
#ifndef GEOMETRY_H
#define GEOMETRY_H

// Function declarations - the public interface
float distance(float x1, float y1, float x2, float y2);
float triangle_area(float base, float height);
float circle_area(float radius);

#endif

This file says "these functions exist and here's how to call them." It doesn't say how they work. That's not the header's job.

Implementation Files: The Actual Code

An implementation file (.c) contains definitions: the actual function bodies, variable initialisations, and any private helper functions. It includes its own header to ensure the declarations and definitions stay in sync.

// geometry.c
#include <math.h>
#include "geometry.h"  // Include our own header

// Private helper function - only visible in this file
static float square(float x) {
    return x * x;
}

// Public function definitions
float distance(float x1, float y1, float x2, float y2) {
    return sqrt(square(x2 - x1) + square(y2 - y1));
}

float triangle_area(float base, float height) {
    return 0.5f * base * height;
}

float circle_area(float radius) {
    return 3.14159f * square(radius);
}

Notice that geometry.c includes geometry.h. This is good practice because the compiler will catch any mismatch between your declarations and definitions. If you declare float distance(float, float, float, float) in the header but define double distance(...) in the source file, the compiler will complain.

Using the Header

Any file that wants to use your geometry functions just includes the header:

// main.c
#include <stdio.h>
#include "geometry.h"  // Now we know about distance, triangle_area, etc.

int main(void) {
    float d = distance(0, 0, 3, 4);
    printf("Distance: %.2f\n", d);  // Prints 5.00

    float area = circle_area(10);
    printf("Circle area: %.2f\n", area);

    return 0;
}

The #include "geometry.h" directive tells the preprocessor to paste the contents of that file right here. After preprocessing, the compiler sees the function declarations and knows how to handle the calls. Later, the linker connects these calls to the actual function definitions in geometry.o.

Header Guards: Preventing Double Inclusion

You might have noticed these lines wrapping the header content:

#ifndef GEOMETRY_H
#define GEOMETRY_H
// ... header contents ...
#endif

These are header guards, and they solve a subtle but important problem: what happens if a header gets included twice?

This can happen more easily than you might think. Say main.c includes both geometry.h and physics.h, and physics.h itself includes geometry.h because it uses some geometry functions internally:

// main.c
#include "geometry.h"
#include "physics.h"  // This also includes geometry.h internally

Without header guards, the contents of geometry.h would be pasted twice. For function declarations, this might just cause a warning. But if the header defines a struct or a typedef, you'd get a "redefinition" error — the compiler sees the same type being defined twice. Header guards prevent this.

The first time the preprocessor encounters #include "geometry.h", it processes these lines:

#ifndef GEOMETRY_H      // Is GEOMETRY_H undefined? Yes, so continue.
#define GEOMETRY_H      // Define GEOMETRY_H (now it exists).
// ... contents ...     // Process the header contents.
#endif                  // End of the conditional block.

If the same header gets included again later in the same translation unit:

#ifndef GEOMETRY_H      // Is GEOMETRY_H undefined? No, it's defined now.
                        // Skip everything until #endif.
#endif

The second inclusion is effectively empty. The header contents only appear once, no matter how many times the header is included.

The name you use (like GEOMETRY_H) should be unique. The convention is to use the filename in uppercase with underscores replacing dots and any path separators. Some projects add a prefix or suffix to further reduce collision risk.

Angle Brackets vs Quotes

You'll notice two styles of include:

#include <stdio.h>      // Angle brackets
#include "geometry.h"   // Quotes

Angle brackets tell the preprocessor to look in the system include directories — places where the standard library headers live. Quotes tell it to look in the current directory first (or directories you specify), then fall back to system directories.

The rule of thumb: use angle brackets for standard library and system headers, quotes for your own headers and third-party libraries you've added to your project.

What Goes Where?

Here's a quick guide for deciding what belongs in headers versus implementation files.

Headers should contain function declarations (prototypes), struct and union definitions, typedef declarations, enum definitions, macro definitions, extern variable declarations, and static inline function definitions (small functions meant to be inlined).

Implementation files should contain function definitions (the actual code), static (file-private) functions and variables, and the definitions of extern variables declared in headers.

The principle is that headers describe the interface while implementation files provide the behaviour. Anything that other files need to know about goes in the header. Anything that's an internal implementation detail stays in the .c file.

A Complete Example

Let's put it all together with a small string utilities module.

// string_utils.h
#ifndef STRING_UTILS_H
#define STRING_UTILS_H

#include <stddef.h>  // For size_t

// Check if a string is empty or NULL
int string_is_empty(const char *str);

// Count occurrences of a character in a string
size_t string_count_char(const char *str, char c);

// Check if string starts with a given prefix
int string_starts_with(const char *str, const char *prefix);

#endif

// string_utils.c
#include <string.h>
#include "string_utils.h"

int string_is_empty(const char *str) {
    return str == NULL || str[0] == '\0';
}

size_t string_count_char(const char *str, char c) {
    if (str == NULL) return 0;

    size_t count = 0;
    while (*str) {
        if (*str == c) count++;
        str++;
    }
    return count;
}

int string_starts_with(const char *str, const char *prefix) {
    if (str == NULL || prefix == NULL) return 0;
    return strncmp(str, prefix, strlen(prefix)) == 0;
}

// main.c
#include <stdio.h>
#include "string_utils.h"

int main(void) {
    const char *text = "hello, world";

    if (!string_is_empty(text)) {
        printf("The string has %zu 'l' characters\n",
               string_count_char(text, 'l'));  // Prints 3
    }

    if (string_starts_with(text, "hello")) {
        printf("It starts with 'hello'\n");
    }

    return 0;
}

To compile this, you'd typically run:

gcc -c string_utils.c -o string_utils.o
gcc -c main.c -o main.o
gcc string_utils.o main.o -o program

Or more simply:

gcc string_utils.c main.c -o program

The compiler compiles each .c file into an object file, then the linker combines them. The header file is never compiled directly — it's just pasted into whichever .c files include it.

Why This Matters

The header/implementation split does several things for you. It keeps your public interface separate from implementation details, so users of your code only see what they need. It enables separate compilation, so changing one .c file doesn't require recompiling everything. It provides a natural place for documentation — the header shows what functions are available and what they do. And it scales cleanly as projects grow, because dependencies are explicit and manageable.

This pattern is so fundamental to C that you'll see it everywhere: in the standard library, in operating system APIs, in every library you'll ever use. Get comfortable with it, and structuring C projects becomes straightforward.

As always, thanks for joining me on this journey into embedded development!

The Basic Structure of a Function

A function in C has four parts: a return type, a name, a parameter list, and a body.

int add(int a, int b) {
    int result = a + b;
    return result;
}

• The return type comes first. In this case it's int, meaning the function will produce an integer value that gets sent back to whoever called it. If a function doesn't need to return anything, you use void as the return type.

• The name comes next. This is how you'll refer to the function when you want to call it. Function names follow the same rules as variable names: they can contain letters, numbers, and underscores, but can't start with a number.

• The parameter list sits inside the parentheses. These are the inputs to the function. There are the values that get passed in when you call it. Each parameter has a type and a name. If a function takes no parameters, you can write void inside the parentheses (or leave them empty, though void is more explicit).

• The body is everything between the curly braces. This is the code that runs when the function is called. If the function has a non-void return type, the body must include a return statement that provides a value of the correct type.

Calling a Function

Once you've defined a function, you call it by using its name followed by arguments in parentheses:

int sum = add(5, 3);  // sum is now 8

The arguments 5 and 3 get copied into the parameters a and b. The function runs, computes the result, and returns 8. That returned value gets assigned to sum.

This copying is important. C passes arguments by value, meaning the function receives copies of the values, not the original variables. If you modify a parameter inside the function, the original variable outside the function is unaffected:

void try_to_modify(int x) {
    x = 100;  // This only changes the local copy
}

int main(void) {
    int num = 5;
    try_to_modify(num);
    // num is still 5 here, not 100
    return 0;
}

If you need a function to modify something outside itself, you pass a pointer to it. But that's a topic for another post.

Return Types and void

The return type specifies what kind of value the function produces. It can be any type: int, float, char, a pointer, a struct, and so on.

// Returns an integer
int square(int x) {
    return x * x;
}

// Returns a floating-point number
float divide(float a, float b) {
    return a / b;
}

// Returns a pointer to a character (a string)
char *get_greeting(void) {
    return "Hello, world!";
}

When a function doesn't need to return anything, you declare it with void:

void print_hello(void) {
    printf("Hello!\n");
    // No return statement needed, or you can write: return;
}

You can include a bare return; statement in a void function to exit early, but you don't have to. The function will return automatically when it reaches the closing brace.

One thing to watch out for: if you declare a function with a non-void return type, you must return a value on every code path. If you forget, the compiler might warn you, but the behaviour is undefined — the caller will receive garbage.

int risky(int x) {
    if (x > 0) {
        return x * 2;
    }
    // Oops! What happens if x <= 0? No return statement.
    // This is undefined behaviour.
}

Parameters: Inputs to Your Function

Parameters let you pass data into a function. You can have as many as you need, separated by commas:

void print_rectangle_info(int width, int height, const char *label) {
    int area = width * height;
    printf("%s: %d x %d = %d\n", label, width, height, area);
}

Each parameter is essentially a local variable that gets initialised with the value you pass when calling the function.

If a function takes no parameters, you should write void in the parameter list:

int get_answer(void) {
    return 42;
}

There's a subtle difference between int get_answer(void) and int get_answer(). The first explicitly says "this function takes no arguments." The second, in C (unlike C++), means "this function takes an unspecified number of arguments" — it's an old-style declaration that doesn't prototype the parameters. For clarity and safety, always use void when you mean no parameters.

Declaration vs Definition

This is a distinction that trips up newcomers, but it's important for understanding how C programs are structured.

A function definition is the complete function: return type, name, parameters, and body. It's the actual implementation.

// This is a definition - it includes the body
int multiply(int a, int b) {
    return a * b;
}

A function declaration (also called a prototype) just tells the compiler that a function exists and what its signature looks like. It doesn't include the body:

// This is a declaration - no body, ends with a semicolon
int multiply(int a, int b);

Why would you need both? Because the C compiler processes your code from top to bottom. If you try to call a function before the compiler has seen it, it won't know what parameters it takes or what it returns.

#include <stdio.h>

int main(void) {
    int result = multiply(3, 4);  // Error! Compiler hasn't seen multiply yet.
    printf("%d\n", result);
    return 0;
}

int multiply(int a, int b) {
    return a * b;
}

You have two options. Either move the function definition above main so the compiler sees it first, or provide a declaration before main and put the definition wherever you like:

#include <stdio.h>

// Declaration: tells the compiler what multiply looks like
int multiply(int a, int b);

int main(void) {
    int result = multiply(3, 4);  // Now this works
    printf("%d\n", result);
    return 0;
}

// Definition: the actual implementation
int multiply(int a, int b) {
    return a * b;
}

For small programs, you might just order your functions so each is defined before it's called. For larger programs, the declaration/definition split becomes essential — you put declarations in header files and definitions in source files. That way, any source file that includes the header knows about the function and can call it, even though the actual code lives elsewhere.

The main Function: Where It All Begins

Every C program must have a function called main. This is the entry point — when you run your program, execution starts at the first line of main.

The main function is special in several ways. It's called by the operating system, not by your code. Its return type is always int, and the value you return becomes the program's exit status: 0 conventionally means success, and non-zero values indicate some kind of error.

There are two valid signatures for main:

// Version 1: takes no arguments
int main(void) {
    // Your program here
    return 0;
}

// Version 2: takes command-line arguments
int main(int argc, char *argv[]) {
    // argc is the number of arguments
    // argv is an array of strings containing the arguments
    return 0;
}

The second version gives you access to command-line arguments. If the user runs ./myprogram hello world, then argc would be 3 (the program name plus two arguments), and argv would contain {"./myprogram", "hello", "world"}.

You might occasionally see void main() in old code or tutorials. This is non-standard. The correct return type for main is int. Some compilers accept void main(), but it's not portable and you shouldn't use it.

One more quirk: main is the only function in C where you can omit the return statement. If you don't explicitly return a value, main implicitly returns 0. This was added in the C99 standard. I'd still recommend including return 0; for clarity, but it's not strictly required.

Why Use Functions?

Functions exist to solve several problems at once.

Code reuse is the obvious benefit. If you need to perform the same operation in multiple places, you write it once as a function and call it wherever needed. If you later need to fix a bug or change the behaviour, you update one place rather than hunting through your code for every copy.

// Without a function: repeated code
float area1 = 3.14159 * radius1 * radius1;
float area2 = 3.14159 * radius2 * radius2;
float area3 = 3.14159 * radius3 * radius3;

// With a function: write once, use anywhere
float circle_area(float radius) {
    return 3.14159f * radius * radius;
}

float area1 = circle_area(radius1);
float area2 = circle_area(radius2);
float area3 = circle_area(radius3);

Abstraction is equally important. Functions let you hide complexity behind a simple interface. When you call printf, you don't need to know how it formats strings or talks to the terminal. You just pass it arguments and it does its job. You can apply the same principle in your own code: write a function that handles the messy details, give it a clear name, and then use it without thinking about what's inside.

Organisation follows naturally. Functions let you break a large program into smaller, manageable pieces. Each function handles one task. This makes code easier to read, easier to test, and easier to maintain. Instead of one long main function with hundreds of lines, you have a collection of focused functions, each doing one thing well.

int main(void) {
    initialise_system();
    load_configuration();

    while (running) {
        process_input();
        update_state();
        render_output();
    }

    cleanup();
    return 0;
}

You can understand the structure of this program without reading the implementation of each function. The names tell you what happens at each step.

The Costs of Functions

Functions aren't free, though the costs are usually small.

There's a calling overhead. When you call a function, the CPU has to save some state, jump to the function's code, pass the arguments, execute the function, and then return. For tiny operations called millions of times in a tight loop, this overhead can matter. In such cases, you might inline the code manually, use the inline keyword as a hint to the compiler, or (more commonly) trust the compiler to make sensible optimisations.

Arguments are copied. Because C passes by value, each argument is copied into the function's parameter. For small types like int or float, this is trivial. For large structs, it can be expensive. That's why you'll often see functions take pointers to large structs rather than the structs themselves:

// Expensive: copies the entire struct
void process_data(struct LargeData data);

// Cheaper: copies only a pointer (8 bytes on 64-bit systems)
void process_data(const struct LargeData *data);

Debugging can sometimes be slightly harder when code is spread across many functions, because you have to trace through multiple call sites. But this is usually outweighed by the clarity that good function decomposition provides.

In practice, you should almost always prefer using functions. The benefits of clarity, reuse, and maintainability far outweigh the minor performance costs. Modern compilers are very good at optimising function calls, and you should only avoid them when profiling shows a genuine bottleneck.

Putting It All Together

Here's a complete example that demonstrates declarations, definitions, multiple functions, and main:

#include <stdio.h>

// Function declarations (prototypes)
// These tell the compiler what functions exist and their signatures
float celsius_to_fahrenheit(float celsius);
float fahrenheit_to_celsius(float fahrenheit);
void print_conversion(float temp, char from_unit);

int main(void) {
    float temp = 100.0f;

    // Convert boiling point of water both ways
    print_conversion(temp, 'C');
    print_conversion(212.0f, 'F');

    return 0;
}

// Function definitions (implementations)

float celsius_to_fahrenheit(float celsius) {
    return (celsius * 9.0f / 5.0f) + 32.0f;
}

float fahrenheit_to_celsius(float fahrenheit) {
    return (fahrenheit - 32.0f) * 5.0f / 9.0f;
}

void print_conversion(float temp, char from_unit) {
    if (from_unit == 'C') {
        float result = celsius_to_fahrenheit(temp);
        printf("%.1f°C = %.1f°F\n", temp, result);
    } else if (from_unit == 'F') {
        float result = fahrenheit_to_celsius(temp);
        printf("%.1f°F = %.1f°C\n", temp, result);
    } else {
        printf("Unknown unit: %c\n", from_unit);
    }
}

The declarations at the top let us define main before the other functions. Each function has a single, clear purpose. The main function reads almost like prose — you can see what the program does without diving into implementation details. This is what good use of functions looks like.

Functions are simple in concept but foundational in practice. Master them, and you have the tools to write clear, organised, maintainable C code.

In object-oriented languages, this usually involves classes and inheritance. In C, we achieve the same thing with function pointers and structs. The principle is identical — only the implementation differs.

A Practical Scenario

Let's say you're building an audio application. You've defined a clean interface for audio sources:

// audio_source.h
#ifndef AUDIO_SOURCE_H
#define AUDIO_SOURCE_H

#include <stddef.h>

// Your application's audio source interface
typedef struct AudioSource {
    // Read samples into buffer, return number of samples read
    size_t (*read_samples)(struct AudioSource *self, float *buffer, size_t count);

    // Get the sample rate
    int (*get_sample_rate)(struct AudioSource *self);

    // Clean up resources
    void (*destroy)(struct AudioSource *self);

    // Pointer to implementation-specific data
    void *impl_data;
} AudioSource;

#endif

Your audio pipeline expects AudioSource objects. It calls read_samples() to pull audio data, and everything works nicely.

:::note In C, a function's name is actually a pointer to where that function's code lives in memory. When you write printf("hello"), you're calling the function via its address. Function pointers let you store that address in a variable, pass it around, and call whatever function it happens to point to. The struct in the above example stores three function pointers: read_samples, get_sample_rate, and destroy; which means each AudioSource instance can have its own set of functions wired up. When you create an MP3 adapter, you point these at your MP3-specific functions. When you create a WAV adapter, you point them at WAV-specific functions. The calling code doesn't know or care which functions are actually being called; it just calls source->read_samples(source, buffer, count) and the right thing happens.

The impl_data field is the other half of the puzzle. It's a void *, which means it can point to anything. Each adapter uses this to store whatever internal state it needs — the MP3 adapter stores a pointer to its MP3Decoder, the WAV adapter might store file handle and format information, and so on. When one of the function pointers is called, it casts impl_data back to the appropriate type and uses it.

This is how you get polymorphism in C: a generic struct that presents a uniform interface, combined with a void pointer that lets each implementation carry its own specific data. The consumer of the interface just sees AudioSource and calls methods on it; the implementation details are hidden behind those function pointers and that void pointer. :::

Now you want to add support for a third-party MP3 decoding library. The problem is that this library has its own interface that looks nothing like yours:

// Hypothetical third-party MP3 library
typedef struct {
    void *internal_state;
    int channels;
    int sample_rate;
} MP3Decoder;

// Their functions
MP3Decoder *mp3_open(const char *filename);
int mp3_decode_frame(MP3Decoder *dec, short *pcm_out, int max_samples);
void mp3_close(MP3Decoder *dec);

The library uses short samples instead of float. It has different function names. The structure is completely different. You can't pass an MP3Decoder to code expecting an AudioSource.

You could modify your audio pipeline to handle MP3Decoder as a special case, but that's messy. You could modify the third-party library, but you don't control it. The adapter pattern gives you a third option: wrap the incompatible interface to make it compatible.

Building the Adapter

The adapter needs to present the AudioSource interface while internally using the MP3Decoder. Here's how:

// mp3_adapter.c
#include <stdlib.h>
#include "audio_source.h"
#include "mp3_library.h"  // The third-party library

// Internal structure holding the adapted decoder
typedef struct {
    MP3Decoder *decoder;
} MP3AdapterData;

// Adapter implementation of read_samples
static size_t mp3_adapter_read(AudioSource *self, float *buffer, size_t count) {
    MP3AdapterData *data = (MP3AdapterData *)self->impl_data;

    // Temporary buffer for the library's short samples
    short *temp = malloc(count * sizeof(short));
    if (!temp) return 0;

    // Call the third-party library
    int samples_read = mp3_decode_frame(data->decoder, temp, (int)count);

    // Convert from short (-32768 to 32767) to float (-1.0 to 1.0)
    for (int i = 0; i < samples_read; i++) {
        buffer[i] = temp[i] / 32768.0f;
    }

    free(temp);
    return (size_t)samples_read;
}

// Adapter implementation of get_sample_rate
static int mp3_adapter_get_sample_rate(AudioSource *self) {
    MP3AdapterData *data = (MP3AdapterData *)self->impl_data;
    return data->decoder->sample_rate;
}

// Adapter implementation of destroy
static void mp3_adapter_destroy(AudioSource *self) {
    MP3AdapterData *data = (MP3AdapterData *)self->impl_data;
    mp3_close(data->decoder);  // Clean up the third-party decoder
    free(data);                 // Clean up our adapter data
    free(self);                 // Clean up the AudioSource struct
}

// Factory function: create an AudioSource from an MP3 file
AudioSource *audio_source_from_mp3(const char *filename) {
    // Open the MP3 using the third-party library
    MP3Decoder *decoder = mp3_open(filename);
    if (!decoder) return NULL;

    // Allocate our adapter data
    MP3AdapterData *data = malloc(sizeof(MP3AdapterData));
    if (!data) {
        mp3_close(decoder);
        return NULL;
    }
    data->decoder = decoder;

    // Allocate and populate the AudioSource interface
    AudioSource *source = malloc(sizeof(AudioSource));
    if (!source) {
        mp3_close(decoder);
        free(data);
        return NULL;
    }

    // Wire up the function pointers
    source->read_samples = mp3_adapter_read;
    source->get_sample_rate = mp3_adapter_get_sample_rate;
    source->destroy = mp3_adapter_destroy;
    source->impl_data = data;

    return source;
}

Now your audio pipeline can use MP3 files without knowing anything about the MP3 library:

// main.c
#include "audio_source.h"

// Declared in mp3_adapter.c
AudioSource *audio_source_from_mp3(const char *filename);

void process_audio(AudioSource *source) {
    float buffer[1024];
    size_t samples;

    while ((samples = source->read_samples(source, buffer, 1024)) > 0) {
        // Process the audio...
    }
}

int main(void) {
    AudioSource *source = audio_source_from_mp3("song.mp3");
    if (source) {
        process_audio(source);  // Works with any AudioSource
        source->destroy(source);
    }
    return 0;
}

What Makes This an Adapter

The key elements are clear if you look at what each piece is doing:

• The target interface is AudioSource. This is what your existing code expects. You don't want to change it.

• The adaptee is MP3Decoder from the third-party library. This is what you want to use, but it doesn't match your interface.

• The adapter is the combination of MP3AdapterData and the mp3_adapter_* functions. It implements the target interface while internally delegating to the adaptee. The translation logic (converting short to float, mapping function calls etc.) lives here.

• The factory function audio_source_from_mp3() constructs the adapter and wires everything together. Client code just calls this and gets back an AudioSource it can use normally.

Adding More Adapters

The real power shows when you add more formats. Each one gets its own adapter:

// Different factory functions, same return type
AudioSource *audio_source_from_mp3(const char *filename);
AudioSource *audio_source_from_wav(const char *filename);
AudioSource *audio_source_from_flac(const char *filename);
AudioSource *audio_source_from_ogg(const char *filename);

Each adapter wraps a different underlying library, handling whatever quirks that library has. Your audio processing code doesn't care, it just sees AudioSource objects and calls read_samples().

void play_file(const char *filename) {
    AudioSource *source = NULL;

    // Pick the right adapter based on file extension
    if (ends_with(filename, ".mp3")) {
        source = audio_source_from_mp3(filename);
    } else if (ends_with(filename, ".wav")) {
        source = audio_source_from_wav(filename);
    } else if (ends_with(filename, ".flac")) {
        source = audio_source_from_flac(filename);
    }

    if (source) {
        process_audio(source);  // Same code handles all formats
        source->destroy(source);
    }
}

When to Use This Pattern

The adapter pattern is useful when you're integrating third-party libraries that have their own conventions, maintaining backward compatibility with old interfaces while using new implementations, writing plugins or modular systems where components need a uniform interface, or testing code by swapping in mock implementations that conform to the expected interface.

There's also a maintenance benefit: the adapter isolates your code from changes in the underlying system. If the MP3 library releases a new version with a different API, maybe mp3_decode_frame becomes mp3_read_pcm with different parameters, you only need to update the adapter. Every part of your codebase that uses AudioSource remains untouched, because it never knew about the MP3 library in the first place. The adapter acts as a buffer between your code and external dependencies, containing the blast radius of changes.

A Simpler Alternative

This pattern does add a layer of indirection, which has a small cost. Don't use it when a simple wrapper function would suffice, or when you control both sides of the interface and can just make them match directly.

// Simple wrapper, no function pointers
size_t read_mp3_samples(MP3Decoder *dec, float *buffer, size_t count) {
    short temp[count];
    int read = mp3_decode_frame(dec, temp, count);
    for (int i = 0; i < read; i++) {
        buffer[i] = temp[i] / 32768.0f;
    }
    return read;
}

This translates between interfaces without the struct-and-function-pointer machinery. Use the full adapter pattern when you need to treat different implementations uniformly through a common interface; use simple wrappers when you just need to bridge a single gap.

As always, thanks for joining me on this journey into embedded development!

Where Does Dynamic Memory Live?

Your program's memory is divided into several regions. The stack holds local variables and function call information, growing and shrinking automatically as functions are called and return. The heap is different: it's a pool of memory that your program can draw from and return to at will, and it persists until you explicitly free it.

The heap isn't managed by the compiler. It's managed by the allocator, which is a chunk of code (usually part of your C library) that sits between your malloc calls and the operating system.

What malloc Actually Does

When you call malloc, the allocator needs to find a contiguous block of memory large enough for your request. This is trickier than it sounds.

The allocator maintains data structures to track which parts of the heap are in use and which are free. A simple implementation might keep a linked list of free blocks. When you request memory, it walks the list looking for a block that's big enough. Different allocators use different strategies here: first-fit (take the first block that's large enough), best-fit (find the smallest block that's large enough), or more sophisticated approaches.

When the allocator finds a suitable block, it might be larger than you need. If you ask for 100 bytes and there's a free block of 500 bytes, the allocator will often split that block — give you 100 bytes and keep the remaining 400 bytes on the free list for future requests.

Here's the important bit: the allocator typically stores metadata alongside your allocation. If you ask for 100 bytes, the allocator might actually use 108 or 116 bytes internally — the extra space holds information like the size of the allocation, pointers for the free list, or flags. This metadata usually sits just before the pointer you receive. When you call free(ptr), the allocator looks at the bytes just before ptr to figure out how big the block is.

What you think you got:      [---- 100 bytes of usable memory ----]

What's actually there:       [header][---- 100 bytes of usable memory ----]
                                 ^
                                 |
                             size, flags, etc.

This is why freeing an invalid pointer or overwriting memory before your allocation can corrupt the heap — you're trashing the allocator's bookkeeping.

Where Does the Memory Come From?

The allocator itself needs to get memory from somewhere. On Unix-like systems, it typically uses system calls like sbrk or mmap. sbrk extends the heap by moving the "program break", which is the boundary between the heap and unused address space. mmap asks the kernel to map a chunk of memory into your process's address space.

Calling into the kernel is expensive, so allocators don't do it for every malloc. Instead, they request large chunks from the operating system and then carve those chunks up to satisfy individual allocations. When you malloc(100), the allocator might have already obtained a 128KB block from the OS, and it just hands you a piece of that.

What free Actually Does

When you call free(ptr), the allocator marks that block as available for reuse. It reads the metadata to determine the block's size, then adds it back to its free list.

Crucially, free usually doesn't return memory to the operating system. The memory stays in your process's address space, available for future malloc calls. This is why a program's memory usage (as reported by the OS) often doesn't decrease after freeing memory — the allocator is holding onto it in case you need it again soon.

Some allocators will return large blocks to the OS, particularly those allocated with mmap, but smaller allocations typically just go back into the pool.

Fragmentation

Over time, as you allocate and free memory of varying sizes, the heap can become fragmented. You might have plenty of free memory in total, but it's scattered across many small non-contiguous blocks. When you ask for a large allocation, there's no single free block big enough to satisfy it, even though the total free memory exceeds your request.

[used][free 50][used][free 30][used][free 80][used][free 40]

Total free: 200 bytes
Largest contiguous block: 80 bytes

If you request 100 bytes here, you're out of luck as there's no contiguous block large enough. The allocator would need to request more memory from the OS, even though 200 bytes are technically free.

Good allocators use various strategies to combat fragmentation: coalescing adjacent free blocks, using different pools for different allocation sizes, or organising memory in ways that reduce fragmentation in the first place.

Coalescing: Merging Free Blocks

When you free a block, a good allocator checks whether the adjacent blocks are also free. If they are, it merges them into a single larger block. This is called coalescing.

Before free(B):   [A: free][B: used][C: free]
After free(B):    [-- one big free block ---]

Without coalescing, you'd accumulate lots of small free blocks that individually aren't useful for larger allocations. Coalescing helps keep the free list healthy.

Why This Matters

Memory overhead: every allocation costs more than you asked for, because of metadata. Allocating millions of tiny objects is wasteful as you'll pay the overhead on each one.

Performance: allocation isn't free. The allocator has to search for suitable blocks, possibly split them, update its data structures. For performance-critical code, you might want to allocate in bulk or use a custom allocator.

Memory doesn't go down: your program's resident memory can grow but rarely shrinks, because free doesn't return memory to the OS. This isn't a leak, the memory is available for reuse within your process, but it can be surprising.

Corruption is catastrophic: writing past the end of an allocation or freeing the same pointer twice corrupts the allocator's data structures. The program might not crash immediately, but the heap is now in an inconsistent state. Future allocations might return overlapping memory, or the allocator might crash much later, far from the original bug.

A Note on Modern Allocators

Real-world allocators like glibc's ptmalloc, jemalloc, or tcmalloc are significantly more sophisticated than the simple model I've described. They use multiple arenas to reduce contention in multithreaded programs, maintain separate free lists for different size classes, use thread-local caches to avoid locking on every allocation, and employ various clever tricks to improve performance and reduce fragmentation.

But the fundamentals remain the same: carve up memory into blocks, track what's free, satisfy requests from the pool, and try not to fragment things too badly in the process.

As always, thanks for joining me on this journey into embedded development!

Once you understand the difference between a declaration and a definition, extern becomes much clearer.

Declarations vs Definitions

In C, a declaration tells the compiler "this thing exists and has this type." A definition actually creates the thing and allocates storage for it.

For functions, the distinction is obvious:

// Declaration: tells the compiler the function exists
int add(int a, int b);

// Definition: actually implements the function
int add(int a, int b) {
    return a + b;
}

For variables, it's a bit more subtle, and that's where extern comes in.

Extern Variables

Let's say you have a global variable in one file that you want to use in another file.

// config.c
int max_connections = 100;  // This is a definition

You've defined max_connections here. Memory is allocated for it, and it's initialised to 100.

Now, in another file, you want to use this variable:

// server.c
extern int max_connections;  // This is a declaration

void setup_server(void) {
    printf("Max connections: %d\n", max_connections);
}

The extern keyword tells the compiler "there's an int called max_connections somewhere, but not here. Don't allocate storage for it. Just trust me that it exists, and the linker will sort it out."

Without extern, you'd get a problem. If you wrote:

// server.c
int max_connections;  // This is another definition!

Now you've got two definitions of the same variable in two different files. The linker will complain about multiple definitions (or worse, with some linkers and settings, it might silently merge them in ways you don't expect).

The Header File Pattern

In practice, you almost always see extern declarations in header files. This is the standard pattern:

// config.h
#ifndef CONFIG_H
#define CONFIG_H

extern int max_connections;      // Declaration
extern const char *app_name;     // Declaration

#endif

// config.c
#include "config.h"

int max_connections = 100;       // Definition
const char *app_name = "MyApp";  // Definition

// server.c
#include "config.h"

void setup_server(void) {
    // We can use max_connections and app_name here
    printf("%s allows %d connections\n", app_name, max_connections);
}

Any file that includes config.h can use these variables. The actual storage lives in config.c, and everyone else just references it through the extern declarations.

:::note The reason this pattern works is down to how C handles compilation and linking as separate stages. When the compiler processes server.c, it sees #include "config.h", which pastes in the extern int max_connections; declaration. This tells the compiler "there's an integer called max_connections somewhere, and I need to reference it." The compiler doesn't know or care where it actually lives — it just generates code that refers to a symbol called max_connections and trusts that the linker will resolve it later. Meanwhile, when the compiler processes config.c, it sees int max_connections = 100;, which is a definition. This actually allocates four bytes of storage, initialises them to 100, and exports the symbol max_connections so the linker can find it. When you link the object files together, the linker sees that server.o needs a symbol called max_connections, and config.o provides one, so it wires them up. Every reference to max_connections in your entire program now points to that single four-byte location defined in config.c. The header file is just a convenient way to share the declaration across multiple source files — without it, you'd have to manually write extern int max_connections; at the top of every file that needs access to it, which would be tedious and error-prone. :::

This is the C way of having shared global state. Whether you should have shared global state is a different question, but when you need it, this is how you do it.

Extern With Functions (Usually Unnecessary)

Here's something that catches people out: function declarations are implicitly extern.

// These two lines mean exactly the same thing
int add(int a, int b);
extern int add(int a, int b);

The extern keyword on a function declaration is redundant. You'll see it occasionally in older code or in code written by people coming from other languages, but it's not doing anything. Most style guides recommend leaving it off.

This is why function prototypes in header files don't need extern:

// math_utils.h
#ifndef MATH_UTILS_H
#define MATH_UTILS_H

int add(int a, int b);        // extern is implied
int multiply(int a, int b);   // extern is implied

#endif

Variables are different. Without extern, a variable declaration at file scope is a definition (or at least a tentative definition, but let's not go down that rabbit hole just yet).

Extern With Initialisers = That's a Definition

If you try to initialise an extern variable, you're actually defining it:

extern int max_connections = 100;  // This is a definition, despite extern!

Some compilers will warn about this. The extern keyword is essentially being ignored because you're providing an initial value, which means you're defining the variable right here.

:::tip Whether the compiler warns you or not, this is a source of confusion. One you can do without by being explicit: use extern for declarations (no initialiser), and ensure you leave it off for definitions (with or without an initialiser). :::

A Practical Example: Building a Simple Module

Let's put this together with a small example. Say you're writing a logging module.

// logger.h
#ifndef LOGGER_H
#define LOGGER_H

// External variable: current log level
extern int log_level;

// Log level constants
#define LOG_ERROR 0
#define LOG_WARN  1
#define LOG_INFO  2
#define LOG_DEBUG 3

// Function declarations (extern is implied, so we don't write it)
void log_message(int level, const char *message);
void set_log_level(int level);

#endif

// logger.c
#include <stdio.h>
#include "logger.h"

// Definition of the log level variable
int log_level = LOG_INFO;  // Default to INFO

void log_message(int level, const char *message) {
    if (level <= log_level) {
        const char *level_names[] = {"ERROR", "WARN", "INFO", "DEBUG"};
        printf("[%s] %s\n", level_names[level], message);
    }
}

void set_log_level(int level) {
    log_level = level;
}

// main.c
#include "logger.h"

int main(void) {
    log_message(LOG_INFO, "Starting up");

    // We can access log_level directly because of the extern declaration
    if (log_level >= LOG_DEBUG) {
        log_message(LOG_DEBUG, "Debug mode is on");
    }

    set_log_level(LOG_DEBUG);
    log_message(LOG_DEBUG, "Now this will print");

    return 0;
}

The extern int log_level; in the header lets any file that includes logger.h read (or modify) the log level. The actual variable lives in logger.c.

:::note Did you spot any issues with this code example?

This example is fine for demonstrating the extern pattern, but there are a few things you'd want to improve in production code:

1. Exposing log_level directly via extern means any file can modify it without going through set_log_level(), which undermines encapsulation, if you later need to add validation or trigger behaviour when the level changes, you'd have to track down every place that touches the variable directly. Better to make log_level static in logger.c and add a get_log_level() function if external code needs to read it.
2. The #define constants would be cleaner as an enum, which gives you better type safety and more useful information in a debugger.
3. There's no bounds checking when indexing into level_names[], if someone passes an invalid level, you're into undefined behaviour territory.
4. The level_names array is declared inside the function, which means it's technically recreated on each call (though the compiler will likely optimise this away). Declaring it as static const at file scope makes the intent explicit and guarantees single initialisation.

None of these are critical for an example on the extern keyword, but they're worth being aware of as you move toward real-world code. :::

Extern and Static

It's worth noting that extern and static are opposites when applied to global variables and functions.

static means internal linkage: visible only within this file.

extern means external linkage: visible across files, defined elsewhere.

You can't use both on the same declaration. If you write extern static int x;, the compiler will rightly tell you that makes no sense.

Wrapping Up

The extern keyword is fundamentally about separation: declaring something in one place and defining it in another. It's the glue that lets multiple C files share variables.

The key points to remember are that extern on a variable means "this is a declaration, not a definition." On a function, it's redundant since functions are implicitly extern already. And somewhere in your program, every extern variable needs an actual definition without extern.

If you're structuring a C project with multiple files, you'll use this pattern constantly. Declarations with extern go in headers, definitions go in source files, and the linker ties it all together.

As always, thanks for joining me on this journey into embedded development!

1. Static Local Variables

Normally, when a function finishes executing, its local variables disappear. The stack frame gets cleaned up, and those variables cease to exist. Next time you call the function, you start fresh.

A static local variable changes that. It persists between function calls.

#include <stdio.h>

void count_calls(void) {
    static int call_count = 0;  // Initialised once, persists forever
    call_count++;
    printf("This function has been called %d times\n", call_count);
}

int main(void) {
    count_calls();  // Prints: 1
    count_calls();  // Prints: 2
    count_calls();  // Prints: 3
    return 0;
}

The key thing here is that call_count is initialised to zero only once, when the program starts. After that, it just keeps its value between calls. It's not recreated each time the function runs.

Where does it live in memory? Not on the stack. Static local variables are stored in the data segment (or BSS segment if uninitialised), alongside global variables. They have the lifetime of the entire program, but the scope of the function they're declared in.

I find this useful for things like generating unique IDs, caching expensive calculations, or tracking state in a function that needs to remember what happened last time.

One thing to watch out for: this can make your functions harder to reason about and test, because they're no longer pure functions. The output depends on how many times you've called them before. Use it when you need it, but be aware of the trade-off.

:::note A pure function is one that always produces the same output for the same input, and has no side effects. If you call add(2, 3), you get 5 every single time, regardless of when you call it, how many times you've called it before, or what else is happening in your program. The function doesn't have static variables, doesn't read from global variables, doesn't modify anything outside its own scope, and doesn't do I/O. It just takes its arguments, computes a result, and returns it. This makes pure functions easy to test (no setup required, just check input against output), easy to reason about (you can understand them in isolation), and safe to call from anywhere without worrying about hidden consequences.

The moment a function reads from or writes to a static variable, accesses global state, prints to the console, or modifies something via a pointer that was passed in, it stops being pure. That's not always a bad thing, programs need side effects to do anything useful, but knowing which of your functions are pure helps you understand where complexity and unpredictability live in your codebase. :::

2. Static Global Variables

When you declare a global variable (outside any function) as static, you're saying "this variable should only be visible within this file."

Without static:

// file1.c
int shared_counter = 0;  // Visible to other files via extern

// file2.c
extern int shared_counter;  // We can access it from here

With static:

// file1.c
static int private_counter = 0;  // Only visible in file1.c

// file2.c
extern int private_counter;  // Linker error! Can't see it.

This is about controlling visibility across translation units. The static keyword gives the variable internal linkage, meaning it's private to that file.

:::note A translation unit is what the C compiler actually sees after the preprocessor has finished its work. When you compile a .c file, the preprocessor first handles all the #include directives, macro expansions, and conditional compilation blocks, producing a single blob of source code. That blob, your original .c file with all the headers inlined and macros expanded, is one translation unit.

The compiler processes each translation unit independently, turning it into an object file (.o or .obj), and then the linker combines all the object files into your final executable. This is why static functions and variables are "file-private," they're actually private to the translation unit, which in practice means the .c file they're defined in (plus whatever headers that file includes). It's also why you can have the same static function name in two different .c files without a conflict: each lives in its own translation unit, and the linker never sees them because they have internal linkage. When people say "file scope" in C, they really mean "translation unit scope," though in most cases the distinction doesn't matter since each .c file typically becomes one translation unit. :::

Why would you want this? Encapsulation. If you're writing a module and you have some state that only that module should touch, making it static prevents other parts of the codebase from accidentally (or deliberately) messing with it. It's a bit like making a member private in an object-oriented language.

3. Static Functions

The same logic applies to functions. A static function is only visible within the file where it's defined.

// utils.c

// This helper is only for internal use within utils.c
static int calculate_checksum(const char *data, size_t len) {
    int sum = 0;
    for (size_t i = 0; i < len; i++) {
        sum += data[i];
    }
    return sum;
}

// This is the public function other files can call
int validate_data(const char *data, size_t len) {
    int checksum = calculate_checksum(data, len);
    return checksum == expected_checksum;
}

Other files can call validate_data, but they can't call calculate_checksum directly. It's an implementation detail.

This is genuinely useful for keeping your API clean. When someone includes your header file, they shouldn't see every little helper function you've written. They should see the functions you've designed for them to use. The static keyword lets you hide the rest.

It also means you can have static functions with the same name in different files without causing linker conflicts. Each one is private to its own file.

A Quick Summary

Here's how I think about it:

• Static local variable: "Keep your value between calls, but stay scoped to this function."
• Static global variable: "Exist for the whole program, but only be visible in this file."
• Static function: "Only be callable from within this file."

The common thread is persistence or restriction of visibility. For local variables, it's about persistence. For globals and functions, it's about restricting visibility to the current translation unit.

One More Thing: Static in Headers

You might occasionally see static used in header files, often with inline functions.

// math_utils.h
#ifndef MATH_UTILS_H
#define MATH_UTILS_H

// static inline: asking the compiler to insert this code directly
// at each call site, avoiding function call overhead
static inline int max(int a, int b) {
    return (a > b) ? a : b;
}

static inline int min(int a, int b) {
    return (a < b) ? a : b;
}

static inline int clamp(int value, int lower, int upper) {
    // Constrain a value to a range
    if (value < lower) return lower;
    if (value > upper) return upper;
    return value;
}

#endif

This creates a separate copy of the function in each translation unit that includes the header. Sometimes that's what you want (for small inline functions), but it can bloat your binary if you're not careful.

:::tip If you see static inline in a header, that's usually deliberate. If you see just static for a regular function in a header, someone might have made a mistake. With static inline, the intent is clear: you want the function inlined, and the static is there as a fallback to prevent linker errors if inlining doesn't happen. But with just static on a substantial function, you're not asking for inlining at all, you're just creating a separate copy of the function in every translation unit that includes the header, and that's almost never what someone actually wants. :::

Wrapping Up

The static keyword is doing a lot of work in C. Same word, different contexts, different effects. Once you've got the three uses clear in your head, you'll find it's a handy tool for managing state and keeping your code organised.

If you're coming from a language like Java or C#, note that C's static has nothing to do with class members (C doesn't have classes). It's all about storage duration and linkage. Don't let the shared terminology confuse you.

As always, thanks for joining me on this journey into embedded development!

This direct control over memory is why these languages are still used for operating systems, game engines, and embedded devices. It's also why they have a reputation for being difficult. But once you understand where your data lives and who's responsible for cleaning it up, most of the difficulty disappears.

The Two Places Your Data Can Live

In C and C++, your data essentially lives in one of two places: the stack or the heap. Understanding the difference is fundamental to everything else.

The Stack

The stack is where local variables live. When you declare a variable inside a function, it goes on the stack. When that function returns, the variable is automatically destroyed. You don't have to think about it.

void greet() {
    int count = 5;           // Lives on the stack
    char message[20];        // Also on the stack

    // Do things with count and message...

}   // count and message are automatically destroyed here

The stack is fast, predictable, and self-cleaning. It's called a "stack" because it works like a stack of plates: the last thing you put on is the first thing that comes off. Each function call pushes a new "frame" onto the stack containing its local variables, and returning from that function pops the frame off.

The catch? Stack space is limited (typically a few megabytes), and the size of stack allocations must be known at compile time. You can't decide at runtime that you need an array of a million integers and put it on the stack. Well, you can try, but you'll get a stack overflow.

:::tip You might hear the terms FIFO and LIFO when people talk about data structures. FIFO stands for "first in, first out." Like a queue at a shop, where the first person to arrive is the first person served. LIFO stands for "last in, first out", and that's how a stack works. The most recent item you added is the first one you remove. When you call a function, its stack frame goes on top. When that function returns, its frame comes off first, before any of the frames that were already there. This is why local variables from a calling function are still intact when a called function returns — they were lower in the stack and never got touched. :::

The Heap

The heap is where dynamic memory lives. It's much larger than the stack, and you can allocate whatever size you need at runtime. The trade-off is that you're responsible for cleaning up after yourself.

In C, you use malloc to allocate and free to deallocate:

#include <stdlib.h>

void process_data(int num_items) {
    // Allocate an array of integers on the heap
    int* data = malloc(num_items * sizeof(int));

    if (data == NULL) {
        // malloc returns NULL if allocation fails
        return;
    }

    // Use the data...
    for (int i = 0; i < num_items; i++) {
        data[i] = i * 2;
    }

    // We're done, so we must free the memory
    free(data);
}

In C++, you use new and delete:

void process_data(int num_items) {
    // Allocate an array of integers on the heap
    int* data = new int[num_items];

    // Use the data...
    for (int i = 0; i < num_items; i++) {
        data[i] = i * 2;
    }

    // We're done, so we must delete the array
    delete[] data;  // Note the [] for arrays
}

The heap gives you flexibility, but it demands discipline. Forget to free your memory, and you've got a memory leak. Free it twice, and you've got undefined behaviour. Use it after freeing, and you've got a use-after-free bug. These are the classic memory errors that have caused countless security vulnerabilities over the decades.

Pointers: Addresses in Memory

You can't talk about memory in C/C++ without talking about pointers. A pointer is simply a variable that holds a memory address. Instead of containing a value directly, it contains the location where a value is stored.

int value = 42;
int* ptr = &value;  // ptr now holds the address of value

printf("Value: %d\n", value);      // Prints 42
printf("Address: %p\n", ptr);      // Prints something like 0x7ffd5e8c3a4c
printf("Via pointer: %d\n", *ptr); // Prints 42 (dereferencing)

The & operator gives you the address of something. The * operator (when used on a pointer) gives you what's at that address. This is called dereferencing.

Pointers are how we work with heap memory. When you call malloc or new, you get back a pointer to the allocated memory. You use that pointer to access and manipulate the data, and eventually you pass that same pointer to free or delete to release the memory.

Pointers vs Arrays in C

This equivalence between arrays and pointers is one of C's more confusing aspects for newcomers. An array name is essentially a pointer to its first element, and array indexing is just pointer arithmetic with nicer syntax.

int* numbers = malloc(3 * sizeof(int));

// These three lines do exactly the same thing
numbers[0] = 10;
*(numbers + 0) = 10;
*numbers = 10;

// Array indexing is just pointer arithmetic in disguise
numbers[2] = 30;      // Same as *(numbers + 2) = 30

When you write numbers[2], you're asking for "the element at index 2". But what the compiler actually does is take the address stored in numbers, add 2 * sizeof(int) bytes to it, and then read the value at that resulting address. That's pointer arithmetic: starting from a base address and moving forward by a certain number of elements.

The syntax *(numbers + 2) makes this explicit. numbers + 2 means "the address two integers past where numbers points", and the * dereferences that address to get the value. The square bracket notation numbers[2] is just a more readable way of writing exactly the same thing.

This also explains why numbers[0], *(numbers + 0), and *numbers are all identical. Index zero means no offset from the base address, so you're just dereferencing the pointer directly.

Here's where it gets interesting: because numbers + 2 and 2 + numbers are mathematically equivalent, C actually allows you to write 2[numbers] instead of numbers[2]. They compile to the same thing. You'd never want to write code like that, but it demonstrates just how literally array indexing maps to pointer arithmetic.

The key insight is that C doesn't really have arrays in the way higher-level languages do. What it has are contiguous blocks of memory and pointers to the start of those blocks. The array syntax is a convenience layer on top of that.

The Dangers: What Can Go Wrong

Let me walk you through the classic memory errors. Knowing what they look like is the first step to avoiding them.

Memory Leaks

A memory leak occurs when you allocate memory but never free it. The memory remains allocated until your program exits, even though you've lost all references to it.

void leaky_function() {
    int* data = malloc(1000 * sizeof(int));

    // Do some work...

    if (some_error_condition) {
        return;  // Oops! We forgot to free data
    }

    free(data);
}

In a short-running program, leaks might not matter much. In a long-running server or an embedded system that runs for months, leaks accumulate and eventually exhaust available memory.

Use After Free

This is when you access memory after you've already freed it. The memory might have been reallocated for something else, so you could be reading or writing garbage, or worse, corrupting unrelated data.

int* ptr = malloc(sizeof(int));
*ptr = 42;
free(ptr);

// ptr still holds the old address, but the memory is no longer ours
*ptr = 100;  // Undefined behaviour! Anything could happen

Double Free

Freeing the same memory twice corrupts the memory allocator's internal data structures. This can cause crashes, or worse, exploitable security vulnerabilities.

int* ptr = malloc(sizeof(int));
free(ptr);
free(ptr);  // Undefined behaviour!

Buffer Overflow

Writing beyond the bounds of an allocated buffer. This is the source of countless security exploits throughout computing history.

char buffer[10];
strcpy(buffer, "This string is way too long for the buffer");
// We've just written past the end of buffer, corrupting whatever was next to it

Modern C++: Smart Pointers

If you're writing C++, you have access to smart pointers, which automate memory management while still giving you control when you need it. They're part of the standard library and should be your default choice for heap allocation in modern C++.

unique_ptr: Single Ownership

A unique_ptr owns its memory exclusively. When the unique_ptr goes out of scope, it automatically deletes the memory. You can't copy a unique_ptr, but you can move it to transfer ownership.

#include <memory>

void process() {
    // Memory is automatically managed
    std::unique_ptr<int[]> data = std::make_unique<int[]>(100);

    data[0] = 42;

    // When data goes out of scope, the memory is automatically freed
    // No explicit delete needed, no leaks possible
}

This handles most use cases well. The memory is tied to a specific scope, and cleanup happens automatically even if exceptions are thrown.

shared_ptr: Shared Ownership

Sometimes multiple parts of your code need to hold references to the same data, and you want the memory freed only when everyone's done with it. That's what shared_ptr is for. It keeps a reference count and deletes the memory when the count reaches zero.

#include <memory>

std::shared_ptr<Widget> create_widget() {
    return std::make_shared<Widget>();
}

void use_widgets() {
    std::shared_ptr<Widget> w1 = create_widget();
    std::shared_ptr<Widget> w2 = w1;  // Both now point to the same Widget

    // Reference count is 2

}   // Both w1 and w2 go out of scope, ref count hits 0, Widget is deleted

Shared pointers have slightly more overhead than unique pointers due to the reference counting, but they solve real problems when ownership genuinely needs to be shared.

When to Use Raw Pointers

Even in modern C++, raw pointers aren't obsolete. They're still the right choice for non-owning references, where you need to point to something but aren't responsible for its lifetime. Function parameters that observe but don't own are a common example.

// This function doesn't own the data, it just uses it
void print_value(const int* value) {
    if (value != nullptr) {
        std::cout << *value << std::endl;
    }
}

void example() {
    auto data = std::make_unique<int>(42);
    print_value(data.get());  // Pass raw pointer, ownership stays with unique_ptr
}

The rule of thumb: use smart pointers for ownership, raw pointers for observation.

RAII: The Pattern Behind the Magic

Smart pointers are an example of a broader C++ pattern called RAII: Resource Acquisition Is Initialisation. The idea is that resource management (memory, file handles, network connections, mutexes) should be tied to object lifetimes.

You acquire the resource in the constructor and release it in the destructor. Since destructors are called automatically when objects go out of scope, cleanup happens automatically and reliably, even when exceptions are thrown.

class FileHandle {
public:
    FileHandle(const char* path) {
        file = fopen(path, "r");
    }

    ~FileHandle() {
        if (file) {
            fclose(file);  // Automatically closed when FileHandle is destroyed
        }
    }

    // Prevent copying (or implement it properly)
    FileHandle(const FileHandle&) = delete;
    FileHandle& operator=(const FileHandle&) = delete;

private:
    FILE* file;
};

void read_config() {
    FileHandle config("settings.txt");
    // Use config...

}   // config goes out of scope, destructor runs, file is closed

Once you understand RAII, you'll start seeing opportunities to apply it everywhere. It's one of C++'s most useful patterns.

Practical Tips

After working with C and C++ for a while, here are the habits that have helped me avoid the most problems:

Initialise your pointers. An uninitialised pointer contains garbage, which is worse than a null pointer because it might look valid. In C, initialise to NULL. In C++, use nullptr. A null pointer will crash predictably when dereferenced; a garbage pointer might corrupt memory silently.

int* ptr = NULL;  // Safe default

Set pointers to null after freeing. This prevents use-after-free bugs from silently corrupting memory. If you accidentally use the pointer, you'll get a crash instead of subtle corruption.

free(ptr);
ptr = NULL;

Match your allocations and deallocations. malloc pairs with free. new pairs with delete. new[] pairs with delete[]. Mixing them is undefined behaviour.

Use tools to catch errors. Valgrind on Linux will detect memory leaks, use-after-free, and buffer overflows. Address Sanitizer (ASan) is built into modern compilers and catches similar issues with less overhead. Use them during development.

In C++, prefer stack allocation when possible. If the object's lifetime matches a scope and it's not too large, put it on the stack. It's faster and there's nothing to clean up.

// Prefer this when possible
void process() {
    std::vector<int> data(100);  // vector manages its own heap memory internally
    // ...
}   // data is destroyed, its internal memory is freed

// Over this
void process() {
    std::vector<int>* data = new std::vector<int>(100);
    // ...
    delete data;
}

Wrapping Up

Memory management in C and C++ comes down to understanding two things: where your data lives (stack vs heap) and who's responsible for cleaning it up (automatic vs manual).

In C, you're always working manually. You call malloc, you call free, and you're responsible for getting it right.

In C++, you have choices. Smart pointers and RAII let you automate cleanup while retaining control. Modern C++ code should rarely contain explicit new and delete calls outside of low-level infrastructure code.

The key is building good habits: initialise your pointers, use the right tools to catch errors, and in C++, let smart pointers do the work for you. Get these fundamentals right, and memory management becomes straightforward.

As always, thanks for joining me on this journey into embedded development!

Turns out, bitwise operations aren't magic at all. They're actually quite simple. And once you understand them, you'll have a new tool to use. One that you'll find yourself using fairly often, from compact data storage to quicker calculations.

First, Let's Talk About Bits

Before we dive into operations, let's make sure we're on the same page about what we're operating on.

Every number in your computer is stored as a sequence of bits, where each bit is either a 0 or a 1. When I write the number 5 in code, the computer stores it as 00000101 (assuming an 8-bit number for simplicity). That's just 5 in binary: one 4, zero 2s, and one 1.

Here's a quick reference for the first few numbers:

0  = 00000000
1  = 00000001
2  = 00000010
3  = 00000011
4  = 00000100
5  = 00000101
6  = 00000110
7  = 00000111
8  = 00001000

Each position represents a power of 2, reading right to left: 1, 2, 4, 8, 16, 32, 64, 128. When a bit is "set" (equals 1), you add that power of 2 to the total. So 00000101 means 4 + 1 = 5.

Right, with that foundation in place, let's look at what we can actually do with these bits.

AND (&): Both Must Be True

The AND operation compares two numbers bit by bit. For each position, the result is 1 only if both input bits are 1. Otherwise, it's 0.

    00001101  (13)
AND 00000111  (7)
  = 00000101  (5)

This is incredibly useful for checking if specific bits are set. Say you have a byte where each bit represents a different permission, and bit 2 (counting from 0) means "can write files". You can check if that bit is set like this:

// Check if bit 2 is set in the permissions byte
if (permissions & 0b00000100) {
    // User can write files
}

The number 0b00000100 (which equals 4) is called a "mask" because it masks out all the bits we don't care about. If bit 2 is set in permissions, we get a non-zero result. If it's not set, we get zero.

OR (|): Either Will Do

The OR operation is more generous. For each bit position, the result is 1 if either (or both) input bits are 1.

   00001100  (12)
OR 00000011  (3)
 = 00001111  (15)

This is perfect for setting bits without disturbing the others. Want to grant that write permission we just checked for?

// Set bit 2, leave everything else alone
permissions = permissions | 0b00000100;

// Or more concisely:
permissions |= 0b00000100;

Whatever permissions was before, bit 2 is now definitely set, and all the other bits remain exactly as they were.

XOR (^): One or the Other, But Not Both

XOR (exclusive or) is a bit peculiar. It returns 1 when the bits are different, and 0 when they're the same.

    00001111  (15)
XOR 00000101  (5)
  = 00001010  (10)

Here's where it gets interesting: XOR has this lovely property where applying it twice gets you back to where you started. If you XOR a number with the same value twice, you end up with the original number.

int secret = 42;
int key = 123;

int encrypted = secret ^ key;  // Some scrambled value
int decrypted = encrypted ^ key;  // Back to 42!

This makes XOR useful for simple encryption, toggling bits, and all sorts of clever tricks. Want to toggle bit 2? Just XOR with the mask:

permissions ^= 0b00000100;  // Flip bit 2: if it was 0, it's now 1; if it was 1, it's now 0

NOT (~): Flip Everything

The NOT operation is the simplest: it flips every single bit. Ones become zeros, zeros become ones.

NOT 00001111
  = 11110000

This is often used together with AND to clear specific bits. If you want to clear bit 2 (set it to 0), you can AND with the inverse of the bit's mask:

// Clear bit 2
permissions = permissions & ~0b00000100;

// What's happening here:
// ~0b00000100 gives us 0b11111011
// ANDing with this clears bit 2 and preserves everything else

Bit Shifting: Sliding Things Around

We also have operations that move bits left or right. Left shift (<<) moves all bits towards the more significant end, filling in zeros on the right. Right shift (>>) does the opposite.

int x = 1;       // 00000001
x = x << 3;      // 00001000 (now equals 8)
x = x >> 2;      // 00000010 (now equals 2)

Left shifting by n positions is equivalent to multiplying by 2^n. Right shifting is equivalent to dividing by 2^n (discarding any remainder). This is why you'll sometimes see shifts used for fast multiplication or division by powers of 2, though modern compilers are clever enough to make this optimisation for you.

Shifting is also handy for creating bit masks. Instead of writing out 0b00000100 to represent bit 2, you can write 1 << 2. This makes your intent clearer and works regardless of how many bits you're dealing with:

#define WRITE_PERMISSION (1 << 2)
#define READ_PERMISSION  (1 << 1)
#define EXEC_PERMISSION  (1 << 0)

// Now your permission checks become quite readable:
if (permissions & WRITE_PERMISSION) {
    // Can write
}

A Practical Example: Packing Data

Let me show you something I find genuinely satisfying. Say you're working on a game, and you need to store a colour. Each colour has red, green, blue, and alpha components, each ranging from 0 to 255. You could use four separate bytes, or you could pack them all into a single 32-bit integer:

// Pack four 8-bit values into one 32-bit integer
uint32_t pack_colour(uint8_t r, uint8_t g, uint8_t b, uint8_t a) {
    // Shift each component to its position and combine with OR
    return (r << 24) | (g << 16) | (b << 8) | a;
}

// Extract the components back out
uint8_t get_red(uint32_t colour) {
    // Shift right to bring red to the bottom, then mask off everything else
    return (colour >> 24) & 0xFF;
}

uint8_t get_green(uint32_t colour) {
    return (colour >> 16) & 0xFF;
}

uint8_t get_blue(uint32_t colour) {
    return (colour >> 8) & 0xFF;
}

uint8_t get_alpha(uint32_t colour) {
    return colour & 0xFF;  // Already at the bottom, just mask
}

This pattern appears everywhere in graphics programming, network protocols, file formats, and embedded systems where memory is precious and every byte counts.

Why Bother?

You might be wondering why any of this matters when you could just use booleans and normal arithmetic. Fair question.

In high-level application code, you might rarely need bitwise operations. But they become essential when you're working close to the hardware, parsing binary file formats, implementing network protocols, or optimising performance-critical code. A single integer holding 32 boolean flags takes up the same space as 32 separate boolean variables, but you can copy, compare, and manipulate all 32 at once with a single operation.

In embedded systems, where I've been spending more time lately, you're often directly manipulating hardware registers where each bit controls something different. Even if you never write low-level code, understanding bits helps you appreciate what's actually happening inside the machine. And occasionally, you'll encounter someone else's bitwise code and be glad you know what status & (1 << 7) means.

A Quick Reference

To wrap up, here's a summary of the common operations:

The AND operation (a & b) returns 1 only where both bits are 1, which is useful for checking or clearing bits.

The OR operation (a | b) returns 1 where either bit is 1, which is perfect for setting bits.

The XOR operation (a ^ b) returns 1 where bits differ, making it ideal for toggling.

The NOT operation (~a) inverts every bit.

Left shift (a << n) moves bits left by n positions, effectively multiplying by 2^n.

Right shift (a >> n) moves bits right, effectively dividing by 2^n.

And here are the most common patterns you'll encounter:

• Use value & mask to check if a bit is set
• value | mask to set a bit
• value & ~mask to clear a bit
• value ^ mask to toggle a bit.
• For creating masks, 1 << n gives you a mask for bit n.

Once these patterns click, you'll find bitwise operations are less about memorising rules and more about developing an intuition for how bits flow and combine. They're a direct conversation with the machine, and there's something rather satisfying about that.

As always, thanks for joining me on this journey into embedded development!

The Debugging Experience I Was Used To

Coming from mobile development, I had a particular mental model of debugging. I'd set a breakpoint in Xcode or Android Studio, run my app, and when execution hit that breakpoint, I could inspect variables, step through code, and examine the call stack. The debugger and the code being debugged felt like they existed in the same world, even when the app was running on a connected phone rather than a simulator.

What I didn't fully appreciate was how much infrastructure was working behind the scenes to create that experience. Mobile platforms provide debugging services built into the operating system. The IDE communicates with these services over USB, and it all just works.

Embedded systems, particularly bare-metal microcontrollers with no operating system, don't have any of this infrastructure. There's no debug service waiting for your IDE to connect. The microcontroller is just executing instructions, with no awareness that you might want to pause and inspect what it's doing.

How Cross Debugging Works

Cross debugging solves this problem by splitting the debugger into two parts that communicate across the boundary between your host machine and the target device.

On your development machine, you run a debugger frontend. This is typically GDB, the GNU Debugger, or a graphical interface built on top of it. The frontend is where you set breakpoints, issue commands, and view your source code. It runs natively on your laptop and understands your keyboard, your display, and your project files.

On the target side, you need some way to actually halt the processor, read its registers, and inspect memory. This is where debug probes come in. Devices like the ST-Link or SEGGER J-Link connect to your microcontroller through special debug interfaces, most commonly JTAG or SWD. These interfaces are built into the silicon itself, providing hardware-level access to the processor's internal state.

The debug probe runs a small piece of software called a GDB server. This server translates between the GDB protocol that your frontend speaks and the low-level debug commands that control the target hardware. When you click "pause" in your IDE, that request travels from the frontend, across USB to the debug probe, and down into the chip's debug hardware, which halts the processor mid-instruction.

Nothing Comes for Free

Something I hadn't initially considered is that this debug capability has costs. The microcontroller has to dedicate some of its limited resources to supporting these debug interfaces.

At the silicon level, the debug hardware takes up physical space on the chip. There are dedicated pins for JTAG or SWD that can't be used for anything else while debugging. Some microcontrollers let you reclaim these pins for GPIO in production builds, but during development they're unavailable. On a chip with only twenty or thirty pins, losing two or four to debugging is a real trade-off.

There's also internal circuitry dedicated to the debug interface: logic for halting the core, reading registers, and managing breakpoints. This circuitry consumes a small amount of power even when you're not actively debugging. On some devices, particularly those designed for low-power applications, you can disable the debug interface entirely in production to save power, but then you lose the ability to diagnose issues in the field.

Some debug features consume RAM too. If you're using features like real-time tracing or certain advanced breakpoint modes, the chip may need to buffer data internally before sending it to the debug probe. On a microcontroller with only a few kilobytes of RAM, even a small debug buffer can represent a notable percentage of your available memory.

The Printf Alternative

Given these costs and the complexity of setting up proper debug hardware, some developers reach for a more familiar approach: printf debugging. The idea is simple. You write diagnostic messages to an unused serial port, connect a USB-to-serial adapter to your development machine, and watch the output in a terminal. It feels comfortable, especially coming from higher-level development where console logging is standard practice.

The problem is that embedded systems often operate under timing constraints that make printf debugging problematic.

Sending characters over a serial port takes time. At 115200 baud, transmitting a single character takes roughly 87 microseconds. A modest debug message of 50 characters might take over 4 milliseconds to transmit. If your system is running a control loop that needs to execute every millisecond, inserting printf statements can break your timing.

This leads to a common frustration in embedded debugging: bugs that disappear when you try to observe them. Adding printf statements changes the timing of your system enough that race conditions, buffer overflows, or interrupt-related bugs no longer manifest. You add logging, the problem vanishes, you remove logging, the problem returns. You might also introduce new bugs that only exist because of the timing changes from your debug output.

There are ways to mitigate this. You can buffer your debug output and transmit it during idle time, or use a faster interface like SWO (Serial Wire Output) that's designed for debug tracing with less overhead. But these approaches add complexity and still don't fully eliminate the observer effect.

Halting Hardware

What took me a while to get used to is how literal the cross debugging process is. When you hit a breakpoint during cross debugging, the microcontroller's processor actually stops. The clock is still ticking, but the CPU isn't fetching or executing instructions. You're halting the hardware in place.

This has consequences that don't arise in mobile debugging. If your embedded system is controlling something in the real world, pausing execution might cause problems. A motor might keep spinning, a heater might stay on, or communication with another device might time out.

Similarly, inspecting variables works differently than you might expect. There's no runtime providing nice abstractions. When you ask to see a variable's value, the debugger is reading raw bytes from specific memory addresses and interpreting them based on your source code's type information. If that memory happens to be a hardware register that changes when read, simply inspecting it might alter your system's behaviour.

What Mobile Development Hides

Once again, mobile platforms abstract away this complexity. When you debug an iOS or Android app, you're debugging a process running under an operating system that mediates everything. The OS provides memory protection, process isolation, and debugging APIs. You're never directly touching hardware registers or halting a physical processor. And console logging on a modern smartphone has negligible timing impact.

Embedded cross debugging puts you closer to the hardware. You're not debugging through an operating system's abstraction layer; you're interacting with the silicon directly.

The Practical Reality

If you're coming from mobile development and setting up cross debugging for the first time, the good news is that the day-to-day experience isn't dramatically different. You'll still set breakpoints, step through code, and inspect variables. The tools have matured to the point where the underlying complexity is largely invisible. Modern embedded IDEs like STM32CubeIDE, PlatformIO, or VS Code with the right extensions hide much of this complexity behind familiar interfaces. You click a button, your code uploads, and breakpoints work roughly as you'd expect. But underneath, the machinery is different from what you're used to.

But when something goes wrong: when breakpoints don't trigger, when your timing-sensitive code behaves differently under the debugger, when you can't figure out why your debug session won't connect, understanding the architecture helps. Knowing there's a GDB server running on your probe, that your chip has dedicated debug hardware with its own limitations, and that halting the processor means genuinely halting it gives you a mental model for troubleshooting.

As always, thanks for joining me on this journey into embedded development!

Your Computer and Your Target Are Very Different

Think about your laptop or desktop computer. It runs on a powerful processor, likely an Intel or AMD chip using the x86-64 architecture, or if you're on a newer Mac, an ARM-based M-series chip. It has gigabytes of RAM, an operating system many generations deep, and plenty of storage. Now think about an Arduino Uno or a Raspberry Pi Pico. These devices run on completely different processors with different architectures, far less memory, and often no operating system at all.

When you write code and compile it on your laptop, the compiler produces machine code, the actual binary instructions that a processor can execute. But machine code isn't universal. The binary instructions that an Intel processor understands are meaningless to an ARM Cortex-M0 microcontroller. They speak different languages at the hardware level.

The Solution

Cross compilation is the process of building executable code on one type of machine (the host) for a different type of machine (the target). Your laptop acts as the host, providing all the computational power and development tools you need. The embedded device is the target, the machine that will eventually run your code.

When you install an embedded development toolchain, you're getting a special compiler designed for exactly this purpose. Instead of producing machine code for your laptop's processor, it produces machine code for your target's processor. The GNU ARM Embedded Toolchain, for instance, runs on your development machine but outputs binaries that ARM microcontrollers understand.

What Mobile Development Hides From You

Coming from mobile, I initially assumed I'd been doing something similar all along. But the reality is more nuanced: mobile development abstracts away the cross compilation problem rather than exposing you to it directly.

With Android development, when you write Java or Kotlin code, you're not compiling to native machine code at all. The build process produces DEX bytecode, which is architecture-independent. This bytecode runs on the Android Runtime, which handles the translation to native instructions on the device itself. The architecture mismatch between your development machine and the target phone simply doesn't matter because you're shipping portable bytecode rather than native binaries.

iOS development on modern Macs sidesteps the issue differently. Apple's M-series chips are ARM-based, just like iPhone processors. When you build an iOS app on an M1 or M2 Mac, the host and target share the same underlying architecture. The toolchain still does important work adapting for the different operating systems, but you're not dealing with a fundamental architecture mismatch.

Embedded development offers no such abstractions. When I write C for an STM32 microcontroller, the compiler produces raw ARM machine code. There's no runtime to translate bytecode, no shared architecture to lean on.

Why Can't We Compile Directly on the Target?

You might wonder why we don't just compile code directly on the embedded device. For some platforms like the Raspberry Pi, which runs a full Linux operating system, you actually can do this, and it's called native compilation. However, for most embedded targets, this isn't practical.

Microcontrollers simply don't have the resources. A compiler is a complex piece of software that requires significant memory and processing power. An ATmega328P with 2KB of RAM and 32KB of flash couldn't possibly host a compiler. Even when resources aren't the limiting factor, development is far more comfortable on your main computer with your favourite editor, debugging tools, and version control.

The Toolchain

When people talk about cross compilation, they're usually referring to an entire toolchain rather than just the compiler itself. A typical embedded toolchain includes the compiler that translates your C, C++, Rust code into assembly, the assembler that converts assembly into machine code, the linker that combines various object files and libraries into a final executable, and various utilities for inspecting and manipulating binaries.

Popular toolchains include GCC-based options like the ARM GNU Toolchain and vendor-specific tools like those provided in development environments such as STM32CubeIDE or the Arduino IDE. Each toolchain is configured to understand the specific capabilities and constraints of its target architecture.

The key insight for me as a newcomer was recognising that my development machine and my target device are completely separate execution environments. I'm using one computer as a tool to prepare software for another, much simpler computer.

As always, thanks for joining me on this journey into embedded development!

If you've spent any time in embedded development in C, you've likely encountered the volatile keyword. And if you're like me, you've been bitten by infuriating bugs when you forgot to use it (like why does my code break when I turn optimisation on?!).

Despite being one of the most important qualifiers in embedded C, it's frequently misunderstood. This post will explain what volatile actually does, why it matters in embedded contexts, and just as importantly what it doesn't do.

The Problem: Compilers Are Too Clever but They Don't See Everything

Modern C compilers are extraordinarily sophisticated optimisers. They analyse your code, track how variables are used, and make transformations to generate faster, smaller machine code. Most of the time, this is exactly what you want.

Consider this innocent-looking code:

int ready = 0;

void wait_for_ready(void) {
    while (ready == 0) {
        // Wait...
    }
}

A clever compiler might reason: The variable ready is never modified inside this loop. Therefore, if it's zero when we enter, it will always be zero. I can optimise this to:"

void wait_for_ready(void) {
    if (ready == 0) {
        while (1) { }  // Infinite loop
    }
}

From the compiler's perspective within the abstract machine model of C, this transformation is perfectly valid. It doesn't know, and has no way of knowing, that an interrupt handler running asynchronously might set ready to 1. So while compilers are very sophisticated, they are not omnipotent.

This is the fundamental problem volatile solves.

What volatile Actually Means

And this is where the 'volatile' qualifier comes in. It tells the compiler: "This variable's value may change at any time, through means you cannot see or analyse. Do not make any assumptions about its value. Every time the code reads this variable, generate an actual load instruction. Every time the code writes to it, generate an actual store instruction."

Let's fix our earlier example:

volatile int ready = 0;

void wait_for_ready(void) {
    while (ready == 0) {
        // This actually works now
    }
}

Now the compiler must generate code that genuinely reads from the memory location of ready on every iteration of the loop. If an interrupt handler sets it to 1, our loop will see the change and exit.

The Three Core Use Cases in Embedded Systems

1. Memory-Mapped Hardware Registers

In embedded systems, hardware peripherals are typically controlled through memory-mapped registers. Reading or writing to a specific memory address communicates with the hardware, not with regular RAM.

// UART status register at address 0x40001000
#define UART_STATUS (*(volatile uint32_t *)0x40001000)

// UART data register at address 0x40001004
#define UART_DATA   (*(volatile uint32_t *)0x40001004)

void uart_send(char c) {
    // Wait until transmit buffer is empty
    while ((UART_STATUS & TX_READY) == 0) {
        // The hardware updates UART_STATUS independently
    }
    UART_DATA = c;
}

Without volatile, the compiler might:

• Read UART_STATUS once and cache the value, never seeing when the hardware clears the busy flag
• Decide that writing to UART_DATA has no observable effect (since it's never read) and eliminate the write entirely
• Reorder the status check and data write, corrupting the transmission

Hardware registers have another important property: reading them often has side effects. Reading a UART receive register might clear an interrupt flag or advance a FIFO pointer. The compiler cannot be allowed to eliminate or combine these reads.

// Reading this register clears pending interrupts
volatile uint32_t *interrupt_clear = (uint32_t *)0x40002000;

void clear_pending_interrupts(void) {
    (void)*interrupt_clear;  // The read itself is the operation
}

Without volatile, the compiler would remove this "useless" read.

2. Variables Modified by Interrupt Service Routines

This is perhaps the most common source of volatile-related bugs. Variables shared between your main code and interrupt handlers must be marked volatile:

volatile uint32_t system_ticks = 0;

// Called by timer interrupt
void SysTick_Handler(void) {
    system_ticks++;
}

void delay_ms(uint32_t ms) {
    uint32_t start = system_ticks;
    while ((system_ticks - start) < ms) {
        // Busy wait
    }
}

The system_ticks variable is modified by code that the compiler cannot see when compiling delay_ms(). The interrupt can fire at any point, completely asynchronously. Without volatile, the compiler has every right to assume system_ticks never changes during the loop.

3. DMA Buffers and Multi-Core Shared Memory

Direct Memory Access (DMA) controllers transfer data between peripherals and memory without CPU involvement. The CPU sets up the transfer and then continues executing other code while the DMA engine works in the background.

volatile uint8_t rx_buffer[256];
volatile int rx_complete = 0;

void start_dma_receive(void) {
    // Configure DMA to write to rx_buffer
    // When complete, DMA sets rx_complete = 1
    DMA1->CMAR = (uint32_t)rx_buffer;
    DMA1->CCR |= DMA_CCR_EN;
}

void process_received_data(void) {
    while (!rx_complete) { }

    // Process data in rx_buffer
    for (int i = 0; i < 256; i++) {
        handle_byte(rx_buffer[i]);
    }
}

The CPU didn't write to rx_buffer, so the compiler might assume it contains whatever was there before (possibly uninitialised garbage). The volatile qualifier forces it to actually read the DMA-filled contents.

A Deeper Look at the Optimisations volatile Prevents

Let's examine the specific optimisations that volatile inhibits:

Register Caching

Normally, compilers keep frequently-accessed variables in CPU registers for speed:

int counter = 0;

void count_events(void) {
    while (check_sensor()) {
        counter++;
    }
}

The compiler might load counter into a register at the start, increment the register in the loop, and write the final value back only when exiting. With volatile counter, every increment involves a load from memory, an increment, and a store back to memory.

Dead Store Elimination

If a variable is written multiple times before being read, the compiler may keep only the final write:

int status = 0;
status = 1;  // Compiler might remove this
status = 2;  // Keep only this

For hardware registers, each write might trigger a different hardware behaviour. volatile ensures all writes occur.

Dead Read Elimination

Similarly, if a value is read but never used, the compiler may remove the read:

int dummy = *status_register;  // Compiler might remove this

Reading hardware registers often clears flags or advances state machines. volatile prevents this elimination.

Loop-Invariant Code Motion

Compilers can move computations that don't change during a loop to outside the loop:

while (running) {
    if (*config_flag) {  // Might be hoisted outside the loop
        do_something();
    }
}

With volatile, the flag must be checked on every iteration.

What volatile Does NOT Provide

This is where many developers get tripped up. The volatile keyword is more limited than people often assume.

No Atomicity

volatile does not make operations atomic. Consider:

volatile int counter = 0;

// In main code
counter++;

// In interrupt handler
counter++;

The counter++ operation typically compiles to three instructions: load, increment, store. If an interrupt fires between the load and store in the main code, you'll lose an increment.

For atomicity, you need:

// Option 1: Disable interrupts
disable_interrupts();
counter++;
enable_interrupts();

// Option 2: Use atomic types (C11)
#include <stdatomic.h>
atomic_int counter = 0;
atomic_fetch_add(&counter, 1);

// Option 3: Use platform-specific atomic intrinsics
__sync_fetch_and_add(&counter, 1);

No Memory Barriers

On modern processors with out-of-order execution and caching hierarchies, volatile doesn't guarantee other CPUs or cores see your writes when you expect:

volatile int data_ready = 0;
int data[100];  // Non-volatile

void producer(void) {
    // Fill the data array
    for (int i = 0; i < 100; i++) {
        data[i] = compute(i);
    }
    data_ready = 1;  // Signal completion
}

void consumer(void) {
    while (!data_ready) { }
    // BUG: data[] writes might not be visible yet!
    process(data);
}

Even though data_ready is volatile, the writes to data[] might still be sitting in a write buffer or cache, invisible to the consumer. You need explicit memory barriers:

void producer(void) {
    for (int i = 0; i < 100; i++) {
        data[i] = compute(i);
    }
    __sync_synchronize();  // Memory barrier
    data_ready = 1;
}

On single-core microcontrollers without write buffers (like many ARM Cortex-M devices), this is less of a concern. But on multi-core systems or processors with complex memory systems, memory barriers are essential.

No Prevention of Compiler Reordering Around Non-Volatile Accesses

The compiler can still reorder non-volatile operations with respect to each other, even if they're adjacent to volatile accesses:

volatile int flag = 0;
int a = 0, b = 0;

void setup(void) {
    a = 1;
    b = 2;
    flag = 1;  // Compiler must put this access here...
    // ...but a=1 and b=2 can still be reordered
}

If you need ordering guarantees for the non-volatile variables, you need compiler barriers:

void setup(void) {
    a = 1;
    b = 2;
    __asm__ __volatile__ ("" ::: "memory");  // Compiler barrier
    flag = 1;
}

Best Practices

1. Always Use volatile for Hardware Registers

Create a clear convention in your codebase:

// Hardware abstraction layer
typedef volatile uint32_t reg32_t;

typedef struct {
    reg32_t CR;     // Control register
    reg32_t SR;     // Status register
    reg32_t DR;     // Data register
} UART_TypeDef;

#define UART1 ((UART_TypeDef *)0x40011000)

2. Mark All ISR-Shared Variables as volatile

Even if you think you've analysed the code and it's safe, use volatile. Future optimisation levels or compiler versions might break your assumptions:

// ISR communication variables
static volatile bool tx_complete = false;
static volatile uint32_t error_count = 0;
static volatile uint8_t rx_buffer[64];

3. Don't Overuse volatile

Every volatile access has a performance cost. Don't mark variables as volatile unless they genuinely can change unexpectedly:

// BAD: Unnecessary volatile
volatile int loop_counter;  // Only modified by this function

for (loop_counter = 0; loop_counter < 100; loop_counter++) {
    // Performance penalty on every access
}

// GOOD: Copy volatile to local for intensive computation
volatile uint32_t raw_adc_value;

void process_adc(void) {
    uint32_t local_value = raw_adc_value;  // Single volatile read
    // Perform many operations on local_value
    // ...
}

4. Remember: volatile is Necessary but Not Sufficient

For correct concurrent code, you typically need volatile plus one or more of:

• Critical sections (disabled interrupts)
• Atomic operations
• Memory barriers
• Proper mutex/semaphore primitives

The volatile keyword is a fundamental tool in embedded C programming. It prevents the compiler from optimising away critical accesses to hardware registers, ISR-shared variables, and DMA buffers. However, it's important to understand its limitations, it provides neither atomicity nor memory ordering guarantees. When working with hardware or interrupt handlers, ask yourself: "Can this variable change in ways the compiler can't see?" If the answer is yes, you need volatile. Then ask: "Do I also need atomicity or memory barriers?" The answer to that question depends on your specific hardware and use case.

Understanding these nuances is what separates embedded code that "seems to work" from code that's genuinely correct. Code that won't mysteriously break when you change compiler versions, enable optimisation, or port to a new platform.

As always, thanks for joining me on this journey into embedded development!