Firmware Buffering & Ring Buffers Questions

Overview
As an embedded developer I use a circular (ring) buffer to stream data from a producer (ISR/sensor driver) to a consumer (main loop/task). It stores bytes/packets in a fixed-size array and advances head/tail indices modulo the buffer length so no memmove is needed.

Head / Tail roles

• Head = write index (producer advances)
• Tail = read index (consumer advances)
  Both updated modulo N.

Detect full vs empty
Empty when head == tail. Full when next(head) == tail.

Formulas:

next_head = (head + 1) % N
empty  : head == tail
full   : next_head == tail

Ambiguity arises because head==tail can mean either empty or full depending on policy.

Two strategies to avoid ambiguity

• Leave one slot empty: capacity = N-1; treat full as above. Simple and ISR-safe.
• Maintain a count variable: increment on write, decrement on read; full when count == N; empty when count == 0. Count must be updated atomically (or with IRQs disabled) to avoid races.

Example: power-of-two N uses mask for faster wrap:

head = (head + 1) & (N - 1);

Advantages for ISR→task

• Lock-free single-producer single-consumer (SPSC) if operations are atomic
• Low latency, predictable memory and CPU cost
• Small, fixed RAM footprint

Pitfalls

• Buffer overrun (producer writes when full) — decide policy: drop, overwrite oldest, or block
• Pointer wrap-around bugs if not using modulo/mask correctly
• Concurrency: on platforms without atomic word updates, protect head/tail/count with proper atomic/IRQ disable
• Memory alignment/volatile: declare indices volatile to prevent compiler reordering in ISR contexts

I favor the one-slot-empty approach in ISRs for simplicity and minimal synchronization; use counts only when full capacity must be used and atomic updates are available.

Approach (brief)
Use a power-of-two buffer with head (producer write index) updated only by ISR and tail (consumer read index) only by thread. Use 32-bit atomicity guarantee for reads/writes. Store message length (uint32_t) before payload. Enqueue fails if not enough contiguous space; handle wrap by inserting a zero-length padding header to skip to buffer start.

#include <stdint.h>
#include <string.h>
#include <stdbool.h>

#define BUF_SIZE 1024            // power of two
#define MASK (BUF_SIZE - 1)
static uint8_t ring[BUF_SIZE];
static volatile uint32_t head = 0; // written by ISR
static volatile uint32_t tail = 0; // written by thread

// write from ISR: returns true on success
bool enqueue_from_isr(const void *msg, uint32_t len) {
    uint32_t h = head;            // local copy
    uint32_t t = tail;            // read tail (updated by thread)
    uint32_t used = h - t;
    uint32_t free = BUF_SIZE - used;
    uint32_t need = sizeof(uint32_t) + len;
    if (need > free) return false;

    uint32_t pos = h & MASK;
    // if remaining linear space is insufficient for header+payload, add padding
    uint32_t linear = BUF_SIZE - pos;
    if (linear < sizeof(uint32_t)) {
        // write zero-length header as padding
        *(uint32_t *)&ring[pos] = 0;
        h += linear; pos = 0;
    }
    // write header
    *(uint32_t *)&ring[pos] = len;
    pos = (pos + sizeof(uint32_t)) & MASK;
    // write payload (may wrap)
    uint32_t first = (len <= BUF_SIZE - pos) ? len : (BUF_SIZE - pos);
    memcpy(&ring[pos], msg, first);
    if (first < len) memcpy(&ring[0], (const uint8_t*)msg + first, len - first);
    // publish new head (32-bit write is atomic)
    head = h + need;
    return true;
}

// dequeue in thread: returns length copied to buf, 0 if no message
uint32_t dequeue_in_thread(void *buf, uint32_t maxlen) {
    uint32_t t = tail;
    uint32_t h = head;            // read head (updated by ISR)
    if (t == h) return 0;        // empty
    uint32_t pos = t & MASK;
    uint32_t hdr = *(uint32_t *)&ring[pos];
    if (hdr == 0) {             // padding, skip to start
        t += (BUF_SIZE - pos);
        pos = 0;
        hdr = *(uint32_t *)&ring[0];
    }
    uint32_t len = hdr;
    if (len > maxlen) return 0; // too big for caller buffer (could return error)
    pos = (pos + sizeof(uint32_t)) & MASK;
    uint32_t first = (len <= BUF_SIZE - pos) ? len : (BUF_SIZE - pos);
    memcpy(buf, &ring[pos], first);
    if (first < len) memcpy((uint8_t*)buf + first, &ring[0], len - first);
    tail = t + sizeof(uint32_t) + len;
    return len;
}

Memory-ordering notes

• On a single-core 32-bit MCU, 32-bit aligned reads/writes are atomic; head/tail are 32-bit. Producer (ISR) only writes head; consumer only writes tail — no locks needed.
• Must ensure compiler doesn't reorder accesses: declare head/tail volatile and avoid optimizing assumptions. If CPU has weak memory model (rare in single-core MCUs), use a compiler barrier or memory barrier around the publish of head in ISR and around reading head in thread (e.g., asm volatile("" ::: "memory")).
• Write payload before publishing head; consumer reads head first, then payload. Padding header (zero) prevents consumer from misreading a split header across wrap.

Edge cases

• Max message size < BUF_SIZE - sizeof(uint32_t)
• ISR must be short; memcpy can be optimized or replaced with DMA if heavy.
• Ensure BUF_SIZE power-of-two for mask arithmetic.

Approach
Use power-of-two capacity so index wrap is mask = size - 1. Keep head (read index) and tail (write index) as unsigned integers that monotonically increase; buffer index = idx & mask. For ARM Cortex‑M (single core, byte store/read atomic), use volatile for head/tail and memory ordering via compiler barriers (asm volatile("" ::: "memory")) to prevent reordering between producer (ISR) and consumer (main). No interrupt disabling.

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

struct rb {
    uint8_t *buf;
    size_t mask;        // size - 1
    volatile uint32_t head; // consumer reads
    volatile uint32_t tail; // producer writes
};

static struct rb rb_inst;

void rb_init(uint8_t *buf, size_t size) {
    // size must be power of two
    rb_inst.buf = buf;
    rb_inst.mask = size - 1;
    rb_inst.head = rb_inst.tail = 0;
}

/* Compiler memory barrier to prevent reordering */
static inline void barrier(void) { asm volatile ("" ::: "memory"); }

bool rb_push(uint8_t b) {
    uint32_t tail = rb_inst.tail;
    uint32_t head = rb_inst.head; /* read consumer index */
    uint32_t next = tail + 1;
    if ((next - head) > (rb_inst.mask + 1)) return false; /* full */
    rb_inst.buf[tail & rb_inst.mask] = b;
    barrier(); /* ensure data written before updating tail */
    rb_inst.tail = next;
    return true;
}

bool rb_pop(uint8_t *out) {
    uint32_t head = rb_inst.head;
    uint32_t tail = rb_inst.tail; /* read producer index */
    if (head == tail) return false; /* empty */
    *out = rb_inst.buf[head & rb_inst.mask];
    barrier(); /* ensure read completes before advancing head */
    rb_inst.head = head + 1;
    return true;
}

Explanation & Assumptions

• SPSC: producer only writes tail and buffer slot; consumer only writes head.
• volatile prevents compiler caching of head/tail. The memory barrier prevents compiler (and on ARM, typical out-of-order) reordering of data access and index update.
• On ARM Cortex‑M (no cache, single core), this is sufficient; if using Cortex‑M with DMA/shared memory or multicore, stronger barriers (DMB) or atomic ops needed.

Complexity & Edge Cases

• O(1) push/pop, uses size power-of-two. Check size validity at init (not shown). Must ensure buffer pointer lifetime > rb usage.