ra8_rabook_finalize.c File Reference

Canonical RABOOK1 serialization and finalization. More...

#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "rabook_compile.h"

Include dependency graph for ra8_rabook_finalize.c:

Go to the source code of this file.

Data Structures
struct	ra8_rabook_layout_t
	Computed byte offsets of every table / pool plus the total blob size. More...
struct	ra8_rabook_segment_t
	One resident body segment in canonical serialization order. More...
struct	ra8_rabook_memory_sink_t
	Bounded in-memory sink used by the legacy finalizer wrapper. More...

Enumerations
enum	ra8_rabook_crc_t : uint32_t {   k_rabook_crc_init = 0xFFFFFFFFU ,   k_rabook_crc_poly = 0xEDB88320U }
	CRC-32/ISO-HDLC constants matching book_validate. More...
enum	ra8_rabook_crc_bits_t : uint32_t { k_rabook_crc_byte_bits = 8U }
	Per-byte fold count for the bitwise CRC inner loop. More...
enum	ra8_rabook_pool_mode_t : uint8_t { k_rabook_pool_external = 2U }
	Image-pool backing recorded by the builder context. More...
enum	ra8_rabook_segment_count_t : uint8_t {   k_rabook_segment_chapters = 0U ,   k_rabook_segment_nodes = 1U ,   k_rabook_segment_attrs = 2U ,   k_rabook_segment_styles = 3U ,   k_rabook_segment_images = 4U ,   k_rabook_segment_strings = 5U ,   k_rabook_segment_count = 6U }
	Number of resident body segments before the image-pool payload. More...

Functions
static uint32_t	internal_crc_update (uint32_t crc, const uint8_t *data, uint32_t len)
	Continue a CRC-32/ISO-HDLC accumulator over one byte range.
static ra8_err_t	internal_compute_layout (const ra8_rabook_ctx_t *ctx, ra8_rabook_layout_t *lay)
	Compute the table / pool offsets and total blob size, overflow-guarded.
static void	internal_segments (const ra8_rabook_ctx_t *ctx, const ra8_rabook_layout_t *lay, ra8_rabook_segment_t seg[k_rabook_segment_count])
	Populate the canonical resident body-segment sequence.
static ra8_err_t	internal_read_exact (ra8_rabook_image_read_fn read, void *read_ctx, uint32_t offset, uint8_t *dst, uint32_t len)
	Read one exact external-pool chunk, rejecting a short success.
static ra8_err_t	internal_write_exact (ra8_rabook_write_fn write, void *write_ctx, const uint8_t *src, uint32_t len)
	Append one exact stream chunk, rejecting a short success.
static ra8_err_t	internal_crc_image_pool (const ra8_rabook_ctx_t *ctx, ra8_rabook_image_read_fn read, void *read_ctx, uint8_t *scratch, uint32_t scratch_cap, uint32_t *crc)
	Fold the logical image pool into an in-progress CRC.
static book_header_t	internal_make_header (const ra8_rabook_ctx_t *ctx, const ra8_rabook_layout_t *lay, uint32_t crc)
	Fill the fixed RABOOK1 header from one layout and CRC.
static ra8_err_t	internal_write_image_pool (const ra8_rabook_ctx_t *ctx, ra8_rabook_image_read_fn read, void *read_ctx, ra8_rabook_write_fn write, void *write_ctx, uint8_t *scratch, uint32_t scratch_cap)
	Emit the logical image pool through the exact-write callback.
static ra8_err_t	internal_crc_body (const ra8_rabook_ctx_t *ctx, const ra8_rabook_segment_t seg[k_rabook_segment_count], ra8_rabook_image_read_fn read, void *read_ctx, uint8_t *scratch, uint32_t scratch_cap, uint32_t *out_crc)
	Compute the finalized CRC for all canonical body segments.
static ra8_err_t	internal_write_book (const ra8_rabook_ctx_t *ctx, const book_header_t *hdr, const ra8_rabook_segment_t seg[k_rabook_segment_count], ra8_rabook_image_read_fn read, void *read_ctx, ra8_rabook_write_fn write, void *write_ctx, uint8_t *scratch, uint32_t scratch_cap)
	Emit the fixed header followed by the canonical logical body.
static ra8_err_t	internal_validate_stream_args (const ra8_rabook_ctx_t *ctx, ra8_rabook_image_read_fn image_read, ra8_rabook_write_fn write, const uint8_t *scratch, uint32_t scratch_cap, const uint32_t *out_len)
	Validate streaming-finalizer arguments and builder state.
ra8_err_t	ra8_rabook_finalize_stream (const ra8_rabook_ctx_t *ctx, ra8_rabook_image_read_fn image_read, void *image_ctx, ra8_rabook_write_fn write, void *write_ctx, uint8_t *scratch, uint32_t scratch_cap, uint32_t *out_len)
	Stream a canonical flat RABOOK1 blob without a full output arena.
static ra8_err_t	internal_memory_write (void *opaque, const uint8_t *src, uint32_t requested, uint32_t *out_written)
	Append one chunk to a bounded memory sink.
static ra8_err_t	internal_validate_memory_finalize (ra8_rabook_ctx_t *ctx, const void **out_blob, const uint32_t *out_len)
	Validate the legacy in-memory finalizer and output capacity.
ra8_err_t	ra8_rabook_finalize (ra8_rabook_ctx_t *ctx, const void **out_blob, uint32_t *out_len)
	Lay out the tables and pools, fill the header, CRC, and emit the blob.

Variables
static const char *const	s_tag_rabook = "ra8_rabook_finalize"
	Component tag for finalizer diagnostics.

Detailed Description

Canonical RABOOK1 serialization and finalization.

Computes the wire layout over an immutable builder context, folds the body CRC-32, and publishes the header plus body through an exact-write callback. Image payloads may reside in the builder arena or behind a bounded external reader. The memory finalizer is a bounded sink adapter over the same streaming path, so both destinations produce identical bytes.

Copyright

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

Since

0.1.0

Definition in file ra8_rabook_finalize.c.

Enumeration Type Documentation

ra8_rabook_crc_bits_t

enum ra8_rabook_crc_bits_t : uint32_t

Per-byte fold count for the bitwise CRC inner loop.

Since

0.1.0

Enumerator
k_rabook_crc_byte_bits	Bit folds per input byte.

Definition at line 42 of file ra8_rabook_finalize.c.

ra8_rabook_crc_t

enum ra8_rabook_crc_t : uint32_t

CRC-32/ISO-HDLC constants matching book_validate.

Since

0.1.0

Enumerator
k_rabook_crc_init	CRC seed and final XOR mask.
k_rabook_crc_poly	Reflected CRC-32 polynomial.

Definition at line 32 of file ra8_rabook_finalize.c.

ra8_rabook_pool_mode_t

enum ra8_rabook_pool_mode_t : uint8_t

Image-pool backing recorded by the builder context.

Enumerator
k_rabook_pool_external	Bytes live behind the read callback.

Definition at line 47 of file ra8_rabook_finalize.c.

ra8_rabook_segment_count_t

enum ra8_rabook_segment_count_t : uint8_t

Number of resident body segments before the image-pool payload.

Enumerator
k_rabook_segment_chapters	Chapter table.
k_rabook_segment_nodes	DOM node table.
k_rabook_segment_attrs	DOM attribute table.
k_rabook_segment_styles	Stylesheet table.
k_rabook_segment_images	Image descriptor table.
k_rabook_segment_strings	Interned string pool.
k_rabook_segment_count	Five tables plus the string pool.

Definition at line 163 of file ra8_rabook_finalize.c.

Function Documentation

internal_compute_layout()

ra8_err_t internal_compute_layout ( const ra8_rabook_ctx_t * ctx, ra8_rabook_layout_t * lay )

static

Compute the table / pool offsets and total blob size, overflow-guarded.

Sums the fixed header, the five count*record-size tables, and the two pools in 64-bit arithmetic so no intermediate product or running offset can wrap a 32-bit value; the final total is rejected if it exceeds UINT32_MAX before being narrowed back into lay.

Parameters

[in]	ctx	Builder context with the running counts / sizes (non-NULL).
[out]	lay	Receives the contract offsets and total (non-NULL).

Returns

Error code.

Return values

k_ra8_ok	Offsets computed and stored in lay.
k_ra8_err_invalid_size	The blob would exceed 32-bit addressing.

Precondition

ctx and lay are non-NULL (caller-validated).

Each *_count / *_size reflects the bytes actually appended.

Postcondition

On k_ra8_ok, lay offsets are monotonically non-decreasing.

On error lay is left in an indeterminate state and must be ignored.

Note

Not thread-safe.

Since

0.1.0

Definition at line 123 of file ra8_rabook_finalize.c.

References ra8_rabook_ctx_t::attr_count, ra8_rabook_ctx_t::chapter_count, ra8_rabook_ctx_t::image_count, ra8_rabook_ctx_t::image_pool_size, k_book_sizeof_attr, k_book_sizeof_chapter, k_book_sizeof_header, k_book_sizeof_image, k_book_sizeof_node, k_book_sizeof_stylesheet, k_ra8_err_invalid_size, k_ra8_ok, ra8_rabook_ctx_t::node_count, ra8_log_error, s_tag_rabook, ra8_rabook_ctx_t::string_size, and ra8_rabook_ctx_t::stylesheet_count.

Referenced by internal_validate_memory_finalize(), and ra8_rabook_finalize_stream().

internal_crc_body()

ra8_err_t internal_crc_body ( const ra8_rabook_ctx_t * ctx, const ra8_rabook_segment_t seg[k_rabook_segment_count], ra8_rabook_image_read_fn read, void * read_ctx, uint8_t * scratch, uint32_t scratch_cap, uint32_t * out_crc )

static

Compute the finalized CRC for all canonical body segments.

Folds resident segments in layout order, then reads and folds the logical image pool before applying the CRC final XOR.

Parameters

[in]	ctx	Builder describing the logical body.
[in]	seg	Canonical resident segment sequence.
[in]	read	External image-pool reader, when selected.
[in,out]	read_ctx	External reader context.
[in,out]	scratch	External transfer scratch.
[in]	scratch_cap	Scratch capacity in bytes.
[out]	out_crc	Finalized body CRC.

Returns

CRC pass status.

Return values

k_ra8_ok	Every logical body byte was folded.
k_ra8_err_invalid_size	An external read was short.

Precondition

ctx, seg, and out_crc are non-NULL.

External mode supplies a reader and nonzero scratch capacity.

Postcondition

Success initializes out_crc with the RABOOK1 body CRC.

Callback failures are propagated unchanged.

Note

External reads never exceed scratch_cap.

Since

0.1.0

Definition at line 448 of file ra8_rabook_finalize.c.

References internal_crc_image_pool(), internal_crc_update(), k_ra8_ok, k_rabook_crc_init, and k_rabook_segment_count.

Referenced by ra8_rabook_finalize_stream().

internal_crc_image_pool()

ra8_err_t internal_crc_image_pool ( const ra8_rabook_ctx_t * ctx, ra8_rabook_image_read_fn read, void * read_ctx, uint8_t * scratch, uint32_t scratch_cap, uint32_t * crc )

static

Fold the logical image pool into an in-progress CRC.

Reads internal bytes directly or walks an external pool through bounded caller scratch, preserving one CRC accumulator across chunks.

Parameters

[in]	ctx	Builder describing the logical image pool.
[in]	read	External reader, when selected.
[in,out]	read_ctx	External reader context.
[in,out]	scratch	External transfer scratch.
[in]	scratch_cap	Scratch capacity in bytes.
[in,out]	crc	Running CRC accumulator.

Returns

Pool-read status.

Return values

k_ra8_ok	Every pool byte was folded exactly once.
k_ra8_err_invalid_size	An external read was short.

Precondition

ctx and crc are non-NULL.

External mode supplies a non-NULL reader and nonzero scratch capacity.

Postcondition

Success updates crc through the whole logical pool.

Failure leaves the partially updated accumulator unpublished.

Note

External reads are bounded by scratch_cap.

Since

0.1.0

Definition at line 294 of file ra8_rabook_finalize.c.

References ra8_rabook_ctx_t::buf, ra8_rabook_buffers_t::image_pool, ra8_rabook_ctx_t::image_pool_mode, ra8_rabook_ctx_t::image_pool_size, internal_crc_update(), internal_read_exact(), k_ra8_ok, and k_rabook_pool_external.

Referenced by internal_crc_body().

internal_crc_update()

uint32_t internal_crc_update ( uint32_t crc, const uint8_t * data, uint32_t len )

static

Continue a CRC-32/ISO-HDLC accumulator over one byte range.

Folds eight bits per byte with the reflected k_rabook_crc_poly. The caller seeds with k_rabook_crc_init and applies the final XOR after every segment, yielding the exact variant book_validate expects.

Parameters

[in]	crc	Incoming, not-yet-finalized CRC accumulator.
[in]	data	Byte range to checksum (may be NULL iff len is 0).
[in]	len	Number of bytes at data.

Returns

Updated, not-yet-finalized CRC accumulator.

Return values

uint32_t

Accumulator after all len bytes have been folded.

Precondition

data addresses at least len readable bytes (or len is 0).

len is the true range length (no over-read).

Postcondition

A zero-length range returns crc unchanged.

data is not modified (read-only checksum).

Note

Not thread-safe in the sense of shared state, but has none; pure.

Since

0.1.0

Definition at line 70 of file ra8_rabook_finalize.c.

References k_rabook_crc_byte_bits, and k_rabook_crc_poly.

Referenced by internal_crc_body(), and internal_crc_image_pool().

internal_make_header()

book_header_t internal_make_header ( const ra8_rabook_ctx_t * ctx, const ra8_rabook_layout_t * lay, uint32_t crc )

static

Fill the fixed RABOOK1 header from one layout and CRC.

Copies builder counts, metadata, flags, pool sizes, canonical offsets, magic, version, and finalized body CRC into the pinned wire struct.

Parameters

[in]	ctx	Builder state to serialize.
[in]	lay	Canonical layout computed from ctx.
[in]	crc	Finalized body CRC-32.

Returns

Complete RABOOK1 header value.

Return values

book_header_t

Header ready for byte emission.

Precondition

ctx and lay are non-NULL.

lay was computed successfully from ctx.

Postcondition

Every header count and offset matches the builder and layout.

The returned header owns no pointers into builder storage.

Note

Pure construction over caller-owned state.

Since

0.1.0

Definition at line 342 of file ra8_rabook_finalize.c.

References book_header_t::attr_count, ra8_rabook_ctx_t::attr_count, book_header_t::attr_off, book_header_t::author_off, ra8_rabook_ctx_t::author_off, book_header_t::chapter_count, ra8_rabook_ctx_t::chapter_count, book_header_t::chapter_off, book_header_t::cover_image_index, ra8_rabook_ctx_t::cover_image_index, book_header_t::crc32_val, book_header_t::flags, ra8_rabook_ctx_t::flags, book_header_t::format_version, book_header_t::identifier_off, ra8_rabook_ctx_t::identifier_off, book_header_t::image_count, ra8_rabook_ctx_t::image_count, book_header_t::image_off, book_header_t::image_pool_off, book_header_t::image_pool_size, ra8_rabook_ctx_t::image_pool_size, k_book_format_version, book_header_t::language_off, ra8_rabook_ctx_t::language_off, book_header_t::magic, memcpy(), book_header_t::node_count, ra8_rabook_ctx_t::node_count, book_header_t::node_off, book_header_t::string_off, book_header_t::string_size, ra8_rabook_ctx_t::string_size, book_header_t::stylesheet_count, ra8_rabook_ctx_t::stylesheet_count, book_header_t::stylesheet_off, book_header_t::title_off, ra8_rabook_ctx_t::title_off, and book_header_t::total_size.

Referenced by ra8_rabook_finalize_stream().

internal_memory_write()

ra8_err_t internal_memory_write ( void * opaque, const uint8_t * src, uint32_t requested, uint32_t * out_written )

static

Append one chunk to a bounded memory sink.

Checks remaining capacity before copying and reports zero written on exhaustion, preserving the exact-write callback contract.

Parameters

[in,out]	opaque	Memory-sink context.
[in]	src	Source bytes.
[in]	requested	Requested append length.
[out]	out_written	Actual appended length.

Returns

Sink status.

Return values

k_ra8_ok	The full request was copied.
k_ra8_err_invalid_size	The destination lacks capacity.

Precondition

Context, source, and count pointers are non-NULL.

The sink's used count does not exceed its capacity.

Postcondition

Success advances used and reports requested.

Exhaustion reports zero and leaves the sink unchanged.

Note

Used only by the legacy in-memory finalizer wrapper.

Since

0.1.0

Definition at line 644 of file ra8_rabook_finalize.c.

References ra8_rabook_memory_sink_t::cap, ra8_rabook_memory_sink_t::data, k_ra8_err_invalid_size, k_ra8_ok, memcpy(), and ra8_rabook_memory_sink_t::used.

Referenced by ra8_rabook_finalize().

internal_read_exact()

ra8_err_t internal_read_exact ( ra8_rabook_image_read_fn read, void * read_ctx, uint32_t offset, uint8_t * dst, uint32_t len )

static

Read one exact external-pool chunk, rejecting a short success.

Calls the supplied reader once and converts a successful short count into k_ra8_err_invalid_size.

Parameters

[in]	read	Reader callback.
[in,out]	read_ctx	Reader context.
[in]	offset	Logical pool offset.
[out]	dst	Destination buffer.
[in]	len	Exact requested byte count.

Returns

Exact-transfer status.

Return values

k_ra8_ok	Exactly len bytes were read.
k_ra8_err_invalid_size	The callback reported a short success.

Precondition

Callback and destination pointers are non-NULL.

dst spans len writable bytes.

Postcondition

Success initializes every requested destination byte.

A callback error is propagated unchanged.

Note

Does not retry partial reads.

Since

0.1.0

Definition at line 226 of file ra8_rabook_finalize.c.

References k_ra8_err_invalid_size, and k_ra8_ok.

Referenced by internal_crc_image_pool(), and internal_write_image_pool().

internal_segments()

void internal_segments ( const ra8_rabook_ctx_t * ctx, const ra8_rabook_layout_t * lay, ra8_rabook_segment_t seg[k_rabook_segment_count] )

static

Populate the canonical resident body-segment sequence.

Forms views over the five fixed tables and string pool; the external or internal image payload remains a separate final segment.

Parameters

[in]	ctx	Builder holding resident table and string storage.
[in]	lay	Computed canonical section offsets.
[out]	seg	Six writable segment descriptors.

Precondition

All arguments are non-NULL.

lay was computed from ctx.

Postcondition

Every segment points into a caller-owned builder arena.

Segment lengths exactly cover the body through the string pool.

Note

The returned views remain valid while the builder arenas remain alive.

Since

0.1.0

Definition at line 188 of file ra8_rabook_finalize.c.

References ra8_rabook_buffers_t::attrs, ra8_rabook_ctx_t::buf, ra8_rabook_buffers_t::chapters, ra8_rabook_buffers_t::images, k_rabook_segment_attrs, k_rabook_segment_chapters, k_rabook_segment_count, k_rabook_segment_images, k_rabook_segment_nodes, k_rabook_segment_strings, k_rabook_segment_styles, ra8_rabook_buffers_t::nodes, ra8_rabook_buffers_t::string_pool, ra8_rabook_ctx_t::string_size, and ra8_rabook_buffers_t::stylesheets.

Referenced by ra8_rabook_finalize_stream().

internal_validate_memory_finalize()

ra8_err_t internal_validate_memory_finalize ( ra8_rabook_ctx_t * ctx, const void ** out_blob, const uint32_t * out_len )

static

Validate the legacy in-memory finalizer and output capacity.

Checks result pointers and sticky builder failure, then computes the canonical layout without publishing bytes to prove the sink fits.

Parameters

[in]	ctx	Builder to finalize.
[out]	out_blob	Final output pointer destination.
[out]	out_len	Final serialized length destination.

Returns

Validation status.

Return values

k_ra8_ok	Builder layout fits the configured output arena.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_no_mem	Builder failure was already latched.
k_ra8_err_invalid_size	Layout overflows or exceeds output capacity.

Precondition

Pointer values may be NULL for validation.

ctx, when non-NULL, addresses an initialized builder.

Postcondition

Success permits the streaming wrapper to use the configured sink.

No builder, output bytes, or result pointers are modified.

Note

The streaming finalizer recomputes the same layout before emission.

Since

0.1.0

Definition at line 677 of file ra8_rabook_finalize.c.

References ra8_rabook_ctx_t::buf, ra8_rabook_ctx_t::failed, internal_compute_layout(), k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_ok, ra8_rabook_buffers_t::out_cap, RA8_CHECK_NULL_PTR, ra8_log_error, RA8_RETURN_ON_ERROR, and s_tag_rabook.

Referenced by ra8_rabook_finalize().

internal_validate_stream_args()

ra8_err_t internal_validate_stream_args ( const ra8_rabook_ctx_t * ctx, ra8_rabook_image_read_fn image_read, ra8_rabook_write_fn write, const uint8_t * scratch, uint32_t scratch_cap, const uint32_t * out_len )

static

Validate streaming-finalizer arguments and builder state.

Enforces common pointer requirements, sticky builder failure, and the reader/scratch contract selected by a non-empty external pool.

Parameters

[in]	ctx	Builder to finalize.
[in]	image_read	External image-pool reader, when selected.
[in]	write	Destination writer.
[in]	scratch	External transfer scratch pointer.
[in]	scratch_cap	Scratch capacity in bytes.
[out]	out_len	Final serialized length destination.

Returns

Validation status.

Return values

k_ra8_ok	Arguments satisfy the selected pool mode.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_size	External mode has zero scratch capacity.
k_ra8_err_no_mem	Builder failure was already latched.

Precondition

Pointer values may be NULL for validation.

ctx, when non-NULL, addresses an initialized builder.

Postcondition

Success permits layout, CRC, and emission passes.

No builder or output state is modified.

Note

Internal-pool mode ignores image_read and scratch arguments.

Since

0.1.0

Definition at line 539 of file ra8_rabook_finalize.c.

References ra8_rabook_ctx_t::failed, ra8_rabook_ctx_t::image_pool_mode, ra8_rabook_ctx_t::image_pool_size, k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_err_null_ptr, k_ra8_ok, k_rabook_pool_external, RA8_CHECK_NULL_PTR, ra8_log_error, and s_tag_rabook.

Referenced by ra8_rabook_finalize_stream().

internal_write_book()

ra8_err_t internal_write_book ( const ra8_rabook_ctx_t * ctx, const book_header_t * hdr, const ra8_rabook_segment_t seg[k_rabook_segment_count], ra8_rabook_image_read_fn read, void * read_ctx, ra8_rabook_write_fn write, void * write_ctx, uint8_t * scratch, uint32_t scratch_cap )

static

Emit the fixed header followed by the canonical logical body.

Appends each resident segment exactly, then emits the internal or externally reread image pool.

Parameters

[in]	ctx	Builder describing the logical image pool.
[in]	hdr	Finalized RABOOK1 header.
[in]	seg	Canonical resident segment sequence.
[in]	read	External image-pool reader, when selected.
[in,out]	read_ctx	External reader context.
[in]	write	Destination writer.
[in,out]	write_ctx	Destination writer context.
[in,out]	scratch	External transfer scratch.
[in]	scratch_cap	Scratch capacity in bytes.

Returns

Emission status.

Return values

k_ra8_ok	Header and complete body were appended.
k_ra8_err_invalid_size	A callback reported a short success.

Precondition

ctx, hdr, seg, and write are non-NULL.

hdr describes the supplied segment sequence and image pool.

Postcondition

Success appends exactly the header total-size byte count.

Callback failures are propagated unchanged.

Note

External image bytes are reread after the CRC pass.

Since

0.1.0

Definition at line 492 of file ra8_rabook_finalize.c.

References internal_write_exact(), internal_write_image_pool(), k_ra8_ok, and k_rabook_segment_count.

Referenced by ra8_rabook_finalize_stream().

internal_write_exact()

ra8_err_t internal_write_exact ( ra8_rabook_write_fn write, void * write_ctx, const uint8_t * src, uint32_t len )

static

Append one exact stream chunk, rejecting a short success.

Zero-length segments are skipped; non-empty segments are submitted once and must be accepted completely.

Parameters

[in]	write	Writer callback.
[in,out]	write_ctx	Writer context.
[in]	src	Source bytes.
[in]	len	Exact requested byte count.

Returns

Exact-transfer status.

Return values

k_ra8_ok	The complete segment was appended, or len was zero.
k_ra8_err_invalid_size	The callback reported a short success.

Precondition

write is non-NULL.

src spans len readable bytes when len is nonzero.

Postcondition

Success advances the logical destination by len bytes.

A callback error is propagated unchanged.

Note

Does not retry partial writes.

Since

0.1.0

Definition at line 260 of file ra8_rabook_finalize.c.

References k_ra8_err_invalid_size, and k_ra8_ok.

Referenced by internal_write_book(), and internal_write_image_pool().

internal_write_image_pool()

ra8_err_t internal_write_image_pool ( const ra8_rabook_ctx_t * ctx, ra8_rabook_image_read_fn read, void * read_ctx, ra8_rabook_write_fn write, void * write_ctx, uint8_t * scratch, uint32_t scratch_cap )

static

Emit the logical image pool through the exact-write callback.

Writes an internal pool directly or rereads an external pool in caller-scratch-sized chunks and appends each chunk exactly once.

Parameters

[in]	ctx	Builder describing the logical pool.
[in]	read	External reader, when selected.
[in,out]	read_ctx	External reader context.
[in]	write	Destination writer.
[in,out]	write_ctx	Destination writer context.
[in,out]	scratch	External transfer scratch.
[in]	scratch_cap	Scratch capacity in bytes.

Returns

Pool emission status.

Return values

k_ra8_ok	The entire pool was appended.
k_ra8_err_invalid_size	A read or write callback was short.

Precondition

ctx and write are non-NULL.

External mode supplies a reader and nonzero scratch capacity.

Postcondition

Success appends exactly ctx->image_pool_size bytes.

Callback failures are propagated unchanged.

Note

External reads never exceed scratch_cap.

Since

0.1.0

Definition at line 394 of file ra8_rabook_finalize.c.

References ra8_rabook_ctx_t::buf, ra8_rabook_buffers_t::image_pool, ra8_rabook_ctx_t::image_pool_mode, ra8_rabook_ctx_t::image_pool_size, internal_read_exact(), internal_write_exact(), k_ra8_ok, and k_rabook_pool_external.

Referenced by internal_write_book().

ra8_rabook_finalize()

ra8_err_t ra8_rabook_finalize	(	ra8_rabook_ctx_t *	ctx,
		const void **	out_blob,
		uint32_t *	out_len )

Lay out the tables and pools, fill the header, CRC, and emit the blob.

Copies the chapter, node, attr, stylesheet and image tables, then the string and image pools, into the output buffer at the contract offsets (see the file header), fills the 100-byte book_header_t (magic, version, all offsets / counts / sizes, metadata, total_size), and computes the body CRC-32 over every byte after the header. The result passes book_validate.

Parameters

[in,out]	ctx	Builder context (non-NULL, initialised, no overflow).
[out]	out_blob	Receives the blob base (= the output arena) (non-NULL).
[out]	out_len	Receives the blob length in bytes (non-NULL).

Returns

Error code.

Return values

k_ra8_ok	Blob emitted; out_blob / out_len set.
k_ra8_err_null_ptr	A required pointer argument is NULL.
k_ra8_err_no_mem	A prior builder call overflowed an arena.
k_ra8_err_invalid_size	The laid-out blob exceeds the output capacity.

Precondition

ctx was initialised and no builder call set the sticky failed flag.

The output arena holds the full blob (header + tables + pools).

Postcondition

On k_ra8_ok, out_blob[0..*out_len) is a valid RABOOK1 blob.

On error out_blob / out_len are untouched.

Note

Not thread-safe.

See also

book_validate()

Since

Version 0.1.0

Definition at line 693 of file ra8_rabook_finalize.c.

References ra8_rabook_ctx_t::buf, internal_memory_write(), internal_validate_memory_finalize(), k_ra8_ok, ra8_rabook_buffers_t::out, ra8_rabook_buffers_t::out_cap, and ra8_rabook_finalize_stream().

Referenced by internal_compile_to_blob().

ra8_rabook_finalize_stream()

ra8_err_t ra8_rabook_finalize_stream	(	const ra8_rabook_ctx_t *	ctx,
		ra8_rabook_image_read_fn	image_read,
		void *	image_ctx,
		ra8_rabook_write_fn	write,
		void *	write_ctx,
		uint8_t *	scratch,
		uint32_t	scratch_cap,
		uint32_t *	out_len )

Stream a canonical flat RABOOK1 blob without a full output arena.

Computes the same canonical layout and CRC as ra8_rabook_finalize, then appends the header, tables, string pool, and image pool through write. Internal image pools are read directly. An external image pool is read twice through image_read: once for CRC and once for emission, in chunks no larger than scratch_cap.

Parameters

[in]	ctx	Completed builder context.
[in]	image_read	External image-pool reader; required only for an external non-empty pool.
[in,out]	image_ctx	Context passed to image_read.
[in]	write	Exact append callback.
[in,out]	write_ctx	Context passed to write.
[in,out]	scratch	External-pool transfer scratch; required only for an external non-empty pool.
[in]	scratch_cap	Writable bytes at scratch.
[out]	out_len	Receives the complete flat blob length.

Returns

Finalization status.

Return values

k_ra8_ok	Blob streamed completely and out_len set.
k_ra8_err_null_ptr	A required pointer or callback is NULL.
k_ra8_err_no_mem	A prior builder operation overflowed an arena.
k_ra8_err_invalid_size	Layout overflow, zero external scratch, or a short callback transfer.

Returns

Other callback failures are propagated unchanged.

Precondition

The external reader is repeatable and exposes the logical pool recorded by ra8_rabook_add_image_external.

write appends atomically or reports the exact short transfer.

Postcondition

On success exactly *out_len bytes were appended in canonical order.

On failure out_len is untouched; the destination may hold a prefix.

Note

Uses only caller storage and fixed stack state; performs no allocation.

Since

0.1.0

Definition at line 573 of file ra8_rabook_finalize.c.

References internal_compute_layout(), internal_crc_body(), internal_make_header(), internal_segments(), internal_validate_stream_args(), internal_write_book(), k_ra8_ok, and k_rabook_segment_count.

Referenced by ra8_rabook_comic_finish(), and ra8_rabook_finalize().

Variable Documentation

s_tag_rabook

const char* const s_tag_rabook = "ra8_rabook_finalize"

static

Component tag for finalizer diagnostics.

Definition at line 25 of file ra8_rabook_finalize.c.

Referenced by internal_check_buffer_members(), internal_compute_layout(), internal_validate_memory_finalize(), internal_validate_stream_args(), ra8_rabook_link_child(), ra8_rabook_link_sibling(), ra8_rabook_set_metadata(), and rabook_compile_init().