CPU1 (Cortex-M33 secondary core) image: full text/CSS/SVG EPUB->RABOOK1 compile. More...

#include <stdint.h>
#include <string.h>
#include "book.h"
#include "compile_on_m33.h"
#include "epub.h"
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_ipc.h"
#include "ra8_rabook_pipeline.h"
#include "rabook_compile.h"

Include dependency graph for cpu1_main.c:

Enumerations
enum	m33_arena_cap_t : uint32_t { k_arena_chapters = 8U , k_arena_nodes = 256U , k_arena_attrs = 64U , k_arena_styles = 4U , k_arena_images = 8U , k_arena_string = 8U * 1024U , k_arena_imgpool = 64U * 1024U , k_arena_xhtml = 16U * 1024U , k_arena_imgraw = 16U * 1024U , k_arena_css = 16U * 1024U }
	Capacities of the M33 text/CSS/SVG compile's caller-owned arenas. More...
enum	cpu1_ipc_t : uint8_t { k_cpu1_ipc_wake_channel = 0U }
	IPC channel the M33 pokes to wake the parked M85. More...

Functions
void	cpu1_reset_handler (void)
	CPU1 reset handler: minimal C-runtime init, then run the emitter.
static bool	bind_compile (ra8_rabook_buffers_t buf, ra8_rabook_pipeline_scratch_t scr)
	Point a builder + pipeline-scratch view at the SDRAM arenas + output.
static bool	compile_fixture (const void *out_blob, uint32_t out_len)
	Compile the baked parity fixture EPUB into the shared output blob.
static void	publish_result (volatile com33_mailbox_t mb, const void blob, uint32_t len, bool ok)
	Publish the emitter result into the shared mailbox.
static void	cpu1_park (void)
	Park the M33 forever once the emitter has reported its result.
static void	notify_m85 (void)
	Poke the M85's IPC0 receive line to wake it from WFI.
static void	cpu1_run_compile (void)
	CPU1 emitter entry: build the book, finalize the blob, report.
static void	cpu1_fault_handler (void)
	CPU1 default fault handler: publish a fault status, wake the M85, park.

Variables
uint32_t	g_ra8_ls_cpu1_stack_top
	CPU1 stack top (slot 0 of the M33 vector table).
uint32_t	g_ra8_ls_cpu1_data_start
	CPU1 .data run-region start (in SRAM_CPU1).
uint32_t	g_ra8_ls_cpu1_data_end
	CPU1 .data run-region end.
uint32_t	g_ra8_ls_cpu1_data_load
	CPU1 .data load image (in MRAM_CPU1).
uint32_t	g_ra8_ls_cpu1_bss_start
	CPU1 .bss start (in SRAM_CPU1).
uint32_t	g_ra8_ls_cpu1_bss_end
	CPU1 .bss end.
static epub_book_t	s_book
static book_chapter_t	s_chapters [k_arena_chapters]
static book_node_t	s_nodes [k_arena_nodes]
static book_attr_t	s_attrs [k_arena_attrs]
static book_stylesheet_t	s_styles [k_arena_styles]
static book_image_t	s_images [k_arena_images]
static char	s_string_pool [k_arena_string]
static uint8_t	s_image_pool [k_arena_imgpool]
static uint8_t	s_xhtml [k_arena_xhtml]
static ra8_rabook_xml_workspace_t	s_xml_workspace
static uint8_t	s_image_raw [k_arena_imgraw]
static char	s_css [k_arena_css]
const uintptr_t	g_cpu1_vector_table []

Detailed Description

CPU1 (Cortex-M33 secondary core) image: full text/CSS/SVG EPUB->RABOOK1 compile.

Tag: [Ring 6 / APP] {World: NS}

This is the firmware that runs on the RA8D2's second core, the Cortex-M33, for the #149 compiler offload. It is compiled as a wholly separate ELF (-mcpu=cortex-m33) and embedded into the M85 ELF as a .cpu1_image blob; the M85 hands the work to this core via ra8_cpu1_release (HUM Ch 2.9.1) and PARKS while the slow core compiles the book.

The M33 runs the FULL text/CSS/SVG EPUB->.rabook compile over a baked parity fixture .epub – the exact data path the on-device import offloads:

Stamp k_com33_m33_sig into the shared mailbox so the parked M85 can prove the M33 left reset and is executing user code, then read the job the M85 posted (the staged .epub base/len + output buffer) from the request.
epub_open the M85-staged .epub (shared SRAM, k_com33_epub_addr) as an in-memory media: miniz unzips the container and the bounded XML reader parses the OPF spine/manifest. The M33 compiles whatever the M85 staged, so the same image serves any book (not a baked-in fixture).
rabook_compile_from_epub_to_buffer runs the same pipeline the M85 proved byte-identical to the desktop tool – stylesheets, SVG images (verbatim; raster is compiled out via RA8_RABOOK_NO_RASTER, so no stb_image), the chapter DOM walk, metadata, then ra8_rabook_finalize into the shared output buffer. The builder arenas + epub_book_t live in external SDRAM (.sdram_bss); SRAM_CPU1 holds only small state + stack.
Publish blob_base / blob_len / blob_crc / chapter_count, set status = ok, done = 1. The M85 validates the blob AND byte-compares it to the same golden the desktop/M85 path produced – proving the compile is byte-identical on the secondary core.

Note: Zero dynamic allocation reaching real malloc (NASA Rule 3): miniz uses the bounded epub arena and XML uses explicit caller workspace. The freestanding M33 image links the front end and back end (miniz, xml, epub, rabook_compile/pipeline/gray4) – no stb_image, no ra8_fs (the M85 owns the filesystem; this core finalizes into a buffer).; The M33 deliberately does NOT call ra8_log: ra8_emulator echoes only the primary core's ITM, so an M33 log line would be invisible. Its proof-of-life is the mailbox the M85 narrates.

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

Since: 0.1.0

Definition in file cpu1_main.c.

Enumeration Type Documentation

◆ cpu1_ipc_t

enum cpu1_ipc_t : uint8_t

IPC channel the M33 pokes to wake the parked M85.

IPC0 channel 0 is the CPU1 -> CPU0 direction; writing its IPC0ISET0 raises the IPC0 receive interrupt the M85 armed before release, so the M85 leaves WFI as soon as the result is published.

Since: 0.1.0

Enumerator
k_cpu1_ipc_wake_channel	IPC0 channel 0 (CPU1 -> CPU0).

Definition at line 326 of file cpu1_main.c.

◆ m33_arena_cap_t

enum m33_arena_cap_t : uint32_t

Capacities of the M33 text/CSS/SVG compile's caller-owned arenas.

Sized for the parity fixture (one chapter, a stylesheet, an SVG cover) with comfortable slack. The builder tables/pools, the EPUB parse scratch and epub_book_t all live in external SDRAM (.sdram_bss): epub_book_t alone exceeds the 64 KiB SRAM_CPU1. The finalized blob is laid into the shared output buffer (see com33_blob), never here.

Since: 0.1.0

Enumerator
k_arena_chapters	Chapter-table entries.
k_arena_nodes	Node-table entries.
k_arena_attrs	Attribute-table entries.
k_arena_styles	Stylesheet-table entries.
k_arena_images	Image-table entries.
k_arena_string	String-pool capacity (bytes).
k_arena_imgpool	Image-pool capacity (bytes).
k_arena_xhtml	Chapter XHTML parse scratch (bytes).
k_arena_imgraw	SVG/resource load scratch (bytes).
k_arena_css	Stylesheet load scratch (bytes).

Definition at line 88 of file cpu1_main.c.

Function Documentation

◆ bind_compile()

bool bind_compile	(	ra8_rabook_buffers_t *	buf,
		ra8_rabook_pipeline_scratch_t *	scr )

static

Point a builder + pipeline-scratch view at the SDRAM arenas + output.

Parameters

[out]	buf	Builder buffer descriptor to fill (never NULL).
[out]	scr	Pipeline scratch descriptor to fill (never NULL).

Returns: Whether the views were bound.

Return values

true	`buf` and `scr` reference the SDRAM arenas + shared output.
false	`buf` or `scr` is NULL, or the output address resolved to NULL.

Precondition: buf and scr are writable descriptors.; The SDRAM arenas are linked into the .sdram_bss region.

Postcondition: On true, buf->out addresses the shared blob buffer at k_com33_blob_addr and every other * member is non-NULL with its _cap set.; On true, scr carries xhtml / image_raw / css; img_arena and gray are NULL (raster is excluded – the image is built RA8_RABOOK_NO_RASTER).

Note: Single-threaded; runs in M33 thread mode with no RTOS.

Since: 0.1.0

Definition at line 141 of file cpu1_main.c.

References com33_blob(), k_arena_attrs, k_arena_chapters, k_arena_images, k_arena_imgpool, k_arena_nodes, k_arena_string, k_arena_styles, k_com33_blob_cap, s_attrs, s_chapters, s_css, s_image_pool, s_image_raw, s_images, s_nodes, s_string_pool, s_styles, s_xhtml, and s_xml_workspace.

Referenced by compile_fixture().

◆ compile_fixture()

bool compile_fixture	(	const void **	out_blob,
		uint32_t *	out_len )

static

Compile the baked parity fixture EPUB into the shared output blob.

Opens s_m33_parity_epub in memory, binds the SDRAM builder + scratch arenas, and runs rabook_compile_from_epub_to_buffer – the same byte-identical text/CSS/SVG pipeline the M85 path proved – finalizing the RABOOK1 blob into the shared SRAM2 output buffer (no filesystem). s_book is memset first because it lives in NOLOAD SDRAM the reset handler does not zero. Raster is excluded (RA8_RABOOK_NO_RASTER): the fixture cover is an SVG stored verbatim, so no stb_image is linked into the M33 image.

Parameters

[out]	out_blob	Receives the finalized blob base (in the shared buffer).
[out]	out_len	Receives the finalized blob length in bytes.

Returns: Whether the EPUB compiled to a finalized blob.

Return values

true	The blob was finalized into the shared output buffer.
false	`out_blob` / `out_len` NULL, epub_open failed, or a compile stage overflowed an arena.

Precondition: out_blob and out_len are non-NULL.; The M85 brought up the SDRAM controller before releasing this core.

Postcondition: On true the shared output buffer holds a finalized RABOOK1 blob.; On false the shared output buffer must not be treated as a valid blob.

Note: Single-threaded; runs in M33 thread mode with no RTOS.

Since: 0.1.0

Definition at line 213 of file cpu1_main.c.

References bind_compile(), com33_mailbox(), com33_mailbox_t::epub_base, epub_close(), com33_mailbox_t::epub_len, epub_open(), k_ra8_ok, memset(), rabook_compile_from_epub_to_buffer(), and s_book.

Referenced by cpu1_run_compile().

◆ cpu1_fault_handler()

void cpu1_fault_handler ( void )

static

CPU1 default fault handler: publish a fault status, wake the M85, park.

Every M33 exception slot routes here. Before halting, it stamps k_com33_status_fault into the shared mailbox and sets done, then pokes the M85 over IPC so the parked primary core wakes, observes done, reads the distinct fault status, and reports an explicit secondary-core fault. Without this the M85 – which WFI-idles waiting for the M33's compile-done poke – would sleep forever on a done that a faulted core never sets. The first dsb orders the status ahead of done; the second orders done ahead of the IPC poke. The core then spins; on hardware a watchdog (if enabled) eventually resets it.

Returns: This function never returns.

Note: The core spins in place after publishing the fault.

Precondition: A hardware fault or unhandled exception occurred.; Entered via the M33 exception entry path.

Postcondition: status == k_com33_status_fault and done == 1 are published behind a dsb.; The M33 makes no further forward progress.

Note: Shared default for all CPU1 exception vectors.

Since: 0.1.0

Definition at line 463 of file cpu1_main.c.

References com33_mailbox(), com33_mailbox_t::done, k_com33_status_fault, notify_m85(), and com33_mailbox_t::status.

◆ cpu1_park()

void cpu1_park ( void )

static

Park the M33 forever once the emitter has reported its result.

Returns: This function never returns.

Note: The core spins in place.

Precondition: The mailbox already carries the final status / done.; Entered only after the emitter run completes (or fails to build).

Postcondition: The M33 makes no further forward progress.; The published mailbox state is stable for the M85 to read.

Note: Mirrors the sibling dual-core park loops.

Since: 0.1.0

Definition at line 311 of file cpu1_main.c.

Referenced by cpu1_fail(), cpu1_run_compile(), and cpu1_run_reader().

◆ cpu1_reset_handler()

void cpu1_reset_handler ( void )

CPU1 reset handler: minimal C-runtime init, then run the emitter.

The M33 boots with uninitialised RAM, so before any C code runs this copies .data from its MRAM_CPU1 load image into SRAM_CPU1 and zeroes .bss. The linker exports the region bounds as g_ra8_ls_cpu1_* symbols.

Returns: This function never returns.

Note: Control passes to cpu1_run_compile, which loops forever.

Precondition: Hardware loaded the initial SP from .cpu1_vectors[0].; The M85 released this core via the CPU1ACTCSR handshake.

Postcondition: .data mirrors its MRAM_CPU1 load image.; .bss is zero-filled.

Note: Entered only from the CPU1 vector table; runs in M33 thread mode.

Since: 0.1.0

Definition at line 419 of file cpu1_main.c.

References cpu1_run_compile(), g_ra8_ls_cpu1_bss_end, g_ra8_ls_cpu1_bss_start, g_ra8_ls_cpu1_data_end, g_ra8_ls_cpu1_data_load, g_ra8_ls_cpu1_data_start, and RA8_LOOP_BOUND_RUNTIME.

◆ cpu1_run_compile()

void cpu1_run_compile ( void )

static

CPU1 emitter entry: build the book, finalize the blob, report.

Stamps the boot signature, binds the emitter to its arenas, builds the DOM, finalizes the RABOOK1 blob into the shared output buffer, then publishes the result for the parked M85. Any failure publishes build_fail.

Returns: This function never returns.

Note: Control ends in cpu1_park.

Precondition: cpu1_reset_handler has initialised .data / .bss.; The M85 published k_com33_magic and released this core.

Postcondition: mb->done == 1 with status reflecting the emitter outcome.; On success the shared output buffer holds a finalized RABOOK1 blob.

Note: Single-threaded; runs in M33 thread mode with no RTOS.

Since: 0.1.0

Definition at line 373 of file cpu1_main.c.

References com33_mailbox(), compile_fixture(), cpu1_park(), com33_mailbox_t::done, k_com33_m33_sig, k_com33_req_magic, k_com33_status_no_request, com33_mailbox_t::m33_sig, notify_m85(), publish_result(), com33_mailbox_t::req_magic, and com33_mailbox_t::status.

Referenced by cpu1_reset_handler().

◆ notify_m85()

void notify_m85 ( void )

static

Poke the M85's IPC0 receive line to wake it from WFI.

Writes IPC0ISET0 for the wake channel (HUM Ch 3.2.11 "IPC0ISET0" p 215), asserting IRQ line 0 on the primary core. The mailbox done flag is already published and dsb-ordered ahead of this call, so the woken M85 observes a settled result. The HAL return value is intentionally discarded: a failed poke only costs the M85 a fall-through to its bounded poll, never correctness.

Returns: Nothing.

Precondition: The result mailbox fields and done are published behind a dsb.; The M85 armed the IPC0 receive IRQ before releasing this core.

Postcondition: IPC0 channel-0 IRQ line 0 is asserted toward the M85.; No shared mailbox field is modified.

Note: Single-threaded; runs in M33 thread mode with no RTOS.

Since: 0.1.0

Definition at line 350 of file cpu1_main.c.

References k_cpu1_ipc_wake_channel, k_ra8_ipc_irq_event_0, and ra8_ipc_send_event().

Referenced by cpu1_fault_handler(), cpu1_run_compile(), and run_page_turns().

◆ publish_result()

void publish_result	(	volatile com33_mailbox_t *	mb,
		const void *	blob,
		uint32_t	len,
		bool	ok )

static

Publish the emitter result into the shared mailbox.

On success copies the blob base, length, the blob header's body CRC-32 and the chapter count into the mailbox, drains the write buffer, sets status = ok then done = 1. On failure sets status = build_fail and done = 1. The two dsbs order the payload before status, and status before done, so the parked M85 reads a settled mailbox.

Parameters

[in,out]	mb	Shared mailbox (never NULL).
[in]	blob	Finalized blob base, or NULL on a build failure.
[in]	len	Finalized blob length in bytes (0 on failure).
[in]	ok	Whether the emitter finalized a blob.

Returns: Nothing.

Precondition: mb is the fixed-address mailbox pointer.; On ok, blob points at a finalized RABOOK1 blob of len bytes.

Postcondition: mb->done == 1 with status reflecting success or failure.; On success the blob base / length / CRC / chapter count are published.

Note: Single-threaded; runs in M33 thread mode with no RTOS.

Since: 0.1.0

Definition at line 270 of file cpu1_main.c.

References com33_mailbox_t::blob_base, com33_mailbox_t::blob_crc, com33_mailbox_t::blob_len, book_header(), book_header_t::chapter_count, com33_mailbox_t::chapter_count, book_header_t::crc32_val, com33_mailbox_t::done, k_com33_status_build_fail, k_com33_status_ok, and com33_mailbox_t::status.

Referenced by cpu1_run_compile().

Variable Documentation

◆ g_cpu1_vector_table

const uintptr_t g_cpu1_vector_table[]

Initial value:

                                     = {
  (uintptr_t)&g_ra8_ls_cpu1_stack_top,
  (uintptr_t)&cpu1_reset_handler,
  (uintptr_t)&cpu1_fault_handler,
  (uintptr_t)&cpu1_fault_handler,
  (uintptr_t)&cpu1_fault_handler,
  (uintptr_t)&cpu1_fault_handler,
  (uintptr_t)&cpu1_fault_handler,
  (uintptr_t)&cpu1_fault_handler,
}

Definition at line 490 of file cpu1_main.c.

◆ g_ra8_ls_cpu1_bss_end

uint32_t g_ra8_ls_cpu1_bss_end

extern

CPU1 .bss end.

◆ g_ra8_ls_cpu1_bss_start

uint32_t g_ra8_ls_cpu1_bss_start

extern

CPU1 .bss start (in SRAM_CPU1).

◆ g_ra8_ls_cpu1_data_end

uint32_t g_ra8_ls_cpu1_data_end

extern

CPU1 .data run-region end.

◆ g_ra8_ls_cpu1_data_load

uint32_t g_ra8_ls_cpu1_data_load

extern

CPU1 .data load image (in MRAM_CPU1).

◆ g_ra8_ls_cpu1_data_start

uint32_t g_ra8_ls_cpu1_data_start

extern

CPU1 .data run-region start (in SRAM_CPU1).

◆ g_ra8_ls_cpu1_stack_top

uint32_t g_ra8_ls_cpu1_stack_top

extern

CPU1 stack top (slot 0 of the M33 vector table).

◆ s_attrs

book_attr_t s_attrs[k_arena_attrs]

static

Definition at line 111 of file cpu1_main.c.

Referenced by bind_compile(), and internal_builder().

◆ s_book

epub_book_t s_book

static

Definition at line 108 of file cpu1_main.c.

◆ s_chapters

book_chapter_t s_chapters[k_arena_chapters]

static

Definition at line 109 of file cpu1_main.c.

Referenced by bind_compile(), and internal_builder().

◆ s_css

char s_css[k_arena_css]

static

Definition at line 119 of file cpu1_main.c.

Referenced by bind_compile().

◆ s_image_pool

uint8_t s_image_pool[k_arena_imgpool]

static

Definition at line 115 of file cpu1_main.c.

Referenced by bind_compile().

◆ s_image_raw

uint8_t s_image_raw[k_arena_imgraw]

static

Definition at line 118 of file cpu1_main.c.

Referenced by bind_compile().

◆ s_images

book_image_t s_images[k_arena_images]

static

Definition at line 113 of file cpu1_main.c.

Referenced by bind_compile(), and internal_builder().

◆ s_nodes

book_node_t s_nodes[k_arena_nodes]

static

Definition at line 110 of file cpu1_main.c.

Referenced by bind_compile(), er_build_library(), er_render_boxnodes(), and internal_builder().

◆ s_string_pool

char s_string_pool[k_arena_string]

static

Definition at line 114 of file cpu1_main.c.

Referenced by bind_compile().

◆ s_styles

book_stylesheet_t s_styles[k_arena_styles]

static

Definition at line 112 of file cpu1_main.c.

Referenced by bind_compile(), and internal_builder().

◆ s_xhtml

uint8_t s_xhtml[k_arena_xhtml]

static

Definition at line 116 of file cpu1_main.c.

◆ s_xml_workspace

ra8_rabook_xml_workspace_t s_xml_workspace

static

Definition at line 117 of file cpu1_main.c.

Referenced by bind_compile().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ cpu1_ipc_t

◆ m33_arena_cap_t

Function Documentation

◆ bind_compile()

◆ compile_fixture()

◆ cpu1_fault_handler()

◆ cpu1_park()

◆ cpu1_reset_handler()

◆ cpu1_run_compile()

◆ notify_m85()

◆ publish_result()

Variable Documentation

◆ g_cpu1_vector_table

◆ g_ra8_ls_cpu1_bss_end

◆ g_ra8_ls_cpu1_bss_start

◆ g_ra8_ls_cpu1_data_end

◆ g_ra8_ls_cpu1_data_load

◆ g_ra8_ls_cpu1_data_start

◆ g_ra8_ls_cpu1_stack_top

◆ s_attrs

◆ s_book

◆ s_chapters

◆ s_css

◆ s_image_pool

◆ s_image_raw

◆ s_images

◆ s_nodes

◆ s_string_pool

◆ s_styles

◆ s_xhtml

◆ s_xml_workspace