Designing a Driver Layer (HAL)

// uart_driver.cpp - an interrupt-driven UART driver, run against a simulated UART
#include <cstddef>
#include <cstdint>
#include <cstdio>
#include <optional>
#include <span>

// ---- the register block, laid out as the datasheet shows it --------------------------------
struct UartRegs {
    volatile uint32_t SR;       // 0x00 status
    volatile uint32_t DR;       // 0x04 data: write to send, read to receive
    volatile uint32_t BRR;      // 0x08 baud rate divisor: clock / baud
    volatile uint32_t CR1;      // 0x0C control
};
static_assert(sizeof(UartRegs) == 16, "UartRegs does not match the datasheet");

namespace sr {
constexpr uint32_t TXE = 1u << 7;       // the data register is free for the next byte to send
constexpr uint32_t RXNE = 1u << 5;      // a received byte is waiting in the data register
}  // namespace sr
namespace cr1 {
constexpr uint32_t UE = 1u << 13;       // UART on
constexpr uint32_t TXEIE = 1u << 7;     // interrupt when TXE is set
constexpr uint32_t RXNEIE = 1u << 5;    // interrupt when RXNE is set
constexpr uint32_t TE = 1u << 3;        // transmitter on
constexpr uint32_t RE = 1u << 2;        // receiver on
}  // namespace cr1

// ---- pieces from earlier volumes ------------------------------------------------------------
static uint32_t primask = 0;            // the interrupt mask, faked for the PC, as in Volume 03

class InterruptLock {
public:
    InterruptLock() : saved_(primask) { primask = 1; }
    ~InterruptLock() { primask = saved_; }
    InterruptLock(const InterruptLock &) = delete;
    InterruptLock &operator=(const InterruptLock &) = delete;

private:
    uint32_t saved_;
};

template <typename T, size_t N>
class RingBuffer {                      // the ring buffer from Volume 05
public:
    bool push(T item) {
        if (count_ == N) {
            return false;
        }
        items_[head_] = item;
        head_ = (head_ + 1) % N;
        count_++;
        return true;
    }
    bool pop(T &item) {
        if (count_ == 0) {
            return false;
        }
        item = items_[tail_];
        tail_ = (tail_ + 1) % N;
        count_--;
        return true;
    }

private:
    T items_[N] = {};
    size_t head_ = 0;
    size_t tail_ = 0;
    size_t count_ = 0;
};

enum class [[nodiscard]] Status : uint8_t { ok, queue_full };

// ---- the driver -----------------------------------------------------------------------------
class Uart {
public:
    constexpr Uart(UartRegs &regs, uint32_t clock_hz) : regs_(regs), clock_hz_(clock_hz) {}

    void start(uint32_t baud) {
        regs_.BRR = (clock_hz_ + baud / 2) / baud;          // rounded, as in Embedded C
        regs_.CR1 = cr1::UE | cr1::TE | cr1::RE | cr1::RXNEIE;
    }

    // Queue bytes to send, and let the interrupt send them. Never waits.
    Status write(std::span<const uint8_t> bytes) {
        InterruptLock lock;
        Status result = Status::ok;
        for (uint8_t b : bytes) {
            if (!tx_.push(b)) {
                result = Status::queue_full;                // the rest will not fit
                break;
            }
        }
        regs_.CR1 = regs_.CR1 | cr1::TXEIE;                  // there is work: ask for TXE interrupts
        return result;
    }

    // A received byte, if one has arrived. Never waits.
    std::optional<uint8_t> read() {
        InterruptLock lock;
        uint8_t b = 0;
        if (rx_.pop(b)) {
            return b;
        }
        return std::nullopt;
    }

    // Called from the interrupt handler.
    void on_interrupt() {
        uint32_t status = regs_.SR;
        if (status & sr::RXNE) {
            uint8_t b = static_cast<uint8_t>(regs_.DR);     // reading DR clears RXNE
            if (!rx_.push(b)) {
                dropped_++;
            }
        }
        if ((status & sr::TXE) && (regs_.CR1 & cr1::TXEIE)) {
            uint8_t b = 0;
            if (tx_.pop(b)) {
                regs_.DR = b;
            } else {
                regs_.CR1 = regs_.CR1 & ~cr1::TXEIE;        // nothing left: stop asking
            }
        }
    }

    uint32_t dropped() const { return dropped_; }

private:
    UartRegs &regs_;
    uint32_t clock_hz_;
    RingBuffer<uint8_t, 8> tx_;
    RingBuffer<uint8_t, 8> rx_;
    uint32_t dropped_ = 0;
};

// ---- the board: one UART, and its interrupt handler -------------------------------------------
static UartRegs fake_usart1;                             // on the chip: the registers at their address
constinit Uart console(fake_usart1, 16'000'000);         // ready before start-up code runs

extern "C" void USART1_IRQHandler() { console.on_interrupt(); }

// ---- the simulated UART: what the silicon does by itself --------------------------------------
static char wire[64];
static size_t wire_length = 0;

// While the TXE interrupt is enabled, the UART keeps asking for bytes, and sends each one.
static void hw_transmit() {
    constexpr uint32_t untouched = 0xFFFFFFFFu;
    while (fake_usart1.CR1 & cr1::TXEIE) {
        fake_usart1.SR = fake_usart1.SR | sr::TXE;
        fake_usart1.DR = untouched;
        USART1_IRQHandler();
        if (fake_usart1.DR != untouched && wire_length < sizeof wire) {
            wire[wire_length] = static_cast<char>(fake_usart1.DR);
            wire_length++;
        }
    }
}

// A byte arrives on the wire: the UART stores it, raises RXNE, and interrupts.
static void hw_receive(uint8_t b) {
    fake_usart1.DR = b;
    fake_usart1.SR = (fake_usart1.SR | sr::RXNE) & ~sr::TXE;
    USART1_IRQHandler();
    fake_usart1.SR = fake_usart1.SR & ~sr::RXNE;
}

int main() {
    console.start(115200);
    std::printf("BRR = %u, CR1 = 0x%04X\n", static_cast<unsigned>(fake_usart1.BRR),
                static_cast<unsigned>(fake_usart1.CR1));

    const uint8_t hello[] = {'h', 'e', 'l', 'l', 'o', '\n'};
    Status s = console.write(hello);
    hw_transmit();
    std::printf("write: %s, the wire carried %zu bytes: %.*s", s == Status::ok ? "ok" : "queue full",
                wire_length, static_cast<int>(wire_length), wire);
    std::printf("TX interrupt afterwards: %s\n", (fake_usart1.CR1 & cr1::TXEIE) ? "on" : "off");

    hw_receive('O');
    hw_receive('K');
    std::printf("received:");
    while (std::optional<uint8_t> b = console.read()) {
        std::printf(" '%c'", *b);
    }
    std::printf("\n");

    const uint8_t too_long[] = {'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l'};
    s = console.write(too_long);
    std::printf("writing 12 bytes into an 8-byte queue: %s\n", s == Status::ok ? "ok" : "queue full");
    size_t before = wire_length;
    hw_transmit();
    std::printf("the bytes that fitted still went out: %.*s\n", static_cast<int>(wire_length - before),
                wire + before);
    return 0;
}