ereader_m33.h File Reference

Shared contract for the "render a held e-reader page on the M33" demo. More...

#include <stdint.h>
#include "ra8_board_ek_ra8d2_dualcore.h"

Include dependency graph for ereader_m33.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	erm33_mailbox_t
	Cross-core progress block backed by a fixed shared-SRAM address. More...

Enumerations
enum	erm33_mailbox_addr_t : uintptr_t { k_erm33_mailbox_addr = (uintptr_t)k_ra8_board_shared_ram_base }
	Fixed shared-SRAM base address of the progress mailbox. More...
enum	erm33_sdram_addr_t : uintptr_t {   k_erm33_sdram_base = 0x68000000U ,   k_erm33_sdram_end = 0x6C000000U }
	Base + extent of the external SDRAM window the held page lives in. More...
enum	erm33_fb_geom_t : uint32_t {   k_erm33_fb_width = 256U ,   k_erm33_fb_height = 64U ,   k_erm33_fb_bpp = 2U ,   k_erm33_fb_stride = 512U ,   k_erm33_fb_bytes = 32768U ,   k_erm33_fb_cols = 32U ,   k_erm33_fb_rows = 4U }
	Geometry of the RGB565 page framebuffer both images agree on. More...
enum	erm33_const_t : uint32_t {   k_erm33_magic = 0x45524D33U ,   k_erm33_m33_sig = 0x33524452U ,   k_erm33_status_running = 0U ,   k_erm33_status_ok = 1U ,   k_erm33_status_bad_book = 2U ,   k_erm33_status_render_fail = 3U ,   k_erm33_fb_format_rgb565 = 2U ,   k_erm33_page_chars = 128U }
	Signatures, status codes, the RGB565 format tag, and the page width shared by both core images. More...
enum	erm33_cycle_t : uint32_t {   k_erm33_max_turns = 3U ,   k_erm33_touch_dwell = 4096U }
	Bounds for the #150 park / wake / re-render mode-switch cycle. More...

Functions
static volatile erm33_mailbox_t *	erm33_mailbox (void)
	Typed pointer to the fixed-address shared progress mailbox.

Detailed Description

Shared contract for the "render a held e-reader page on the M33" demo.

Tag

[Ring 6 / APP] {World: S}

This header pins the cross-core contract for the #150 power-saving model: the Cortex-M85 (primary, "CPU0") does the one-time heavy work – it owns the baked book and could open / compile it at 1 GHz – then hands the reader to the Cortex-M33 (secondary, "CPU1") and PARKS. The slow core renders one held e-reader page into a real RGB565 framebuffer in external SDRAM through the production ra8_gfx text path, then HOLDS that page – exactly the idle posture an e-reader spends almost all its time in, now at a fraction of the power while the M85 @ 1 GHz sleeps in WFI. "Power saving = drop to the slow core."

Two shared regions both core images must agree on:

1. The progress mailbox (erm33_mailbox_t) at a fixed on-chip SRAM address (k_erm33_mailbox_addr). Each core is a separate compiled image with its own linker script, so a static global in one image is invisible to the other; the one name both images resolve identically is a hard-coded address. Per HUM Ch 58.1 "SRAM" Table 58.1 p 3527 the on-chip data SRAM is SRAM0..SRAM2 (512 KiB each) plus SRAM3 (128 KiB), spanning 0x22000000.. 0x221A0000. The M85 image owns SRAM0+SRAM1 (0x22000000..0x22100000) and the M33 image owns the top 64 KiB of SRAM3 (0x22190000..0x221A0000); the mailbox at 0x22100000 (the start of SRAM2) is left unclaimed by both, so it is backed by the same physical SRAM on both sides with no overlap.
2. The page framebuffer in external SDRAM (k_erm33_sdram_base, 0x68000000). Unlike the mailbox the framebuffer is NOT at a fixed shared address: the M33 places it in its own image's .sdram_bss and PUBLISHES the base + geometry into the mailbox (fb_base / fb_width / ...), the same way the sibling compile_on_m33 publishes its emitted blob's base + length. The M33 also publishes a CRC-32 it computed over those rendered pixels.

Why the M33 CRCs its own framebuffer: on the ra8_emulator host emulator the two cores share only the on-chip SRAM host buffer; each core's external-SDRAM window is a separate mapping, so the parked M85 cannot read back the bytes the M33 wrote at 0x68000000. The M33 therefore reads its own SDRAM framebuffer back to fold a CRC-32 – which is itself the proof that real pixels landed in SDRAM – and publishes that value through the shared mailbox. The M85 reports the published CRC; the ra8_emulator gate asserts it against a golden. On silicon the single physical SDRAM is shared, so an M85 re-read would match.

Coherency: this app's system_init.c leaves the M85 data cache OFF, so a store from one core is visible to the other once a dsb has drained the write buffer; no cache clean / invalidate dance is needed. The mailbox fields are volatile so the compiler emits a real load / store on every access.

Protocol (the reader handoff + the held-page handshake + the #150 mode-switch):

1. M85 zeros the mailbox, stamps k_erm33_magic, dsb.
2. M85 arms the IPC0 receive IRQ (its wake-from-WFI source), configures the LPM block, releases the M33, and waits for the first held page.
3. M33 stamps k_erm33_m33_sig, validates the baked book, lays its opening page text out with ra8_gfx_text_out, renders it into the SDRAM RGB565 framebuffer, folds a CRC-32 over those pixels, publishes fb_base / fb_width / fb_height / fb_stride / fb_format / fb_crc / glyph_count, sets status = ok and done = 1, then HOLDS the page.
4. M85 waits for done, validates the descriptor, logs the page-0 verdict "ereader_m33 ... crc=<hex> PASS", then enters the MODE-SWITCH cycle.
5. M85 PARKS: writes the CGC clock-gate (down-clocks an idle oscillator via the LPM clock-stop matrix) and drops into Sleep-mode WFI. The slow M33 is now the only running core, holding the page and polling a (fake) touch input – the e-reader's steady-state idle posture.
6. On a page-turn touch the M33 bumps turn_req and POKES the M85 over IPC0 (ra8_ipc_send_event), waking it from WFI – the #149 wake mechanism.
7. The woken M85 restores its clocks, does the "heavy" work (the next-page decision the 1 GHz core owns), acknowledges via turn_ack, and re-parks.
8. The M33 observes the ack, RE-RENDERS the held page (re-folding the same deterministic CRC), publishes turn_done, and holds again. Steps 5..8 repeat k_erm33_max_turns times, then both cores park for good.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file ereader_m33.h.

Enumeration Type Documentation

erm33_const_t

enum erm33_const_t : uint32_t

Signatures, status codes, the RGB565 format tag, and the page width shared by both core images.

k_erm33_magic ("ERM3") lets the M33 confirm the mailbox is live before trusting it; k_erm33_m33_sig is the boot sentinel the M33 stamps so the M85 can prove the second core left reset. k_erm33_fb_format_rgb565 is the ra8_gfx_format_t value the M33 publishes in fb_format (cross-checked against the real enum by a static_assert in the M33 image). k_erm33_page_chars is the fixed character capacity of the held page.

See also

erm33_mailbox_t

Since

0.1.0

Enumerator
k_erm33_magic	"ERM3" – M85 stamps it when ready.
k_erm33_m33_sig	"RDR3" boot sentinel written by M33.
k_erm33_status_running	status: M33 is rendering the page.
k_erm33_status_ok	status: page rendered + published.
k_erm33_status_bad_book	status: baked book failed validation.
k_erm33_status_render_fail	status: ra8_gfx render path failed.
k_erm33_fb_format_rgb565	Published fb_format (RGB565).
k_erm33_page_chars	Characters the held page can carry.

Definition at line 168 of file ereader_m33.h.

erm33_cycle_t

enum erm33_cycle_t : uint32_t

Bounds for the #150 park / wake / re-render mode-switch cycle.

The M85 parks and the M33 holds the page; k_erm33_max_turns is the deterministic number of page-turn handoffs the demo exercises before both cores park for good. k_erm33_touch_dwell is the bounded count of hold-loop iterations the M33 spins as a fake touch latency between page turns – a deterministic stand-in for polling the GT911 touch controller (the real touch poll is a HIL follow-up, see the README). Kept small so the ra8_emulator gate completes the whole cycle in a handful of instruction chunks. Both are uint32_t so the M33 / M85 loop bounds are a single fixed type.

Invariant

k_erm33_max_turns >= 1 (at least one handoff is exercised).

See also

erm33_mailbox_t

Since

0.1.0

Enumerator
k_erm33_max_turns	Page-turn handoffs the cycle exercises.
k_erm33_touch_dwell	M33 hold-loop spins per simulated touch wait.

Definition at line 196 of file ereader_m33.h.

erm33_fb_geom_t

enum erm33_fb_geom_t : uint32_t

Geometry of the RGB565 page framebuffer both images agree on.

A small landscape page strip rendered through ra8_gfx: RGB565 (two bytes per pixel, the EK-RA8D2 panel's native format), k_erm33_fb_width pixels wide by k_erm33_fb_height tall. With the 8x16 ra8_gfx font that is k_erm33_fb_cols glyph columns by k_erm33_fb_rows glyph rows, enough for the k_erm33_page_chars characters one held page carries. Kept deliberately tiny so the CRC-32 over the whole plane is fast and stable for the ra8_emulator gate.

Invariant

k_erm33_fb_stride == k_erm33_fb_width * k_erm33_fb_bpp.

k_erm33_fb_bytes == k_erm33_fb_stride * k_erm33_fb_height.

k_erm33_fb_cols * k_erm33_fb_rows == k_erm33_page_chars.

Since

0.1.0

Enumerator
k_erm33_fb_width	Plane width in pixels.
k_erm33_fb_height	Plane height in pixels (4 glyph rows of 16).
k_erm33_fb_bpp	Bytes per pixel (RGB565).
k_erm33_fb_stride	Bytes per pixel row (width * bpp).
k_erm33_fb_bytes	Total plane size in bytes (stride * height).
k_erm33_fb_cols	Glyph columns (width / 8-px glyph).
k_erm33_fb_rows	Glyph rows (height / 16-px glyph).

Definition at line 143 of file ereader_m33.h.

erm33_mailbox_addr_t

enum erm33_mailbox_addr_t : uintptr_t

Fixed shared-SRAM base address of the progress mailbox.

The mailbox sits at the base of the CPU0 <-> CPU1 window. The window itself is a board fact, declared once in ra8_board_ek_ra8d2_dualcore.h along with why both linker scripts leave it free; this app only names its own slice of it.

Invariant

The address is 16-byte aligned (cache-line safe).

See also

ra8_board_dualcore_addr_t

erm33_mailbox()

Since

0.1.0

Enumerator
k_erm33_mailbox_addr	Mailbox base = window base.

Definition at line 104 of file ereader_m33.h.

erm33_sdram_addr_t

enum erm33_sdram_addr_t : uintptr_t

Base + extent of the external SDRAM window the held page lives in.

The 64 MiB external SDRAM maps at 0x68000000. The M33 places its page framebuffer in .sdram_bss near this base and publishes the exact address in fb_base; the M85 only uses these bounds to sanity-check that the published base lies inside the SDRAM window. Declared uintptr_t so the constants cast to a pointer correctly on both the 32-bit target and the 64-bit unit-test host.

Invariant

k_erm33_sdram_base < k_erm33_sdram_end.

Since

0.1.0

Enumerator
k_erm33_sdram_base	External SDRAM window base.
k_erm33_sdram_end	External SDRAM window end (+64 MiB).

Definition at line 122 of file ereader_m33.h.

Function Documentation

erm33_mailbox()

volatile erm33_mailbox_t * erm33_mailbox ( void )

inlinestatic

Typed pointer to the fixed-address shared progress mailbox.

Inlined so both core images compute the identical address with no shared translation unit. Returns the same physical SRAM location on the M85 and the M33.

Returns

Pointer to the mailbox at k_erm33_mailbox_addr.

Return values

non-NULL

Always; the address is a compile-time constant.

Precondition

The linker scripts of both images leave the mailbox word unallocated.

The M85 data cache is disabled (see file header).

Postcondition

Returns a valid volatile pointer; never NULL.

No side effects.

Note

Callable from either core; the pointer arithmetic is identical.

Since

0.1.0

Definition at line 263 of file ereader_m33.h.

References k_erm33_mailbox_addr.

Referenced by cpu1_run_reader(), and main().