Foundations refresh

/* Power-of-two size for bitmask wrap (no division) */
#define RING_SIZE   256u          /* must be power of 2 */
#define RING_MASK   (RING_SIZE - 1u)

typedef struct {
    uint8_t  buf[RING_SIZE];
    volatile uint32_t head;       /* written by producer (ISR) */
    volatile uint32_t tail;       /* written by consumer (task) */
} RingBuf_t;

/* Single producer / single consumer — lock-free on Cortex-M */
static inline bool rb_push(RingBuf_t *rb, uint8_t byte) {
    uint32_t next = (rb->head + 1u) & RING_MASK;
    if (next == rb->tail) return false;   /* full */
    rb->buf[rb->head] = byte;
    rb->head = next;
    return true;
}

static inline bool rb_pop(RingBuf_t *rb, uint8_t *out) {
    if (rb->head == rb->tail) return false;  /* empty */
    *out = rb->buf[rb->tail];
    rb->tail = (rb->tail + 1u) & RING_MASK;
    return true;
}

static inline uint32_t rb_count(const RingBuf_t *rb) {
    return (rb->head - rb->tail) & RING_MASK;
}

typedef int32_t error_t;

#define ERR_OK           (0)
#define ERR_INVALID_ARG  (-1)
#define ERR_TIMEOUT      (-2)
#define ERR_BUSY         (-3)
#define ERR_OVERFLOW     (-4)

/* Every function that can fail returns error_t.
   Callers must check the return value — always. */
error_t UART_Write(const uint8_t *buf, uint16_t len) {
    if (buf == NULL || len == 0u) {
        return ERR_INVALID_ARG;
    }
    /* ... implementation ... */
    return ERR_OK;
}

/* Usage — never ignore: */
error_t err = UART_Write(data, len);
if (err != ERR_OK) {
    LOG_ERROR("UART write failed: %d", err);
    return err;   /* propagate up */
}

typedef enum { ST_IDLE, ST_RECEIVING, ST_PROCESSING, ST_ERROR, ST_COUNT } State_t;
typedef enum { EV_START, EV_BYTE, EV_END, EV_TIMEOUT, EV_COUNT } Event_t;

typedef void (*ActionFn_t)(void);

typedef struct {
    State_t   next_state;
    ActionFn_t action;
} Transition_t;

/* Transition table: [current_state][event] */
static const Transition_t FSM_TABLE[ST_COUNT][EV_COUNT] = {
    /*            EV_START                EV_BYTE                 EV_END                  EV_TIMEOUT         */
    [ST_IDLE]     = {{ST_RECEIVING, on_start}, {ST_IDLE, NULL},     {ST_IDLE, NULL},        {ST_IDLE, NULL}},
    [ST_RECEIVING]= {{ST_IDLE, on_error},      {ST_RECEIVING,on_byte},{ST_PROCESSING,on_end},{ST_ERROR,on_timeout}},
    [ST_PROCESSING]={{ST_IDLE, on_error},      {ST_IDLE, on_error},  {ST_IDLE, on_done},     {ST_ERROR,on_timeout}},
    [ST_ERROR]    = {{ST_IDLE, on_reset},      {ST_ERROR, NULL},     {ST_IDLE, on_reset},    {ST_ERROR, NULL}},
};

static State_t g_state = ST_IDLE;

void FSM_Dispatch(Event_t event) {
    const Transition_t *t = &FSM_TABLE[g_state][event];
    if (t->action != NULL) {
        t->action();
    }
    g_state = t->next_state;
}

#define POOL_BLOCK_SIZE   64u
#define POOL_BLOCK_COUNT  16u

typedef struct {
    uint8_t  data[POOL_BLOCK_SIZE];
    bool     in_use;
} Block_t;

static Block_t s_pool[POOL_BLOCK_COUNT];   /* lives in .bss */

void* Pool_Alloc(void) {
    for (uint32_t i = 0; i < POOL_BLOCK_COUNT; i++) {
        if (!s_pool[i].in_use) {
            s_pool[i].in_use = true;
            return s_pool[i].data;
        }
    }
    return NULL;   /* pool exhausted — never hang, return NULL */
}

void Pool_Free(void *ptr) {
    if (ptr == NULL) return;
    Block_t *b = (Block_t *)((uint8_t *)ptr - offsetof(Block_t, data));
    ASSERT(b >= s_pool && b < s_pool + POOL_BLOCK_COUNT);
    b->in_use = false;
}

/* test/test_ring_buffer.c */
#include "unity.h"
#include "ring_buffer.h"

static RingBuf_t rb;

void setUp(void)    { rb_init(&rb); }
void tearDown(void) { }

void test_RingBuf_InitiallyEmpty(void) {
    TEST_ASSERT_TRUE(rb_empty(&rb));
    TEST_ASSERT_FALSE(rb_full(&rb));
}

void test_RingBuf_PushPop_SingleByte(void) {
    TEST_ASSERT_TRUE(rb_push(&rb, 0xAB));
    uint8_t out = 0;
    TEST_ASSERT_TRUE(rb_pop(&rb, &out));
    TEST_ASSERT_EQUAL_HEX8(0xAB, out);
    TEST_ASSERT_TRUE(rb_empty(&rb));
}

void test_RingBuf_PushOnFull_ReturnsFalse(void) {
    for (uint32_t i = 0; i < RING_SIZE - 1; i++) {
        TEST_ASSERT_TRUE(rb_push(&rb, (uint8_t)i));
    }
    TEST_ASSERT_TRUE(rb_full(&rb));
    TEST_ASSERT_FALSE(rb_push(&rb, 0xFF));  /* must fail */
}

void test_RingBuf_WrapAround_DataIntegrity(void) {
    /* Fill, drain halfway, fill again — verify wrap-around is correct */
    uint8_t in, out;
    for (uint8_t i = 0; i < 128; i++) rb_push(&rb, i);
    for (uint8_t i = 0; i < 128; i++) rb_pop(&rb, &out);
    for (uint8_t i = 0; i < 100; i++) rb_push(&rb, i);
    for (uint8_t i = 0; i < 100; i++) {
        rb_pop(&rb, &out);
        TEST_ASSERT_EQUAL_UINT8(i, out);
    }
}