ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
compile_on_m33.h File Reference

Shared-SRAM contract for the "RABOOK1 emitter on the M33" demo (#149b). More...

#include <stdint.h>
#include "ra8_board_ek_ra8d2_dualcore.h"
Include dependency graph for compile_on_m33.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  com33_mailbox_t
 Cross-core handoff block backed by a fixed shared-SRAM address. More...

Enumerations

enum  com33_addr_t : uintptr_t {
  k_com33_epub_offset = 0x100U ,
  k_com33_blob_offset = 0x8100U ,
  k_com33_mailbox_addr = (uintptr_t)k_ra8_board_shared_ram_base ,
  k_com33_epub_addr = (uintptr_t)k_ra8_board_shared_ram_base + (uintptr_t)k_com33_epub_offset ,
  k_com33_blob_addr = (uintptr_t)k_ra8_board_shared_ram_base + (uintptr_t)k_com33_blob_offset
}
 Fixed shared-SRAM addresses for the mailbox and the output blob. More...
enum  com33_const_t : uint32_t {
  k_com33_magic = 0x434F4D33U ,
  k_com33_req_magic = 0x52455130U ,
  k_com33_m33_sig = 0x4D33C0DEU ,
  k_com33_status_running = 0U ,
  k_com33_status_ok = 1U ,
  k_com33_status_build_fail = 2U ,
  k_com33_status_open_fail = 3U ,
  k_com33_status_no_request = 4U ,
  k_com33_status_fault = 5U
}
 Magics, the boot signature, and the build-status codes shared by both core images. More...
enum  com33_blob_cap_t : uint32_t {
  k_com33_epub_cap = 0x8000U ,
  k_com33_blob_cap = 8192U
}
 Capacities, in bytes, of the shared staged-input and output buffers. More...

Functions

static volatile com33_mailbox_t * com33_mailbox (void)
 Typed pointer to the fixed-address shared mailbox.
static uint8_t * com33_blob (void)
 Typed pointer to the fixed-address shared output-blob buffer.
static uint8_t * com33_epub (void)
 Typed pointer to the fixed-address shared staged-input .epub buffer.

Detailed Description

Shared-SRAM contract for the "RABOOK1 emitter on the M33" demo (#149b).

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

This header pins the cross-core JOB mailbox and the shared input/output buffers for the #149 compiler offload: running the full text/CSS/SVG EPUB->.rabook compile (apps/shared_libs/rabook_compile + epub) on the RA8D2's Cortex-M33 secondary core. The Cortex-M85 (primary, "CPU0") STAGES a source .epub into shared SRAM, posts the job, releases the M33, then PARKS while the slow core compiles the staged book and lays a complete RABOOK1 blob into the shared output buffer. The M85 then validates that blob with book_validate AND byte-compares it to the desktop/M85 golden – proving the secondary core produced the identical compiled book the primary core would have.

Why a fixed address: 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.

Memory budget (all in the shared upper SRAM window, see the address enum):

  • mailbox : the com33_mailbox_t request/response block at 0x22100000.
  • staged .epub : k_com33_epub_cap bytes at k_com33_epub_addr; the M85 copies the source .epub here and the M33 epub_opens it.
  • output blob : k_com33_blob_cap bytes at k_com33_blob_addr; the M33 writes the finalized RABOOK1 blob here so the M85 reads it with no copy.
  • compile arenas: the M33's epub_book_t + builder pools + scratch are NOT shared – they live in the M33 image's external SDRAM (.sdram_bss); only the staged .epub + the blob are shared.

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 compile job handoff):

  1. M85 zeros the response, stamps k_com33_magic, stages the .epub into shared SRAM, fills the request (epub base/len, out base/cap), and stamps k_com33_req_magic LAST behind a dsb.
  2. M85 releases the M33 and PARKS. The M33 now compiles.
  3. M33 stamps k_com33_m33_sig, reads the request, epub_opens the staged bytes, runs rabook_compile_from_epub_to_buffer into the shared output buffer, then publishes blob_base / blob_len / blob_crc (the blob header's body CRC-32) / chapter_count.
  4. M33 sets status = ok then done = 1 (or a failure status, then done).
  5. M85 validates the shared blob, byte-compares it to the golden, and logs "compile_on_m33 PASS" (or traps so ra8_emulator's smoke flags a divergence).
Note
The M33 image links miniz + bounded XML reader + epub + the rabook pipeline but NOT stb_image (raster is compiled out via RA8_RABOOK_NO_RASTER; the SVG path stores verbatim) and NOT ra8_fs (the M85 owns the filesystem; the M33 finalizes into the shared buffer).
Copyright
Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT
Since
0.1.0

Definition in file compile_on_m33.h.

Enumeration Type Documentation

◆ com33_addr_t

enum com33_addr_t : uintptr_t

Fixed shared-SRAM addresses for the mailbox and the output blob.

All three slices are carved from the CPU0 <-> CPU1 window at fixed offsets: the mailbox occupies the first 32 bytes, the staged input starts 256 bytes in so the mailbox keeps its own cache line and some growth room, and the output blob follows 32 KiB after that. 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
k_com33_blob_addr + k_com33_blob_cap stays below k_ra8_board_cpu1_sram_base – the top of the shared window.
See also
ra8_board_dualcore_addr_t
com33_mailbox()
com33_blob()
Since
0.1.0
Enumerator
k_com33_epub_offset 

Staged input offset: past the mailbox's own cache line.

k_com33_blob_offset 

Output blob offset: past the 32 KiB staged input.

k_com33_mailbox_addr 

Mailbox base – the start of the board's shared window.

k_com33_epub_addr 

Staged input base, carved from the shared window.

k_com33_blob_addr 

Output blob base, carved from the shared window.

Definition at line 91 of file compile_on_m33.h.

◆ com33_blob_cap_t

enum com33_blob_cap_t : uint32_t

Capacities, in bytes, of the shared staged-input and output buffers.

The M85 stages the source .epub into k_com33_epub_addr (up to k_com33_epub_cap bytes) before posting the job; the M33 lays the finalized RABOOK1 blob into k_com33_blob_addr (the buffer's out_cap = k_com33_blob_cap). 32 KiB of input dwarfs the parity fixture .epub (~1 KiB) and 8 KiB of output dwarfs its blob (~700 B), so neither buffer overflows for this demo.

Since
0.1.0
Enumerator
k_com33_epub_cap 

Shared staged-input .epub buffer capacity (32 KiB).

k_com33_blob_cap 

Shared output-blob buffer capacity in bytes.

Definition at line 141 of file compile_on_m33.h.

◆ com33_const_t

enum com33_const_t : uint32_t

Magics, the boot signature, and the build-status codes shared by both core images.

k_com33_magic ("COM3") lets the M33 confirm the mailbox is live before trusting it; k_com33_m33_sig is the boot sentinel the M33 stamps so the M85 can prove the second core left reset and is executing user code. The status codes report the outcome of the emitter run the M33 performed.

See also
com33_mailbox_t
Since
0.1.0
Enumerator
k_com33_magic 

"COM3" – M85 stamps it when ready.

k_com33_req_magic 

"REQ0" – M85 stamps it once the job (the

staged .epub + buffers) is ready to run.

k_com33_m33_sig 

"M33 CODE" boot sentinel written by M33.

k_com33_status_running 

status: M33 is still building the blob.

k_com33_status_ok 

status: compile finalized a valid blob.

k_com33_status_build_fail 

status: a compile stage overflowed/failed.

k_com33_status_open_fail 

status: epub_open rejected the input.

k_com33_status_no_request 

status: req_magic absent (no staged job).

k_com33_status_fault 

status: M33 took a hardware fault mid-run.

Definition at line 117 of file compile_on_m33.h.

Function Documentation

◆ com33_blob()

uint8_t * com33_blob ( void )
inlinestatic

Typed pointer to the fixed-address shared output-blob buffer.

The emitter's out arena and the M85's validation target are the same physical SRAM bytes at k_com33_blob_addr; this inline returns that base identically on both images so no shared translation unit is needed.

Returns
Pointer to the blob buffer at k_com33_blob_addr.
Return values
non-NULLAlways; the address is a compile-time constant.
Precondition
Both linker scripts leave the k_com33_blob_cap bytes from k_com33_blob_addr unallocated.
The M85 data cache is disabled (see file header).
Postcondition
Returns a valid pointer; never NULL.
No side effects.
Note
Callable from either core; the pointer arithmetic is identical.
Since
0.1.0

Definition at line 233 of file compile_on_m33.h.

References k_com33_blob_addr.

Referenced by bind_compile().

◆ com33_epub()

uint8_t * com33_epub ( void )
inlinestatic

Typed pointer to the fixed-address shared staged-input .epub buffer.

The M85 copies the source .epub bytes here before posting the job; the M33 reads them via epub_mem_media_t at the same physical SRAM base, so no shared translation unit is needed.

Returns
Pointer to the staged-input buffer at k_com33_epub_addr.
Return values
non-NULLAlways; the address is a compile-time constant.
Precondition
Both linker scripts leave the k_com33_epub_cap bytes from k_com33_epub_addr unallocated.
The M85 data cache is disabled (see file header).
Postcondition
Returns a valid pointer; never NULL.
No side effects.
Note
Callable from either core; the pointer arithmetic is identical.
Since
0.1.0

Definition at line 257 of file compile_on_m33.h.

References k_com33_epub_addr.

Referenced by prep_mailbox().

◆ com33_mailbox()

volatile com33_mailbox_t * com33_mailbox ( void )
inlinestatic

Typed pointer to the fixed-address shared 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_com33_mailbox_addr.
Return values
non-NULLAlways; 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 209 of file compile_on_m33.h.

References k_com33_mailbox_addr.

Referenced by compile_fixture(), cpu1_fault_handler(), cpu1_run_compile(), and main().