book.h File Reference

Flat, execute-in-place container for a build-time "compiled" e-book. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for book.h:

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

Go to the source code of this file.

Data Structures
struct	book_header_t
	Fixed 100-byte prologue describing every table and pool in the blob. More...
struct	book_chapter_t
	One spine document (a renderable chapter) plus its TOC label. More...
struct	book_node_t
	One DOM node. More...
struct	book_attr_t
	One name="value" attribute on an element. More...
struct	book_stylesheet_t
	A preserved CSS stylesheet and the chapter it scopes to. More...
struct	book_image_t
	Descriptor for one transcoded image in the image pool. More...

Typedefs
typedef ra8_err_t(*	book_inflate_fn) (const void *src, size_t src_len, void *dst, size_t dst_cap, size_t *out_len)
	Caller-supplied DEFLATE inflater used by book_open().

Enumerations
enum	book_version_t : uint32_t { k_book_format_version = 1U }
	Wire-format version stamped into every blob header. More...
enum	book_container_t : uint8_t {   k_book_container_magic_len = 4U ,   k_book_container_header_len = 24U ,   k_book_container_entry_len = 8U }
	Constants of the on-disk .rabook chunked compression container. More...
enum	book_sentinel_t : uint32_t { k_book_nil = 0xFFFFFFFFU }
	Reserved index value meaning "no such element". More...
enum	book_flag_t : uint32_t {   k_book_flag_rtl = 0x00000001U ,   k_book_flag_mask_known = 0x00000001U }
	Feature-flag bits carried in book_header_t.flags. More...
enum	book_node_kind_t : uint8_t {   k_book_node_element = 0U ,   k_book_node_text = 1U }
	Discriminates the two kinds of DOM node. More...
enum	book_image_format_t : uint8_t {   k_book_image_gray4 = 0U ,   k_book_image_svg = 1U }
	Pixel encoding of an entry in the image pool. More...
enum	book_image_pixfmt_t : uint8_t {   k_book_pixfmt_gray4 = 0U ,   k_book_pixfmt_gray8 = 1U }
	Pixel depth of a k_book_image_gray4 raster in the image pool. More...
enum	book_struct_size_t : uint16_t {   k_book_sizeof_header = 100U ,   k_book_sizeof_chapter = 12U ,   k_book_sizeof_node = 24U ,   k_book_sizeof_attr = 8U ,   k_book_sizeof_stylesheet = 8U ,   k_book_sizeof_image = 24U }
	Pinned on-disk sizes of the blob's fixed-layout records. More...

Functions
static const book_header_t *	book_header (const void *base)
	View the blob base as its header.
static bool	book_is_rtl (const void *base)
	Whether the book declares right-to-left reading order (manga).
static const void *	book_at (const void *base, uint32_t off)
	Resolve a blob-relative byte offset to a pointer.
static const char *	book_string (const void *base, uint32_t off)
	Resolve a string-pool offset to a NUL-terminated UTF-8 string.
static const book_chapter_t *	book_chapters (const void *base)
	Base of the chapter table.
static const book_node_t *	book_nodes (const void *base)
	Base of the DOM node table.
static const book_attr_t *	book_attrs (const void *base)
	Base of the attribute table.
static const book_stylesheet_t *	book_stylesheets (const void *base)
	Base of the stylesheet table.
static const book_image_t *	book_images (const void *base)
	Base of the image table.
static const char *	book_node_name (const void *base, const book_node_t *node)
	Tag name of an element node.
static const char *	book_node_text (const void *base, const book_node_t *node)
	Text of a text node.
static const uint8_t *	book_image_data (const void *base, const book_image_t *img)
	Image-pool pointer to one image's compressed pixel data.
static book_image_pixfmt_t	book_image_pixfmt (const book_image_t *img)
	Declared pixel depth of one image descriptor.
ra8_err_t	book_validate (const void *base, size_t size)
	Validate that a byte buffer is a well-formed, intact .rabook blob.
ra8_err_t	book_open (const void *file, size_t file_len, book_inflate_fn inflate, void *scratch, size_t scratch_cap, const void **out_base, size_t *out_size)
	Open a .rabook file: check the container, inflate, validate the blob.
ra8_err_t	book_chapter_to_xhtml (const void *base, uint32_t chapter_idx, char *out, size_t cap, size_t *out_len)
	Serialize one chapter's DOM subtree back to XHTML for the renderer.
ra8_err_t	book_chapter_text (const void *base, uint32_t chapter_idx, char *out, size_t cap, size_t *out_len)
	Extract one chapter's readable plain text from the DOM.

Detailed Description

Flat, execute-in-place container for a build-time "compiled" e-book.

book is the on-device representation of a book that has already been unzipped, XML-parsed and image-transcoded on the host by tools/epub_compile. The firmware never unzips or parses XHTML at runtime. A .rabook file is a chunked container – the magic "RBKC", a fixed header naming the chunk size / inflated total / chunk count, a flat chunk table, then one independent zlib stream per fixed-size slice of the flat blob – so it stays compact on flash / SD and stays seekable: any chunk can be inflated alone, without touching the rest of the file. book_open() inflates every chunk once into a caller-provided SDRAM scratch buffer (the resident fast path); book_chunked.h instead inflates single chunks on demand into ra8_vmem cache frames so a book far larger than RAM is read with a bounded working set. Either way the firmware then points a const book_header_t* at inflated bytes and walks them with the inline accessors below. Every internal reference is a byte offset relative to the blob base, so the inflated structure is position-independent and walked with no further parsing or copying.

Fidelity

The format is a faithful pre-parsed DOM, NOT a lossy subset chosen to match what the renderer understands today. Every element keeps its real tag name and full attribute list; every stylesheet is preserved verbatim. A tag the renderer cannot lay out yet is still present in the blob intact – the fix for unsupported markup is to grow the renderer, never to strip the content. The only content that changes form is raster images, which are transcoded to grayscale at their source resolution – no downscale by default, so zoomable content (manga pages) keeps every pixel; a long-edge clamp exists only as an opt-in compile knob. The depth is the pixel_format axis: 4bpp panel-native (a hardware limit, not a renderer one) for never-zoomed content, or full-resolution continuous-tone 8bpp kept verbatim for zoomable content (#476), since the zoom loupe and the e-ink dither need the 256-level tones the 4bpp quantise discards. See RBKC – The Chunked .rabook Container section 3.5.

String interning

All strings (tag names, attribute names and values, text runs, hrefs, metadata) live in a single string pool and are de-duplicated by the compiler. Identical tag names therefore resolve to the same offset, so a renderer can intern-compare tags by offset instead of strcmp.

Layout

[ book_header_t                       ] fixed 100-byte header
[ book_chapter_t   * chapter_count    ] spine / table of contents
[ book_node_t      * node_count       ] DOM nodes (elements + text)
[ book_attr_t      * attr_count       ] element attributes
[ book_stylesheet_t * stylesheet_count] preserved CSS references
[ book_image_t     * image_count      ] image descriptors
[ string pool         : string_size      ] NUL-terminated UTF-8, deduped
[ image pool          : image_pool_size  ] raw 4bpp grayscale / SVG bytes

Note

The inline accessors are pure and do no bounds checking; validate a blob with book_validate() (or open it with book_open()) before walking it. The blob is immutable; nothing here writes to it.

See also

RBKC – The Chunked .rabook Container – the full RBKC wire-format specification (rationale, algorithms, worked example, failure modes).

tools/epub_compile Host compiler that emits .rabook blobs.

reflow.h Renderer that consumes the walked DOM.

Copyright

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

Since

Version 0.1.0

Definition in file book.h.

Typedef Documentation

book_inflate_fn

typedef ra8_err_t( * book_inflate_fn) (const void *src, size_t src_len, void *dst, size_t dst_cap, size_t *out_len)

Caller-supplied DEFLATE inflater used by book_open().

Keeps book decoupled from any one decompressor: the firmware passes a miniz-backed inflater, host tests pass a zlib one.

Parameters

[in]	src	Start of the raw DEFLATE stream.
[in]	src_len	DEFLATE stream length in bytes.
[out]	dst	Destination buffer to inflate into.
[in]	dst_cap	Capacity of dst in bytes.
[out]	out_len	Receives the number of bytes written to dst.

Returns

k_ra8_ok on success, any non-zero ra8_err_t on failure.

Since

Version 0.1.0

Definition at line 655 of file book.h.

Enumeration Type Documentation

book_container_t

enum book_container_t : uint8_t

Constants of the on-disk .rabook chunked compression container.

A file is (all integers little-endian):

[0]  "RBKC" magic (4 bytes)
[4]  uint32 chunk_bytes      inflated bytes per chunk (last chunk short)
[8]  uint64 inflated_total   flat-blob length in bytes
[16] uint32 chunk_count      == ceil(inflated_total / chunk_bytes)
[20] uint32 reserved         must be 0
[24] uint64 offset[chunk_count + 1]   chunk-table: each chunk's zlib
     stream starts at payload + offset[i] and ends at payload + offset[i+1];
     offset[0] == 0 and offset[chunk_count] == payload length
[..] payload: chunk_count concatenated zlib (RFC 1950) streams

Chunk i inflates to exactly min(chunk_bytes, inflated_total - i * chunk_bytes) bytes of the flat blob described by book_header_t, so any chunk can be inflated independently – the property the ra8_vmem paged read path (book_chunked.h) relies on. Producers size chunk_bytes equal to the reader's ra8_vmem frame size so one chunk fills exactly one cache frame. book_open() inflates all chunks (resident).

Since

Version 0.1.0

Enumerator
k_book_container_magic_len	Length of the "RBKC" magic.
k_book_container_header_len	Fixed header bytes ahead of the chunk table.
k_book_container_entry_len	One chunk-table entry (uint64 LE offset).

Definition at line 113 of file book.h.

book_flag_t

enum book_flag_t : uint32_t

Feature-flag bits carried in book_header_t.flags.

Flags extend the v1 layout without a format-version bump: a bit may only change how content is presented, never where any table or pool lives. book_validate() rejects a blob whose flags sets any bit outside k_book_flag_mask_known, so an old firmware never silently mis-renders a book that depends on a semantic it does not implement. Kept in lockstep with FLAG_RTL in tools/epub_compile/src/epub_compile.py (emitted by the CBZ arm, tools/epub_compile/src/cbz_compile.py, under --rtl).

Invariant

k_book_flag_mask_known is the OR of every other enumerator.

See also

book_is_rtl()

Since

Version 0.1.0

Enumerator
k_book_flag_rtl	Right-to-left reading order (manga): spine pages advance leaf-first, and the reader mirrors its page-turn zones.
k_book_flag_mask_known	Every bit this firmware understands; a set bit outside this mask fails book_validate().

Definition at line 147 of file book.h.

book_image_format_t

enum book_image_format_t : uint8_t

Pixel encoding of an entry in the image pool.

Raster images use panel-native 4-bit grayscale; SVG keeps its vector source for on-device rasterization. An enum so future encodings can be added without a flag-day.

Since

Version 0.1.0

Enumerator
k_book_image_gray4	4bpp gray, 2px/byte; pixel (x,y) is at flat index y*width + x.
k_book_image_svg	Verbatim UTF-8 SVG source (vector; on-device rasterized).

Definition at line 174 of file book.h.

book_image_pixfmt_t

enum book_image_pixfmt_t : uint8_t

Pixel depth of a k_book_image_gray4 raster in the image pool.

A second axis, orthogonal to book_image_format_t: that field only says whether an entry is a packed-grayscale raster or verbatim SVG, while this one – modelled on JOF's bpp header field – records how DEEP that raster is. A grayscale e-reader can then rasterize at 4bpp (half the storage, and exactly right for an even 16-level e-ink panel) while a device with more headroom carries the lossless 8bpp source; the compiler picks the depth by device profile instead of baking 4bpp in for every reader.

It lives in the descriptor's former padding byte (book_image_t::pixel_format), so it costs no format growth and needs no book_version_t bump: every .rabook written before this field existed zero-filled that byte, and 0 is k_book_pixfmt_gray4 – exactly the 4bpp packing those blobs already carried. New firmware therefore reads every pre-existing blob unchanged (backward-read); an unknown depth is rejected by book_validate() rather than silently mis-rendered.

Invariant

An k_book_image_svg entry stores 0 here (the field is meaningful only for a raster; callers branch on format first).

const book_image_t* img = &book_images(base)[i];
if (img->format == k_book_image_gray4 &&
    book_image_pixfmt(img) == k_book_pixfmt_gray8) {
  ra8_gfx_blit_gray8(book_image_data(base, img), img->width, img->height, x, y);
}

See also

book_image_pixfmt()

book_image_t

Since

Version 0.1.0

Enumerator
k_book_pixfmt_gray4	4bpp packed grayscale, 2px/byte (default; every pre-field blob).
k_book_pixfmt_gray8	8bpp grayscale, 1px/byte (lossless against any grey panel).

Definition at line 212 of file book.h.

book_node_kind_t

enum book_node_kind_t : uint8_t

Discriminates the two kinds of DOM node.

Since

Version 0.1.0

Enumerator
k_book_node_element	An element: has a tag name and attributes.
k_book_node_text	A text run: carries a string, no children.

Definition at line 161 of file book.h.

book_sentinel_t

enum book_sentinel_t : uint32_t

Reserved index value meaning "no such element".

Used for first_attr, first_child, next_sibling, cover_image_index and a stylesheet's scope_chapter to mean "none" / "applies to all", since a real index can never be 0xFFFFFFFF (the table count is bounded far below that).

Since

Version 0.1.0

Enumerator
k_book_nil	Absent index / "applies to all chapters".

Definition at line 128 of file book.h.

book_struct_size_t

enum book_struct_size_t : uint16_t

Pinned on-disk sizes of the blob's fixed-layout records.

The format is a binary wire layout shared with the host compiler, so each record's byte size is part of the contract. These named constants drive the static_asserts that guard against accidental padding or a silent field change.

Since

Version 0.1.0

Enumerator
k_book_sizeof_header	Bytes in book_header_t.
k_book_sizeof_chapter	Bytes in book_chapter_t.
k_book_sizeof_node	Bytes in book_node_t.
k_book_sizeof_attr	Bytes in book_attr_t.
k_book_sizeof_stylesheet	Bytes in book_stylesheet_t.
k_book_sizeof_image	Bytes in book_image_t.

Definition at line 227 of file book.h.

book_version_t

enum book_version_t : uint32_t

Wire-format version stamped into every blob header.

Bumped on any incompatible change to the on-disk layout. The loader rejects a blob whose format_version it does not recognise.

Since

Version 0.1.0

Enumerator
k_book_format_version	Current .rabook layout revision.

Definition at line 85 of file book.h.

Function Documentation

book_at()

const void * book_at ( const void * base, uint32_t off )

inlinestatic

Resolve a blob-relative byte offset to a pointer.

Parameters

[in]	base	Blob base (non-NULL).
[in]	off	Byte offset within the blob (validated < total_size).

Returns

base + off.

Precondition

base non-NULL and validated.

off lies inside the blob.

Postcondition

Result points within [base, base + total_size).

Note

Thread-safe: pure pointer arithmetic.

Since

Version 0.1.0

Definition at line 427 of file book.h.

Referenced by book_attrs(), book_chapters(), book_image_data(), book_images(), book_nodes(), book_string(), and book_stylesheets().

book_attrs()

const book_attr_t * book_attrs ( const void * base )

inlinestatic

Base of the attribute table.

Parameters

[in]

base

Blob base (non-NULL, validated).

Returns

Pointer to attr[0]; a node's first_attr indexes here.

Precondition

base validated.

book_header(base)->attr_count > 0.

Postcondition

Result indexes a contiguous array of attr_count entries.

Note

Thread-safe: read-only.

Since

Version 0.1.0

Definition at line 488 of file book.h.

References book_at(), and book_header().

Referenced by internal_emit_attrs().

book_chapter_text()

ra8_err_t book_chapter_text	(	const void *	base,
		uint32_t	chapter_idx,
		char *	out,
		size_t	cap,
		size_t *	out_len )

Extract one chapter's readable plain text from the DOM.

Walks the chapter's element/text tree iteratively (no recursion, bounded stack) and writes its text runs into out, inserting a newline at each block-level element so paragraphs stay separated. Markup, attributes and inline structure are dropped – this is for a simple word-wrap reader, not rich layout. The output is NOT NUL-terminated.

Parameters

[in]	base	Validated book blob base (non-NULL).
[in]	chapter_idx	Spine chapter index (< header chapter_count).
[out]	out	Destination text buffer (non-NULL).
[in]	cap	Capacity of out in bytes.
[out]	out_len	Receives the text byte length written.

Returns

Error code.

Return values

k_ra8_ok	Chapter text extracted.
k_ra8_err_null_ptr	A required pointer argument is NULL.
k_ra8_err_invalid_arg	chapter_idx is out of range.
k_ra8_err_invalid_size	Output did not fit cap, or DOM nesting exceeded the bounded walk stack.

Precondition

base was accepted by book_validate() / book_open().

chapter_idx is less than book_header(base)->chapter_count.

Postcondition

On k_ra8_ok, out[0..*out_len) contains the plain-text run (not NUL-terminated).

On error, out contents are unspecified.

Note

Thread-safe: reads only the immutable blob, writes only out.

Since

Version 0.1.0

Definition at line 683 of file book_xhtml.c.

References book_chapters(), book_header(), book_header_t::chapter_count, internal_walk_text(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, book_header_t::node_count, RA8_CHECK_NULL_PTR, book_chapter_t::root_node, and s_tag_xhtml.

Referenced by book_chapter_text_src(), and imp_walk_book().

book_chapter_to_xhtml()

ra8_err_t book_chapter_to_xhtml	(	const void *	base,
		uint32_t	chapter_idx,
		char *	out,
		size_t	cap,
		size_t *	out_len )

Serialize one chapter's DOM subtree back to XHTML for the renderer.

A bridge for feeding a compiled book into reflow_layout_chapter(), which consumes XHTML. Walks the chapter's element/text tree iteratively (no recursion, bounded stack) and writes well-formed XHTML – every tag, attribute and text run, faithfully – into out. Void elements self-close; text and attribute values are entity-escaped. The output is NOT NUL-terminated.

Parameters

[in]	base	Validated book blob base (non-NULL).
[in]	chapter_idx	Spine chapter index (< header chapter_count).
[out]	out	Destination XHTML buffer (non-NULL).
[in]	cap	Capacity of out in bytes.
[out]	out_len	Receives the XHTML byte length written.

Returns

Error code.

Return values

k_ra8_ok	Chapter serialized; out_len bytes written.
k_ra8_err_null_ptr	A required pointer argument is NULL.
k_ra8_err_invalid_arg	chapter_idx is out of range.
k_ra8_err_invalid_size	Output did not fit cap, or DOM nesting exceeded the bounded walk stack.

Precondition

base was accepted by book_validate() / book_open().

cap is large enough for the chapter's serialized XHTML.

Postcondition

On k_ra8_ok, out[0..*out_len) is well-formed (not NUL-terminated).

On error, out contents are unspecified.

Note

Thread-safe: reads only the immutable blob, writes only out.

See also

reflow_layout_chapter()

Since

Version 0.1.0

Definition at line 702 of file book_xhtml.c.

References book_chapters(), book_header(), book_header_t::chapter_count, internal_walk_to_xhtml(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, book_header_t::node_count, RA8_CHECK_NULL_PTR, book_chapter_t::root_node, and s_tag_xhtml.

Referenced by erb_render_chapter().

book_chapters()

const book_chapter_t * book_chapters ( const void * base )

inlinestatic

Base of the chapter table.

Parameters

[in]

base

Blob base (non-NULL, validated).

Returns

Pointer to chapter[0]; read book_header(base)->chapter_count entries.

Precondition

base validated.

book_header(base)->chapter_count > 0 for the result to be dereferenceable.

Postcondition

Result indexes a contiguous array of chapter_count entries.

Note

Thread-safe: read-only.

Since

Version 0.1.0

Definition at line 458 of file book.h.

References book_at(), and book_header().

Referenced by book_chapter_text(), book_chapter_to_xhtml(), and render_held_page().

book_header()

const book_header_t * book_header ( const void * base )

inlinestatic

View the blob base as its header.

Parameters

[in]

base

Pointer to the first byte of a .rabook blob (non-NULL).

Returns

The header view.

Precondition

base points at a blob already accepted by book_validate().

base is at least alignof(uint32_t)-aligned.

Postcondition

Returned pointer aliases base; never NULL when base is non-NULL.

Note

Thread-safe: read-only over immutable data.

Since

Version 0.1.0

Definition at line 382 of file book.h.

Referenced by book_attrs(), book_chapter_text(), book_chapter_to_xhtml(), book_chapters(), book_image_data(), book_images(), book_is_rtl(), book_is_valid(), book_nodes(), book_string(), book_stylesheets(), erb_render_image(), imp_walk_book(), internal_check_compiled_page_count(), main(), publish_result(), render_held_page(), and verify_blob().

book_image_data()

const uint8_t * book_image_data ( const void * base, const book_image_t * img )

inlinestatic

Image-pool pointer to one image's compressed pixel data.

Parameters

[in]	base	Blob base (non-NULL, validated).
[in]	img	Image descriptor (non-NULL).

Returns

Pointer to img->data_size DEFLATE bytes.

Precondition

img belongs to base.

base validated.

Postcondition

Result points within the image pool.

Note

Thread-safe: read-only.

Since

Version 0.1.0

Definition at line 566 of file book.h.

References book_at(), book_header(), and book_image_t::data_off.

Referenced by erb_render_image().

book_image_pixfmt()

book_image_pixfmt_t book_image_pixfmt ( const book_image_t * img )

inlinestatic

Declared pixel depth of one image descriptor.

Decodes book_image_t::pixel_format into its book_image_pixfmt_t. Meaningful only for a k_book_image_gray4 raster (4bpp vs 8bpp packing); an SVG entry stores 0 and reports k_book_pixfmt_gray4, so a renderer must branch on book_image_t::format first and only consult this for a raster. Every blob written before the field existed zero-filled the byte, so an old gray4 blob reports k_book_pixfmt_gray4 unchanged (backward-read).

Parameters

[in]

img

Image descriptor (non-NULL) obtained from book_images().

Returns

The declared pixel depth.

Return values

k_book_pixfmt_gray4	4bpp packed grayscale (2px/byte); also every pre-field blob and every SVG entry.
k_book_pixfmt_gray8	8bpp grayscale (1px/byte).

Precondition

img belongs to a blob accepted by book_validate().

img is non-NULL.

Postcondition

The blob is not modified (pure read).

The result is a depth book_validate() already accepted as known.

Note

Thread-safe: read-only over immutable data.

See also

book_image_pixfmt_t

book_image_data()

Since

Version 0.1.0

Definition at line 599 of file book.h.

References book_image_t::pixel_format.

Referenced by book_src_image_rect(), and erb_render_image().

book_images()

const book_image_t * book_images ( const void * base )

inlinestatic

Base of the image table.

Parameters

[in]

base

Blob base (non-NULL, validated).

Returns

Pointer to image[0]; cover_image_index indexes here.

Precondition

base validated.

book_header(base)->image_count > 0.

Postcondition

Result indexes a contiguous array of image_count entries.

Note

Thread-safe: read-only.

Since

Version 0.1.0

Definition at line 518 of file book.h.

References book_at(), and book_header().

Referenced by erb_render_image(), and internal_image_pixfmts_known().

book_is_rtl()

bool book_is_rtl ( const void * base )

inlinestatic

Whether the book declares right-to-left reading order (manga).

Reads k_book_flag_rtl out of the header's flags word. An RTL book's spine is still stored first-page-first; the flag tells the reader to mirror its presentation (page-turn zones, spread direction). Consuming the flag in the page-turn UI is the reader's job; this accessor only decodes it.

Parameters

[in]

base

Pointer to the first byte of a .rabook blob (non-NULL).

Returns

Whether the RTL flag bit is set.

Return values

true	The book reads right-to-left.
false	The book reads left-to-right (every v1 blob before the flag).

Precondition

base points at a blob already accepted by book_validate().

base is at least alignof(uint32_t)-aligned.

Postcondition

The blob is not modified (pure read).

The result is stable for the lifetime of the immutable blob.

Note

Thread-safe: read-only over immutable data.

See also

book_flag_t

Since

Version 0.1.0

Definition at line 411 of file book.h.

References book_header(), and k_book_flag_rtl.

book_node_name()

const char * book_node_name ( const void * base, const book_node_t * node )

inlinestatic

Tag name of an element node.

Parameters

[in]	base	Blob base (non-NULL, validated).
[in]	node	Element node (non-NULL, kind == k_book_node_element).

Returns

The interned, NUL-terminated tag name.

Precondition

node belongs to base and is an element.

base validated.

Postcondition

Result is a string inside the blob.

Note

Thread-safe: read-only.

Since

Version 0.1.0

Definition at line 534 of file book.h.

References book_string(), and book_node_t::name_off.

book_node_text()

const char * book_node_text ( const void * base, const book_node_t * node )

inlinestatic

Text of a text node.

Parameters

[in]	base	Blob base (non-NULL, validated).
[in]	node	Text node (non-NULL, kind == k_book_node_text).

Returns

The NUL-terminated UTF-8 run.

Precondition

node belongs to base and is a text node.

base validated.

Postcondition

Result is a string inside the blob.

Note

Thread-safe: read-only.

Since

Version 0.1.0

Definition at line 550 of file book.h.

References book_string(), and book_node_t::text_off.

Referenced by collect_chapter_text().

book_nodes()

const book_node_t * book_nodes ( const void * base )

inlinestatic

Base of the DOM node table.

Parameters

[in]

base

Blob base (non-NULL, validated).

Returns

Pointer to node[0]; indices first_child/next_sibling/root_node index here.

Precondition

base validated.

book_header(base)->node_count > 0.

Postcondition

Result indexes a contiguous array of node_count entries.

Note

Thread-safe: read-only.

Since

Version 0.1.0

Definition at line 473 of file book.h.

References book_at(), and book_header().

Referenced by collect_chapter_text(), internal_walk_text(), and internal_walk_to_xhtml().

book_open()

ra8_err_t book_open	(	const void *	file,
		size_t	file_len,
		book_inflate_fn	inflate,
		void *	scratch,
		size_t	scratch_cap,
		const void **	out_base,
		size_t *	out_size )

Open a .rabook file: check the container, inflate, validate the blob.

Parses the "RBKC" container header and chunk table (see book_container_t for the layout), inflates every chunk's zlib stream in order into the caller-owned scratch buffer (expected to live in SDRAM), then runs book_validate() over the reassembled flat blob. On success *out_base is the validated blob base (equal to scratch) ready for the inline accessors. This is the resident open – the whole inflated blob must fit scratch_cap; a book larger than the resident budget is instead read chunk-by-chunk through book_chunked.h + book_src_paged().

Parameters

[in]	file	Pointer to the .rabook file bytes (non-NULL).
[in]	file_len	Length of file in bytes.
[in]	inflate	Decompressor callback (see book_inflate_fn).
[out]	scratch	Buffer that receives the inflated blob (non-NULL).
[in]	scratch_cap	Capacity of scratch; must be >= the inflated total.
[out]	out_base	Receives the validated blob base on success.
[out]	out_size	Receives the inflated blob length on success.

Returns

Error code.

Return values

k_ra8_ok	Container valid, inflated, and blob validated.
k_ra8_err_null_ptr	A required pointer argument is NULL.
k_ra8_err_invalid_arg	Container magic / header geometry / chunk table is malformed (bad magic, zero chunk size, count disagreeing with the total, non-monotonic table, table end disagreeing with the payload length).
k_ra8_err_invalid_size	File too short, scratch_cap too small, or a chunk inflated to a length other than its span.
k_ra8_err_range_check_failed	Blob CRC mismatch (from book_validate()).

Precondition

file_len is the true readable length at file.

scratch is alignof(uint32_t)-aligned.

Postcondition

On k_ra8_ok, *out_base == scratch and accessors stay within it.

On any error, scratch contents are unspecified and must not be walked.

Note

Thread-safe if inflate is and scratch is not shared concurrently.

See also

book_validate()

Since

Version 0.1.0

Definition at line 543 of file book.c.

References internal_open_body(), RA8_CHECK_NULL_PTR, and s_tag_book.

book_string()

const char * book_string ( const void * base, uint32_t off )

inlinestatic

Resolve a string-pool offset to a NUL-terminated UTF-8 string.

Parameters

[in]	base	Blob base (non-NULL, validated).
[in]	off	String-pool offset.

Returns

Pointer to the interned string.

Precondition

base validated.

off is within the string pool.

Postcondition

Result is a NUL-terminated string inside the blob.

Note

Thread-safe: read-only.

Since

Version 0.1.0

Definition at line 443 of file book.h.

References book_at(), and book_header().

Referenced by book_node_name(), book_node_text(), imp_walk_book(), internal_emit_attrs(), internal_open_element(), internal_walk_text(), and internal_walk_to_xhtml().

book_stylesheets()

const book_stylesheet_t * book_stylesheets ( const void * base )

inlinestatic

Base of the stylesheet table.

Parameters

[in]

base

Blob base (non-NULL, validated).

Returns

Pointer to stylesheet[0].

Precondition

base validated.

book_header(base)->stylesheet_count > 0.

Postcondition

Result indexes a contiguous array of stylesheet_count entries.

Note

Thread-safe: read-only.

Since

Version 0.1.0

Definition at line 503 of file book.h.

References book_at(), and book_header().

book_validate()

ra8_err_t book_validate	(	const void *	base,
		size_t	size )

Validate that a byte buffer is a well-formed, intact .rabook blob.

Checks, in order: the magic and format_version; that flags sets no bit outside k_book_flag_mask_known (a blob relying on a presentation semantic this firmware does not implement must be rejected, not mis-read); that total_size fits in size; that every table offset plus its extent and every pool lie within total_size; that every image descriptor names a book_image_pixfmt_t this build can unpack (an unknown depth is refused rather than mis-blitted); and finally the CRC-32 of the body. Must be called once before any accessor is used on base; the accessors assume a validated blob and do no bounds checking themselves (they are pure offset arithmetic for XIP).

Parameters

[in]	base	Pointer to the candidate blob (may be NULL).
[in]	size	Number of readable bytes at base.

Returns

Error code.

Return values

k_ra8_ok	Blob is well-formed and CRC matches.
k_ra8_err_null_ptr	base is NULL.
k_ra8_err_invalid_arg	Magic is wrong, the format version is unknown, flags carries an unknown feature bit, or an image declares an unknown pixel format.
k_ra8_err_invalid_size	size is too small or a table/pool runs past total_size.
k_ra8_err_range_check_failed	CRC-32 of the body does not match the header.

Precondition

size is the true readable length at base (no over-read).

base is alignof(uint32_t)-aligned when non-NULL.

Postcondition

On k_ra8_ok, every accessor on base stays within [base, base + total_size).

On any error, base must not be passed to other accessors.

Note

Thread-safe: reads only the immutable candidate buffer.

See also

book_header()

Since

Version 0.1.0

Definition at line 231 of file book.c.

References book_header_t::attr_count, book_header_t::attr_off, book_header_t::chapter_count, book_header_t::chapter_off, book_header_t::crc32_val, book_header_t::flags, book_header_t::format_version, book_header_t::image_count, book_header_t::image_off, book_header_t::image_pool_off, book_header_t::image_pool_size, internal_crc32(), internal_image_pixfmts_known(), internal_magic_ok(), internal_table_fits(), k_book_flag_mask_known, k_book_format_version, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_range_check_failed, k_ra8_ok, book_header_t::node_count, book_header_t::node_off, RA8_CHECK_NULL_PTR, s_tag_book, book_header_t::string_off, book_header_t::string_size, book_header_t::stylesheet_count, book_header_t::stylesheet_off, and book_header_t::total_size.

Referenced by erb_render_image(), imp_walk_book(), internal_compile_temp(), internal_dispatch_and_cache(), internal_open_body(), main(), and verify_blob().