rabook_import_compiler.c File Reference

Production adapter binding the import seam to the real compiler (#151). More...

#include "rabook_import_compiler.h"
#include <stddef.h>
#include <stdint.h>
#include "book.h"
#include "epub.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_rabook_pipeline.h"
#include "ra8_vmem.h"
#include "ra8_vmem_stream.h"
#include "ra8_vsource.h"

Include dependency graph for rabook_import_compiler.c:

Go to the source code of this file.

Data Structures
struct	import_stream_t
	Per-compile streaming state living in the adapter's stack frame. More...

Functions
static ra8_err_t	internal_source_read (void *ctx, uint64_t offset, uint8_t *buf, uint32_t len)
	ra8_vsource_read_fn over the open source file: seek + full read.
static ra8_err_t	internal_cache_bind (const rabook_import_compiler_ctx_t *ctx, import_stream_t *ss, uint32_t size)
	Rebuild the cookie's page cache over the open source file.
static ra8_err_t	internal_stream_open (const rabook_import_compiler_ctx_t *ctx, ra8_fs_mount_t *mount, const char *epub_path, import_stream_t *ss)
	Open the source .epub as a cache-fronted stream (no residency).
ra8_err_t	rabook_import_compile_adapter (void *compile_ctx, ra8_fs_mount_t *mount, const char *epub_path, const char *out_path)
	Import-seam adapter: stream a .epub off mount and compile it.
static ra8_err_t	internal_read_whole_file (ra8_fs_mount_t *mount, const char *path, uint8_t *buf, uint32_t cap, uint32_t *out_len)
	Read a whole file off mount into buf, closing it on every path.
static ra8_err_t	internal_dispatch_and_cache (const rabook_import_compiler_m33_ctx_t *ctx, uint32_t epub_len, ra8_fs_mount_t *mount, const char *out_path)
	Dispatch the staged compile to the secondary core, validate, cache it.
static bool	internal_is_dispatch_failure (ra8_err_t err)
	Classify an offload result: does err warrant an in-core retry?
static ra8_err_t	internal_fallback_or_propagate (const rabook_import_compiler_m33_ctx_t *ctx, ra8_err_t err, ra8_fs_mount_t *mount, const char *epub_path, const char *out_path)
	Retry a failed offload in-core, or propagate the offload error.
static ra8_err_t	internal_offload_or_fallback (const rabook_import_compiler_m33_ctx_t *ctx, uint32_t epub_len, ra8_fs_mount_t *mount, const char *epub_path, const char *out_path)
	Run the M33 offload, retrying in-core when the offload itself failed.
ra8_err_t	rabook_import_compile_adapter_m33 (void *compile_ctx, ra8_fs_mount_t *mount, const char *epub_path, const char *out_path)
	Import-seam adapter that offloads the compile to the Cortex-M33 (#149).

Variables
static const char *const	s_tag = "rabook_import_compiler"
	Log tag for this adapter.

Detailed Description

Production adapter binding the import seam to the real compiler (#151).

Connects import-manager requests to the bounded EPUB/RABOOK compiler while preserving the caller's storage and workspace lifetimes.

Since

Version 0.1.0

Copyright

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

[Ring 4 / EPUB Import] {World: NS}

Definition in file rabook_import_compiler.c.

Function Documentation

internal_cache_bind()

ra8_err_t internal_cache_bind ( const rabook_import_compiler_ctx_t * ctx, import_stream_t * ss, uint32_t size )

static

Rebuild the cookie's page cache over the open source file.

Re-initialises the single-slot registry, registers the file as a paged object of size bytes, re-initialises the cookie's ra8_vmem cache over the cookie's frame/meta/bucket arrays (a fresh, empty cache – no frame from a previous compile can be served), and binds ss->st as the byte-stream reader. The frame pool is the compile front-end's entire source-side RAM budget.

Parameters

[in]	ctx	Populated compiler cookie (cache storage fields).
[in,out]	ss	Streaming state holding the open file; receives the registry + stream binding.
[in]	size	Source file length in bytes (> 0).

Returns

Error code.

Return values

k_ra8_ok	Cache bound; ss->st is readable.
k_ra8_err_null_ptr	A cache storage pointer is NULL.
k_ra8_err_invalid_size	size is 0, or a cache dimension is 0.

Precondition

ss->file is an open read-mode handle.

The cookie's cache* fields describe caller-owned storage.

Postcondition

On k_ra8_ok the cookie's cache is empty and serves the source file.

On any non-ok return the cache/stream bindings are unusable.

Note

Not thread-safe.

Since

Version 0.1.0

Definition at line 123 of file rabook_import_compiler.c.

References rabook_import_compiler_ctx_t::cache, rabook_import_compiler_ctx_t::cache_bucket_count, rabook_import_compiler_ctx_t::cache_buckets, rabook_import_compiler_ctx_t::cache_frame_bytes, rabook_import_compiler_ctx_t::cache_frame_count, rabook_import_compiler_ctx_t::cache_frames, rabook_import_compiler_ctx_t::cache_keys, rabook_import_compiler_ctx_t::cache_meta, import_stream_t::file, internal_source_read(), k_ra8_ok, import_stream_t::obj, RA8_CHECK_NULL_PTR, ra8_vmem_init(), ra8_vmem_stream_init(), ra8_vsource_add_paged(), ra8_vsource_init(), ra8_vsource_loader(), s_tag, import_stream_t::st, and import_stream_t::vsrc.

Referenced by internal_stream_open().

internal_dispatch_and_cache()

ra8_err_t internal_dispatch_and_cache ( const rabook_import_compiler_m33_ctx_t * ctx, uint32_t epub_len, ra8_fs_mount_t * mount, const char * out_path )

static

Dispatch the staged compile to the secondary core, validate, cache it.

Calls the cookie's dispatch seam to run the compile on the M33, which emits a RABOOK1 blob (length in blob_len) into ctx->blob_buf; the blob is then run through book_validate to catch a cross-core transfer slip or worker fault before it is written to out_path with ra8_fs_write_file.

Parameters

[in]	ctx	Populated M33 cookie (dispatch + buffers).
[in]	epub_len	Source length already in ctx->epub_load_buf.
[in,out]	mount	Mounted volume the validated blob is written to.
[in]	out_path	Path to write the RABOOK1 body to (importer temp name).

Returns

Error code.

Return values

k_ra8_ok	Blob dispatched, validated, and written to out_path.
k_ra8_err_*	Propagated dispatch / validate / write error.

Precondition

ctx->dispatch and ctx->blob_buf are non-NULL.

ctx->epub_load_buf holds epub_len readable bytes.

Postcondition

On success out_path holds a book_validate-clean blob.

On any error out_path is not written.

Note

Not thread-safe.

Since

Version 0.1.0

Definition at line 324 of file rabook_import_compiler.c.

References rabook_import_compiler_m33_ctx_t::blob_buf, rabook_import_compiler_m33_ctx_t::blob_cap, book_validate(), rabook_import_compiler_m33_ctx_t::dispatch, rabook_import_compiler_m33_ctx_t::dispatch_ctx, rabook_import_compiler_m33_ctx_t::epub_load_buf, k_ra8_ok, and ra8_fs_write_file().

Referenced by internal_offload_or_fallback().

internal_fallback_or_propagate()

ra8_err_t internal_fallback_or_propagate ( const rabook_import_compiler_m33_ctx_t * ctx, ra8_err_t err, ra8_fs_mount_t * mount, const char * epub_path, const char * out_path )

static

Retry a failed offload in-core, or propagate the offload error.

The shared classify-and-retry tail of both offload stages (the source read and the dispatch): a TIMEOUT/FAULT or transport overflow (see internal_is_dispatch_failure) means the source .epub is likely fine, so the compile is retried IN-CORE via the cookie's fallback – the import still yields a valid .rabook. Other errors, and the no-fallback case, propagate err unchanged.

Parameters

[in]	ctx	Populated M33 cookie (optional fallback).
[in]	err	The non-OK offload-stage error to classify.
[in,out]	mount	Mounted volume holding the source and the output.
[in]	epub_path	Root-level path of the source .epub (for the retry).
[in]	out_path	Path to write the RABOOK1 body to (importer temp name).

Returns

Error code.

Return values

k_ra8_ok	The in-core fallback compiled and wrote the blob.
k_ra8_err_*	err propagated, or the in-core fallback's error.

Precondition

err is a non-OK offload-stage result.

ctx->fallback is NULL or a fully-populated in-core cookie.

Postcondition

On k_ra8_ok, out_path holds a book_validate-clean blob.

On any error, out_path is not written.

Note

Not thread-safe.

Since

Version 0.1.0

Definition at line 401 of file rabook_import_compiler.c.

References rabook_import_compiler_m33_ctx_t::fallback, internal_is_dispatch_failure(), ra8_log_warn, rabook_import_compile_adapter(), and s_tag.

Referenced by internal_offload_or_fallback(), and rabook_import_compile_adapter_m33().

internal_is_dispatch_failure()

bool internal_is_dispatch_failure ( ra8_err_t err )

static

Classify an offload result: does err warrant an in-core retry?

A TIMEOUT/FAULT – the worker stalled, faulted, or never finished – surfaces from the dispatch seam as k_ra8_err_hw_error; a blob too large for the cross-core transport surfaces as k_ra8_err_no_mem. Both mean the OFFLOAD failed though the source .epub may compile cleanly, so the in-core path is worth a try. A caller bug (k_ra8_err_null_ptr) or an FS slip would only recur in-core and so is not a fallback trigger; success is handled before this is reached.

Parameters

[in]

err

Non-OK error returned by internal_dispatch_and_cache.

Returns

Whether err warrants the in-core fallback.

Return values

true	err is k_ra8_err_hw_error or k_ra8_err_no_mem.
false	Any other code.

Precondition

err is a value internal_dispatch_and_cache can return.

Reached only after the offload returned non-OK.

Postcondition

No state is mutated (pure predicate).

The result depends only on err.

Note

Pure; thread-safe.

The two-condition decision below is the only compound boolean in this module; its N+1 = 3 MC/DC vectors live in tests/src/test_rabook_import_m33.c (the fallback-on-timeout / fallback-on-oom / no-fallback-on-other-error cases), which cite this function in their @par MC/DC: blocks.

Since

Version 0.1.0

Definition at line 372 of file rabook_import_compiler.c.

References k_ra8_err_hw_error, k_ra8_err_no_mem, and RA8_INTERNAL.

Referenced by internal_fallback_or_propagate().

internal_offload_or_fallback()

ra8_err_t internal_offload_or_fallback ( const rabook_import_compiler_m33_ctx_t * ctx, uint32_t epub_len, ra8_fs_mount_t * mount, const char * epub_path, const char * out_path )

static

Run the M33 offload, retrying in-core when the offload itself failed.

Dispatches to internal_dispatch_and_cache; a clean result is used as-is and any failure is classified by internal_fallback_or_propagate.

Parameters

[in]	ctx	Populated M33 cookie (dispatch + optional fallback).
[in]	epub_len	Source length already in ctx->epub_load_buf.
[in,out]	mount	Mounted volume the validated blob is written to.
[in]	epub_path	Root-level path of the source .epub (for the retry).
[in]	out_path	Path to write the RABOOK1 body to (importer temp name).

Returns

Error code.

Return values

k_ra8_ok	Blob produced (on the M33, or in-core on fallback) and written.
k_ra8_err_*	Propagated offload error, or the in-core fallback error.

Precondition

ctx is non-NULL with a non-NULL dispatch.

ctx->epub_load_buf holds epub_len readable bytes.

Postcondition

On k_ra8_ok, out_path holds a book_validate-clean blob.

On any error, out_path is not written.

Note

Not thread-safe.

Since

Version 0.1.0

Definition at line 437 of file rabook_import_compiler.c.

References internal_dispatch_and_cache(), internal_fallback_or_propagate(), and k_ra8_ok.

Referenced by rabook_import_compile_adapter_m33().

internal_read_whole_file()

ra8_err_t internal_read_whole_file ( ra8_fs_mount_t * mount, const char * path, uint8_t * buf, uint32_t cap, uint32_t * out_len )

static

Read a whole file off mount into buf, closing it on every path.

Opens path read-only, rejects a file larger than cap with k_ra8_err_no_mem (a transport overflow – the M33 offload needs the source resident in shared memory, so an oversized source must surface as a fallback trigger, not a silent truncation), pulls the bytes into buf with a single ra8_fs_read (byte count returned in *out_len), then closes the handle unconditionally. The read error is returned in preference to the close error so a partial read is not masked.

Parameters

[in]	mount	Mounted volume (non-NULL).
[in]	path	Root-level source path (non-NULL).
[out]	buf	Destination buffer (non-NULL).
[in]	cap	Capacity of buf in bytes.
[out]	out_len	Receives the number of bytes read on success.

Returns

Error code.

Return values

k_ra8_ok	The file was read; *out_len holds its length.
k_ra8_err_no_mem	The file is larger than cap (fallback trigger).
k_ra8_err_*	Propagated open / read / close error.

Precondition

buf and out_len are non-NULL.

path names an existing file on mount.

Postcondition

On success buf holds *out_len bytes and the file is closed.

On any error the file is closed if it was opened.

Note

Not thread-safe.

Since

Version 0.1.0

Definition at line 271 of file rabook_import_compiler.c.

References k_ra8_err_no_mem, k_ra8_fs_mode_read, k_ra8_ok, ra8_fs_close(), ra8_fs_open(), ra8_fs_read(), ra8_fs_size(), and RA8_INTERNAL.

Referenced by rabook_import_compile_adapter_m33().

internal_source_read()

ra8_err_t internal_source_read ( void * ctx, uint64_t offset, uint8_t * buf, uint32_t len )

static

ra8_vsource_read_fn over the open source file: seek + full read.

ra8_vsource_loader clamps every request to the registered object size, so a short read here means the file shrank or the backend faulted – reported as k_ra8_err_hw_error rather than served as silently-truncated page bytes. ra8_fs offsets are 32-bit, so an offset past 4 GiB is rejected (the object size cannot exceed the ra8_fs_size result anyway).

Parameters

[in]	ctx	The open ra8_fs_file_t* (as a void cookie).
[in]	offset	Absolute byte offset within the source file.
[out]	buf	Destination buffer (len writable bytes).
[in]	len	Bytes to read.

Returns

Error code.

Return values

k_ra8_ok	Exactly len bytes were copied to buf.
k_ra8_err_null_ptr	ctx or buf is NULL.
k_ra8_err_out_of_range	offset exceeds the 32-bit ra8_fs range.
k_ra8_err_hw_error	Short read (file shrank / backend fault).
k_ra8_err_*	Propagated seek / read error.

Precondition

ctx is a live read-mode file handle.

offset + len lies within the registered object size.

Postcondition

On k_ra8_ok exactly len bytes were written to buf.

No state outside buf and the file offset is modified.

Note

Not thread-safe.

Since

Version 0.1.0

Definition at line 76 of file rabook_import_compiler.c.

References k_ra8_err_hw_error, k_ra8_err_out_of_range, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_fs_read(), ra8_fs_seek(), and s_tag.

internal_stream_open()

ra8_err_t internal_stream_open ( const rabook_import_compiler_ctx_t * ctx, ra8_fs_mount_t * mount, const char * epub_path, import_stream_t * ss )

static

Open the source .epub as a cache-fronted stream (no residency).

Opens epub_path read-only, sizes it, binds the cookie's page cache over the open file via internal_cache_bind, and opens the book with epub_open_streamed reading through ra8_vmem_stream_read. On any failure the file is closed and ss->file is NULL; on success the file stays open (the book streams from it) until the adapter closes it after the compile.

Parameters

[in]	ctx	Populated compiler cookie.
[in,out]	mount	Mounted volume holding the source.
[in]	epub_path	Root-level path of the source .epub.
[in,out]	ss	Zeroed streaming state; receives the open file + stream bindings (must out-live the compile).

Returns

Error code.

Return values

k_ra8_ok	Book opened; ctx->epub streams through the cache.
k_ra8_err_*	Propagated open / cache-bind / streamed-open error.

Precondition

ctx->epub and the cookie's cache storage are populated.

ss is zero-initialised by the caller.

Postcondition

On k_ra8_ok ss->file is the open source and ctx->epub->in_use == 1.

On any error ss->file == NULL (the file was closed here).

Note

Not thread-safe.

Since

Version 0.1.0

Definition at line 178 of file rabook_import_compiler.c.

References rabook_import_compiler_ctx_t::epub, epub_open_streamed(), import_stream_t::file, internal_cache_bind(), k_ra8_fs_mode_read, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_fs_close(), ra8_fs_open(), ra8_fs_size(), RA8_INTERNAL, ra8_vmem_stream_read(), s_tag, ra8_vmem_stream_t::size, and import_stream_t::st.

Referenced by rabook_import_compile_adapter().

rabook_import_compile_adapter()

ra8_err_t rabook_import_compile_adapter ( void * compile_ctx, ra8_fs_mount_t * mount, const char * epub_path, const char * out_path )

nodiscard

Import-seam adapter: stream a .epub off mount and compile it.

Signature matches rabook_import_compile_fn. Opens the source file, fronts it with the cookie's bounded ra8_vmem page cache, opens the book with epub_open_streamed (no whole-file residency, #230), runs rabook_compile_from_epub to out_path, and closes the book and the source file on every path.

Parameters

[in]	compile_ctx	Pointer to a rabook_import_compiler_ctx_t.
[in,out]	mount	Mounted volume holding the source and the output.
[in]	epub_path	Root-level path of the source .epub.
[in]	out_path	Path to write the RABOOK1 body to (the importer's temp name).

Returns

Error code.

Return values

k_ra8_ok	Book compiled and written to out_path.
k_ra8_err_null_ptr	A required pointer (incl. a cookie field) is NULL.
k_ra8_err_*	Propagated open / cache-bind / compile error.

Precondition

compile_ctx points at a fully-populated cookie.

mount, epub_path, and out_path are non-NULL.

Postcondition

On k_ra8_ok, out_path holds a valid RABOOK1 blob and the book is closed.

The source file handle is closed on every return path.

Note

Not thread-safe.

Since

Version 0.1.0

Definition at line 213 of file rabook_import_compiler.c.

References rabook_import_compiler_ctx_t::bufs, rabook_import_compiler_ctx_t::epub, epub_close(), import_stream_t::file, internal_stream_open(), k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_fs_close(), rabook_compile_from_epub(), s_tag, and rabook_import_compiler_ctx_t::scr.

Referenced by imp_make_cfg(), and internal_fallback_or_propagate().

rabook_import_compile_adapter_m33()

ra8_err_t rabook_import_compile_adapter_m33 ( void * compile_ctx, ra8_fs_mount_t * mount, const char * epub_path, const char * out_path )

nodiscard

Import-seam adapter that offloads the compile to the Cortex-M33 (#149).

Signature matches rabook_import_compile_fn. Reads the source .epub off mount, dispatches the compile to the secondary core via the cookie's ra8_dual_core_compile_dispatch_fn, validates the returned blob with book_validate, then writes it to out_path (the manager renames it into the cache). The M85 owns the filesystem; the M33 only produces the blob in shared memory.

If the offload fails with a TIMEOUT/FAULT (k_ra8_err_hw_error) or a transport overflow (k_ra8_err_no_mem) and the cookie carries a rabook_import_compiler_ctx_t.fallback, the compile is retried IN-CORE so a transient secondary-core failure never fails the import. A clean offload result is used directly; other errors propagate.

Parameters

[in]	compile_ctx	Pointer to a rabook_import_compiler_m33_ctx_t.
[in,out]	mount	Mounted volume holding the source and the output.
[in]	epub_path	Root-level path of the source .epub.
[in]	out_path	Path to write the RABOOK1 body to (importer temp name).

Returns

Error code.

Return values

k_ra8_ok	Blob produced (on the M33, or in-core on fallback), validated, and written to out_path.
k_ra8_err_null_ptr	A required pointer (incl. a cookie field) is NULL.
k_ra8_err_*	Propagated read / dispatch / validate / write error (the in-core fallback error when that path is taken).

Precondition

compile_ctx points at a fully-populated cookie with a non-NULL dispatch.

mount, epub_path, and out_path are non-NULL.

Postcondition

On k_ra8_ok, out_path holds a book_validate-clean RABOOK1 blob.

On any error, out_path is not written.

Note

Not thread-safe.

See also

ra8_dual_core_compile_dispatch_fn

rabook_import_compile_adapter

Since

Version 0.1.0

Definition at line 450 of file rabook_import_compiler.c.

References rabook_import_compiler_m33_ctx_t::dispatch, rabook_import_compiler_m33_ctx_t::epub_load_buf, rabook_import_compiler_m33_ctx_t::epub_load_cap, internal_fallback_or_propagate(), internal_offload_or_fallback(), internal_read_whole_file(), k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Variable Documentation

s_tag

const char* const s_tag = "rabook_import_compiler"

static

Log tag for this adapter.

Since

Version 0.1.0

Definition at line 30 of file rabook_import_compiler.c.