- Generated by
1.16.1
|
ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
|
A paragraph each on the libraries a newcomer meets first. This is a reading order, not an index: libs/README.md lists every library in the tree, and the public header named under "main entry points" carries the full API with the project's mandatory Doxygen tag set.
Vendored third-party libraries live under libs/third_party/ and are documented as SOUP under docs/SOUP/; they are not covered here.
Foundational primitives that every other library depends on: error codes (ra8_err_t), structured logging (ra8_log_*), runtime asserts, the bit-position constants used throughout the HAL, and the stack canary supervisor. Nothing in ra8_core touches a hardware register – it is the project's freestanding-C runtime.
The hand-written hardware abstraction layer for the RA8D2 on-chip peripherals: the serial buses, the timers and PWM, analog in and out, the interrupt and event fabric, DMA, external memory, networking, display and camera, USB, crypto and the watchdogs – one driver per peripheral, over a bank of ra8_*_regs.h register-map headers written from the HUM. Every driver returns ra8_err_t and is unit-tested against tests/mocks/src/ra8_fake_mmap.c, which presents the MCU peripheral address space as host-side RAM.
Board-support pinning and resource-id table for the EK-RA8D2 v1 evaluation kit: LED handles, push-button handles, on-board PMOD mappings, and the ra8_board_get_info() discovery call apps use to key off the exact board variant.
Cortex-M85 Memory Protection Unit configuration helper. Lets apps declare an MPU layout as a static ra8_mpu_cfg_t table at init-time and have the helper program the regions in the right order, then enable the MPU.
TrustZone Non-Secure Callable veneers. Lives in the secure world and exposes a curated subset of secure-side services (key vault, OTA commit, register windows, etc.) to the non-secure firmware via the __attribute__((cmse_nonsecure_entry)) ABI. There is no public header per se – the veneer set is split across ra8_nsc.h, ra8_nsc_cgc.h, ra8_nsc_comms.h, ra8_nsc_io.h and ra8_nsc_veneer.h.
Network platform-abstraction layer over the RA8D2 ESWM block. Owns the DMA descriptor rings, MAC bring-up, and the byte pump up to whatever IP stack sits above it. Stack-agnostic by design: the NetX Duo port in port/netxduo/ builds on it.
USB device-mode platform-abstraction layer. Hides the FS-vs-HS controller choice, the MSTP / clock-gate dance, and per-endpoint software ring buffers behind a small stack-agnostic API. No USB stack is currently compiled against this seam; a future CherryUSB, TinyUSB, or hand-rolled adapter can bind without changing the header.
Thin facade over the vendored Mbed TLS + TF-PSA-Crypto stack. Hands out TLS sessions from a fixed-size static pool (NASA Power-of-10 Rule 3) and translates Mbed TLS error codes into ra8_err_t. Higher-level apps (HTTPS client, MQTT/TLS, OTA fetch) call into this facade instead of pulling Mbed TLS directly.
Application-level facade over tf-psa-crypto. Wraps PSA Crypto API key-import / sign / verify / AEAD encrypt+decrypt / random calls and returns ra8_err_t. Pairs with the secure-side key vault exposed through ra8_nsc_key_vault.
Over-the-air firmware update orchestrator: manifest fetch, slot management against the dual-bank Octo-SPI flash layout, signed image verification (delegated to ra8_psa_crypto), and the secure- side commit veneer in ra8_nsc_ota.
Cellular modem AT command/response driver layered on caller-supplied byte-I/O and monotonic-time callbacks. The production modem demo binds those callbacks to RA8 SCI transport; tests use in-memory fakes. The module owns the line buffer, response parser, and URC dispatcher.
The single integration boundary between this firmware and the ESP32-C6 companion radio. Owns the esp-hosted payload header and its checksum, the serial endpoint's TLV envelope, the protobuf Rpc control plane (encode, decode, UID correlation, event decode), the polled transaction pump, the 802.3 data plane, and Wi-Fi station control. Everything hardware-shaped sits behind a three-function transport seam, which port/esp-hosted/ binds to the OS-abstraction vtable on the board and tests/mocks/src/ra8_c6_model.c binds to a co-processor model on the host.
The generated protobuf codec allocates, and this firmware has no heap, so the codec is handed a bump allocator over a caller-supplied array that is emptied after every message – which keeps the whole control plane inside NASA Power of 10 Rule 3.
First-party FAT12/FAT16/FAT32 + exFAT filesystem (read + write) backed by a swappable block-device interface. The platform's only filesystem since the vendored FileX was retired (#611). Current consumers include the ereader storage paths, filesystem format/mount app, page cache, and RA8 I/O demos; the ThreadX LevelX demo uses LevelX directly.
EPUB (.epub) reader and chapter iterator. Walks the ZIP container through miniz, parses the OPF manifest + NCX spine, and hands chapter XHTML to reflow for layout.
HTML reflow + paginate engine for the ereader: it pages chapter content into the viewport so the GLCDC layer can blit one page at a time. The default engine is first-party, zero-allocation and MC/DC-testable; a litehtml-backed variant exists behind a build option that is off, and docs/EPUB_CONFORMANCE.md is the contract for what either one renders.
Software 2D graphics primitives for the parallel TFT: framebuffer clear, pixel/line/rect/circle, bitmap blits, and bundled bitmap fonts. Sits on top of the GLCDC driver in ra8_hal.
Resistive/capacitive touch-screen calibration utility. Runs the classic 3- or 5-point capture sequence, computes the affine transform, and applies it to live raw samples.
Power-profiling helper that inserts named region markers into the firmware so power-rail captures (Joulescope or J-Link energy probe) can be correlated to firmware activity. Trivially small, but used across most of the example apps.
ThreadX-aware watchdog supervisor. Provides a per-thread check-in registry so a hung thread starves the watchdog refresh and triggers a reset, instead of one healthy thread keeping the watchdog happy indefinitely. Falls back to a plain refresh path in non-RTOS apps.
1.16.1