On-silicon HIL: EPUB cover-art extraction + decode + render (#143). More...

#include <stddef.h>
#include <stdint.h>
#include "epub.h"
#include "epub_cover_fixture.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_err.h"
#include "ra8_gfx.h"
#include "ra8_isr.h"
#include "ra8_mstp.h"
#include "ra8_time.h"
#include "reflow_image.h"

Include dependency graph for main.c:

Enumerations
enum	ec_consts_t : uint32_t { k_ec_uart_baud = 115200U , k_ec_fb_w = 160U , k_ec_fb_h = 120U , k_ec_arena_bytes = 128U * 1024U , k_ec_cover_cap = 64U * 1024U , k_ec_col_bg = 0x202028U , k_ec_fnv_offset = 0x811C9DC5U , k_ec_fnv_prime = 0x01000193U , k_ec_hex_nibbles = 8U , k_ec_nibble_bits = 4U , k_ec_nibble_mask = 0x0FU , k_ec_dec_ten = 10U }
	Console / render knobs (no magic numbers). More...

Functions
static void	ec_print (const uint8_t *msg, uint32_t len)
	Emit a byte run on the SCI8 console.
static void	ec_panic_halt (const uint8_t *msg, uint32_t len)
	Print the fail banner and trap (ra8_emulator halts on the BKPT).
static uint32_t	ec_framebuffer_hash (void)
	FNV-1a hash over the rendered framebuffer.
static void	ec_print_hex (uint32_t value)
	Print a 32-bit value as 8 upper-case hex digits.
static void	ec_print_uint (uint32_t value)
	Print a small unsigned integer in decimal.
static void	ec_setup_or_halt (void)
	Bring up clocks/MSTP/time + the SCI8 console; halt on failure.
static size_t	ec_render_cover_or_halt (int32_t out_w, int32_t out_h)
	Open the EPUB, extract the cover, decode+scale+blit it; return size.
void	main (void)
	App entry: extract + decode + render the EPUB cover, print the banner.

Variables
static epub_book_t	s_book
	Opened book (large – file-scope, not on the stack).
static uint8_t	s_cover [k_ec_cover_cap]
	Cover-image read buffer (file-scope; holds the raw encoded bytes).
static uint16_t	s_framebuffer [(size_t) k_ec_fb_h *(size_t) k_ec_fb_w]
	RGB565 framebuffer the cover is rendered into.
static uint8_t	s_img_arena [k_ec_arena_bytes]
	Fixed bump arena backing the heap-free image decode.
static const uint8_t	k_msg_boot [] = "ereader-cover-hil: boot\r\n"
static const uint8_t	k_msg_fail [] = "ereader-cover-hil: FAIL init\r\n"
static const uint8_t	k_msg_open [] = "ereader-cover-hil: FAIL open\r\n"
static const uint8_t	k_msg_cov [] = "ereader-cover-hil: FAIL cover\r\n"
static const uint8_t	k_msg_derr [] = "ereader-cover-hil: FAIL decode\r\n"
static const uint8_t	k_msg_pre [] = "ereader-cover-hil: cover "
static const uint8_t	k_msg_x [] = "x"
static const uint8_t	k_msg_crc [] = " crc="
static const uint8_t	k_msg_ok [] = " PASS\r\n"

Detailed Description

On-silicon HIL: EPUB cover-art extraction + decode + render (#143).

The headline "book cover art" path for the on-device e-reader, end to end:

epub_open – open a baked, cover-bearing .epub in memory (vendored miniz ZIP + bounded XML reader, zero-heap via epub_miniz_alloc).
epub_get_cover_image – resolve the properties="cover-image" manifest item and copy the cover's raw PNG bytes into a buffer.
ra8_img_decode_blit – decode the PNG (stb_image), scale-to-fit it into the framebuffer box preserving aspect ratio, and blit it – allocating only from a fixed SRAM bump arena (no malloc, NASA Rule 3).
FNV-1a hash the rendered framebuffer.

The console banner on success is:

ereader-cover-hil: cover <W>x<H> crc=<8hex> PASS

where <W>x<H> is the blitted (scaled) size and <8hex> the framebuffer hash. The whole chain is deterministic (a fixed blob through a deterministic parser + decoder + scaler), so the banner is identical on host, ra8_emulator, and silicon. Any failure on any stage prints a FAIL banner and halts on a BKPT before the PASS line, so the gate is exact.

This is the EPUB analogue of ereader_image (#106, which decodes a bare baked PNG): the only new surface is the epub_get_cover_image extraction in front of the proven decode+scale+blit pipeline.

[Ring 7 / App] {World: NS}

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

Since: 0.1.0

Definition in file main.c.

Enumeration Type Documentation

◆ ec_consts_t

enum ec_consts_t : uint32_t

Console / render knobs (no magic numbers).

Enumerator
k_ec_uart_baud	Console baud.
k_ec_fb_w	Framebuffer width, pixels.
k_ec_fb_h	Framebuffer height, pixels.
k_ec_arena_bytes	Image decode scratch, bytes.
k_ec_cover_cap	Cover-image read buffer capacity.
k_ec_col_bg	Framebuffer clear colour.
k_ec_fnv_offset	FNV-1a 32-bit offset basis.
k_ec_fnv_prime	FNV-1a 32-bit prime.
k_ec_hex_nibbles	Hex digits in a 32-bit value.
k_ec_nibble_bits	Bits per hex nibble.
k_ec_nibble_mask	Low-nibble mask.
k_ec_dec_ten	Hex digit / decimal split.

Definition at line 55 of file main.c.

Function Documentation

◆ ec_framebuffer_hash()

uint32_t ec_framebuffer_hash ( void )

static

FNV-1a hash over the rendered framebuffer.

Definition at line 106 of file main.c.

References k_ec_fnv_offset, k_ec_fnv_prime, and s_framebuffer.

Referenced by main().

◆ ec_panic_halt()

void ec_panic_halt	(	const uint8_t *	msg,
		uint32_t	len )

static

Print the fail banner and trap (ra8_emulator halts on the BKPT).

Definition at line 96 of file main.c.

References ec_print().

Referenced by ec_render_cover_or_halt(), ec_setup_or_halt(), and main().

◆ ec_print()

void ec_print	(	const uint8_t *	msg,
		uint32_t	len )

static

Emit a byte run on the SCI8 console.

Definition at line 90 of file main.c.

References ra8_board_uart_console_write().

Referenced by ec_panic_halt(), ec_print_hex(), ec_print_uint(), and main().

◆ ec_print_hex()

void ec_print_hex ( uint32_t value )

static

Print a 32-bit value as 8 upper-case hex digits.

Definition at line 118 of file main.c.

References ec_print(), k_ec_dec_ten, k_ec_hex_nibbles, k_ec_nibble_bits, and k_ec_nibble_mask.

Referenced by main().

◆ ec_print_uint()

void ec_print_uint ( uint32_t value )

static

Print a small unsigned integer in decimal.

Definition at line 130 of file main.c.

References ec_print(), and k_ec_dec_ten.

Referenced by main().

◆ ec_render_cover_or_halt()

size_t ec_render_cover_or_halt	(	int32_t *	out_w,
		int32_t *	out_h )

static

Open the EPUB, extract the cover, decode+scale+blit it; return size.

Halts on any failure stage before returning. On success the cover has been rendered into s_framebuffer and the blitted dimensions are returned via out_w / out_h.

Parameters

[out]	out_w	Receives the blitted (scaled) cover width, pixels.
[out]	out_h	Receives the blitted (scaled) cover height, pixels.

Returns: The number of raw cover bytes extracted from the manifest.

Precondition: ec_setup_or_halt ran and ra8_gfx_init bound s_framebuffer.

Postcondition: On return s_framebuffer holds the scaled cover; out_w/out_h set.

Since: 0.1.0

Definition at line 182 of file main.c.

References ec_panic_halt(), epub_get_cover_image(), epub_open(), k_ec_arena_bytes, k_ec_cover_cap, k_ec_fb_h, k_ec_fb_w, k_epub_cover_fixture, k_epub_cover_fixture_len, k_msg_cov, k_msg_derr, k_msg_open, k_ra8_ok, ra8_img_decode_blit(), s_book, s_cover, and s_img_arena.

Referenced by main().

◆ ec_setup_or_halt()

void ec_setup_or_halt ( void )

static

Bring up clocks/MSTP/time + the SCI8 console; halt on failure.

Definition at line 149 of file main.c.

References ec_panic_halt(), k_ec_uart_baud, k_msg_fail, k_ra8_clock_id_cpuclk0, k_ra8_ok, ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), ra8_mstp_init(), and ra8_time_init().

Referenced by main().

◆ main()

void main ( void )

App entry: extract + decode + render the EPUB cover, print the banner.

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: The cover-size / framebuffer-CRC banner is emitted; CPU loops in WFI.

Since: 0.1.0

Definition at line 221 of file main.c.

References ec_framebuffer_hash(), ec_panic_halt(), ec_print(), ec_print_hex(), ec_print_uint(), ec_render_cover_or_halt(), ec_setup_or_halt(), k_ec_col_bg, k_ec_fb_h, k_ec_fb_w, k_msg_boot, k_msg_crc, k_msg_fail, k_msg_ok, k_msg_pre, k_msg_x, k_ra8_gfx_format_rgb565, k_ra8_ok, ra8_gfx_clear(), ra8_gfx_init(), ra8_isr_globals_enable(), and s_framebuffer.

Variable Documentation

◆ k_msg_boot

const uint8_t k_msg_boot[] = "ereader-cover-hil: boot\r\n"

static

Definition at line 79 of file main.c.

◆ k_msg_cov

const uint8_t k_msg_cov[] = "ereader-cover-hil: FAIL cover\r\n"

static

Definition at line 82 of file main.c.

◆ k_msg_crc

const uint8_t k_msg_crc[] = " crc="

static

Definition at line 86 of file main.c.

◆ k_msg_derr

const uint8_t k_msg_derr[] = "ereader-cover-hil: FAIL decode\r\n"

static

Definition at line 83 of file main.c.

Referenced by ec_render_cover_or_halt(), and main().

◆ k_msg_fail

const uint8_t k_msg_fail[] = "ereader-cover-hil: FAIL init\r\n"

static

Definition at line 80 of file main.c.

◆ k_msg_ok

const uint8_t k_msg_ok[] = " PASS\r\n"

static

Definition at line 87 of file main.c.

◆ k_msg_open

const uint8_t k_msg_open[] = "ereader-cover-hil: FAIL open\r\n"

static

Definition at line 81 of file main.c.

◆ k_msg_pre

const uint8_t k_msg_pre[] = "ereader-cover-hil: cover "

static

Definition at line 84 of file main.c.

◆ k_msg_x

const uint8_t k_msg_x[] = "x"

static

Definition at line 85 of file main.c.

Referenced by erb_render_image(), ez_print_banner(), ls_emit_banner(), main(), and mg_print_banner().

◆ s_book

epub_book_t s_book

static

Opened book (large – file-scope, not on the stack).

Definition at line 71 of file main.c.

◆ s_cover

uint8_t s_cover[k_ec_cover_cap]

static

Cover-image read buffer (file-scope; holds the raw encoded bytes).

Definition at line 73 of file main.c.

◆ s_framebuffer

uint16_t s_framebuffer[(size_t) k_ec_fb_h *(size_t) k_ec_fb_w]

static

RGB565 framebuffer the cover is rendered into.

Definition at line 75 of file main.c.

◆ s_img_arena

uint8_t s_img_arena[k_ec_arena_bytes]

static

Fixed bump arena backing the heap-free image decode.

Definition at line 77 of file main.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ec_consts_t

Function Documentation

◆ ec_framebuffer_hash()

◆ ec_panic_halt()

◆ ec_print()

◆ ec_print_hex()

◆ ec_print_uint()

◆ ec_render_cover_or_halt()

◆ ec_setup_or_halt()

◆ main()

Variable Documentation

◆ k_msg_boot

◆ k_msg_cov

◆ k_msg_crc

◆ k_msg_derr

◆ k_msg_fail

◆ k_msg_ok

◆ k_msg_open

◆ k_msg_pre

◆ k_msg_x

◆ s_book

◆ s_cover

◆ s_framebuffer

◆ s_img_arena