Headless on-silicon HIL gate for reflow content render + pagination (#115). More...

#include <stddef.h>
#include <stdint.h>
#include "font_fixture.h"
#include "ra8_attributes.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.h"

Include dependency graph for main.c:

Enumerations
enum	rc_consts_t : uint32_t { k_rc_fb_w = 160U , k_rc_fb_h = 192U , k_rc_font_px = 16U , k_rc_reflow_px = 24U , k_rc_ink = 0xFF101010U , k_rc_link_col = 0xFF2A52BEU , k_rc_bg = 0xF4F0E8U , k_rc_uart_baud = 115200U , k_rc_fnv_offset = 2166136261U , k_rc_fnv_prime = 16777619U , k_rc_hex_nibbles = 8U , k_rc_nibble_bits = 4U , k_rc_nibble_mask = 0x0FU , k_rc_dec_ten = 10U }
	Framebuffer / console / hash / type-size knobs. More...

Functions
static void	internal_rc_print (const uint8_t *msg, uint32_t len)
	Emit a byte run on the board UART console.
static void	internal_rc_panic_halt (const uint8_t *msg, uint32_t len)
	Emit a failure banner, break into the debugger, and halt.
static void	internal_rc_print_hex (uint32_t value)
	Print a 32-bit value as eight uppercase hexadecimal digits.
static void	internal_rc_print_uint (uint32_t value)
	Print an unsigned 32-bit integer in decimal.
static uint32_t	internal_rc_render_all (uint32_t *out_hash)
	Render every page of the laid-out chapter; fold an FNV over the output.
static void	internal_rc_setup_or_halt (void)
	Bring up clocks, module-stop control, timekeeping, and the console.
void	main (void)
	App entry: paginate + render the chapter, re-flow bigger, print.

Variables
static uint16_t	s_framebuffer [(size_t) k_rc_fb_h *(size_t) k_rc_fb_w]
	RGB565 framebuffer in internal SRAM (no panel attached).
static reflow_t	s_engine
	Reflow engine (large – file-scope, not on the stack).
static const char	s_rc_chapter []
	Fixed multi-paragraph HTML chapter used by both layout passes.
static const uint8_t	s_msg_boot [] = "reflow-content-hil: boot\r\n"
	Boot diagnostic emitted after platform initialization.
static const uint8_t	s_msg_fail [] = "reflow-content-hil: FAIL init\r\n"
	Fatal platform or engine initialization diagnostic.
static const uint8_t	s_msg_lerr [] = "reflow-content-hil: FAIL layout\r\n"
	Fatal chapter layout or font-size reflow diagnostic.
static const uint8_t	s_msg_pre [] = "reflow-content-hil: pages="
	Prefix for the original page-count diagnostic.
static const uint8_t	s_msg_crc [] = " crc="
	Separator introducing a rendered-framebuffer hash.
static const uint8_t	s_msg_rpages [] = " rpages="
	Separator introducing the larger-font page count.
static const uint8_t	s_msg_eol [] = "\r\n"
	Console line terminator for the result banner.

Detailed Description

Headless on-silicon HIL gate for reflow content render + pagination (#115).

Closes the real-hardware gap for the book-content render path: paginate a multi-page chapter, render every page into a framebuffer, and exercise a font-size re-flow – no panel / SD / touch needed. The app lays out a baked multi-paragraph chapter through reflow (fixed-metric Ahem face) into a 160x192 RGB565 framebuffer, renders each page and folds an FNV-1a-32 over the framebuffer, then calls reflow_set_font_size() to re-flow at a larger size and renders again. It prints a banner on the SCI8 J-Link OB console:

reflow-content-hil: pages=<N> crc=<8 hex> rpages=<M> crc=<8 hex>

Ahem's fixed metrics make pagination + render deterministic; the banner is identical every boot (stable across resets) and matches the host / ra8_emulator run, so any drift in the layout, pagination, or render changes the hash.

[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

◆ rc_consts_t

enum rc_consts_t : uint32_t

Framebuffer / console / hash / type-size knobs.

Enumerator
k_rc_fb_w	Framebuffer width, pixels.
k_rc_fb_h	Framebuffer height, pixels.
k_rc_font_px	Body font size, pixels.
k_rc_reflow_px	Re-flow font size, pixels.
k_rc_ink	Body ink colour (ARGB).
k_rc_link_col	Anchor colour (ARGB).
k_rc_bg	Page background (0x00RRGGBB).
k_rc_uart_baud	Console baud.
k_rc_fnv_offset	FNV-1a-32 offset basis.
k_rc_fnv_prime	FNV-1a-32 prime.
k_rc_hex_nibbles	Hex digits in a 32-bit value.
k_rc_nibble_bits	Bits per hex nibble.
k_rc_nibble_mask	Low-nibble mask.
k_rc_dec_ten	Hex digit / decimal split.

Definition at line 44 of file main.c.

Function Documentation

◆ internal_rc_panic_halt()

void internal_rc_panic_halt	(	const uint8_t *	msg,
		uint32_t	len )

static

Emit a failure banner, break into the debugger, and halt.

Writes the supplied diagnostic, executes bkpt #0 for emulator visibility, then parks forever using bounded single-instruction waits.

Parameters

[in]	msg	First byte of the fatal diagnostic.
[in]	len	Number of diagnostic bytes to emit.

Precondition: msg references at least len readable bytes.; The console is initialized or the caller accepts a silent failure banner.

Postcondition: The debugger break instruction has executed.; Control never returns to the caller.

Note: On hardware without a debugger, execution proceeds directly to the wait loop.

Since: 0.1.0

Definition at line 176 of file main.c.

References internal_rc_print(), and RA8_INTERNAL.

Referenced by internal_rc_setup_or_halt(), and main().

◆ internal_rc_print()

void internal_rc_print	(	const uint8_t *	msg,
		uint32_t	len )

static

Emit a byte run on the board UART console.

Forwards a caller-owned span without allocation and treats console output as diagnostic rather than acceptance-critical state.

Parameters

[in]	msg	First byte of the diagnostic span.
[in]	len	Number of bytes to offer to the console.

Precondition: msg references at least len readable bytes.; The board UART console has been initialized.

Postcondition: At most len bytes have been offered to the console backend.; The caller's span remains unchanged.

Note: Write errors are deliberately ignored by this HIL-only helper.

Since: 0.1.0

Definition at line 158 of file main.c.

References ra8_board_uart_console_write(), and RA8_INTERNAL.

Referenced by internal_rc_panic_halt(), internal_rc_print_hex(), internal_rc_print_uint(), and main().

◆ internal_rc_print_hex()

void internal_rc_print_hex ( uint32_t value )

static

Print a 32-bit value as eight uppercase hexadecimal digits.

Extracts nibbles from most significant to least significant and emits one fixed-width stack buffer through the console helper.

Parameters

[in] value Value to format.

Precondition: The console helper is ready to accept eight bytes.; k_rc_hex_nibbles remains eight for the 32-bit input width.

Postcondition: Exactly eight hexadecimal characters have been offered to the console.; value and all application diagnostics remain unchanged.

Note: Leading zeroes are retained for stable HIL parsing.

Since: 0.1.0

Definition at line 197 of file main.c.

References internal_rc_print(), k_rc_dec_ten, k_rc_hex_nibbles, k_rc_nibble_bits, k_rc_nibble_mask, and RA8_INTERNAL.

Referenced by main().

◆ internal_rc_print_uint()

void internal_rc_print_uint ( uint32_t value )

static

Print an unsigned 32-bit integer in decimal.

Collects digits in reverse order in a fixed ten-byte stack buffer, then emits them from most significant to least significant.

Parameters

[in] value Value to format.

Precondition: The console helper is initialized.; The fixed buffer can represent every uint32_t decimal value.

Postcondition: At least one and at most ten decimal characters have been emitted.; No application state outside the console backend is modified.

Note: Zero is handled explicitly so it still emits one character.

Since: 0.1.0

Definition at line 220 of file main.c.

References internal_rc_print(), k_rc_dec_ten, and RA8_INTERNAL.

Referenced by main().

◆ internal_rc_render_all()

uint32_t internal_rc_render_all ( uint32_t * out_hash )

static

Render every page of the laid-out chapter; fold an FNV over the output.

Clears and renders each page into the static RGB565 framebuffer, then folds every output byte into one FNV-1a-32 diagnostic hash.

Parameters

[out] out_hash Receives the FNV-1a-32 over every page's framebuffer.

Returns: The page count.

Return values

0	The engine currently contains no pages.
1..UINT32_MAX	Number of pages reported by the engine.

Precondition: out_hash points to writable storage.; s_engine contains a successfully laid-out chapter.

Postcondition: *out_hash contains the ordered hash of all rendered page bytes.; s_framebuffer contains the final rendered page when pages exist.

Note: Render return values are intentionally covered by the final deterministic hash.

Since: 0.1.0

Definition at line 253 of file main.c.

References k_rc_bg, k_rc_fb_h, k_rc_fb_w, k_rc_fnv_offset, k_rc_fnv_prime, ra8_gfx_clear(), RA8_INTERNAL, reflow_get_page_count(), reflow_render_page(), s_engine, and s_framebuffer.

Referenced by main().

◆ internal_rc_setup_or_halt()

void internal_rc_setup_or_halt ( void )

static

Bring up clocks, module-stop control, timekeeping, and the console.

Initializes dependencies in order, derives CPUCLK0 for SysTick, and routes any failure through the permanent diagnostic halt path.

Precondition: Core reset initialization has completed and peripheral registers are accessible.; Configurable interrupts remain globally masked.

Postcondition: On success the timebase and board UART console are ready.; On failure the initialization banner is emitted and control never returns.

Note: The caller enables global interrupts only after this helper succeeds.

Since: 0.1.0

Definition at line 282 of file main.c.

References internal_rc_panic_halt(), k_ra8_clock_id_cpuclk0, k_ra8_ok, k_rc_uart_baud, ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), RA8_INTERNAL, ra8_mstp_init(), ra8_time_init(), and s_msg_fail.

Referenced by main().

◆ main()

void main ( void )

App entry: paginate + render the chapter, re-flow bigger, print.

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 page-count + render-hash banner is emitted; the CPU loops in WFI.

Since: 0.1.0

Definition at line 307 of file main.c.

References internal_rc_panic_halt(), internal_rc_print(), internal_rc_print_hex(), internal_rc_print_uint(), internal_rc_render_all(), internal_rc_setup_or_halt(), k_ra8_gfx_format_rgb565, k_ra8_ok, k_rc_fb_h, k_rc_fb_w, k_rc_font_px, k_rc_ink, k_rc_link_col, k_rc_reflow_px, ra8_gfx_init(), ra8_isr_globals_enable(), reflow_init(), reflow_layout_chapter(), reflow_set_font_size(), s_ahem_ttf, s_ahem_ttf_len, s_engine, s_framebuffer, s_msg_boot, s_msg_crc, s_msg_eol, s_msg_fail, s_msg_lerr, s_msg_pre, s_msg_rpages, and s_rc_chapter.

Variable Documentation

◆ s_engine

reflow_t s_engine

static

Reflow engine (large – file-scope, not on the stack).

Definition at line 65 of file main.c.

◆ s_framebuffer

uint16_t s_framebuffer[(size_t) k_rc_fb_h *(size_t) k_rc_fb_w]

static

RGB565 framebuffer in internal SRAM (no panel attached).

Definition at line 62 of file main.c.

◆ s_msg_boot

const uint8_t s_msg_boot[] = "reflow-content-hil: boot\r\n"

static

Boot diagnostic emitted after platform initialization.

Separates successful console bring-up from later reflow output.

Note: The terminating null byte is excluded from writes.

Since: 0.1.0

Definition at line 95 of file main.c.

◆ s_msg_crc

const uint8_t s_msg_crc[] = " crc="

static

Separator introducing a rendered-framebuffer hash.

Labels both the normal-size and larger-font FNV-1a results.

Note: Followed immediately by eight uppercase hexadecimal digits.

Since: 0.1.0

Definition at line 127 of file main.c.

Referenced by main().

◆ s_msg_eol

const uint8_t s_msg_eol[] = "\r\n"

static

Console line terminator for the result banner.

Uses CRLF to match the board UART console's diagnostic convention.

Note: Contains no terminating payload beyond the two control bytes.

Since: 0.1.0

Definition at line 143 of file main.c.

Referenced by main().

◆ s_msg_fail

const uint8_t s_msg_fail[] = "reflow-content-hil: FAIL init\r\n"

static

Fatal platform or engine initialization diagnostic.

Identifies failures before a valid chapter layout exists.

Note: Emission is followed by a debugger break and permanent halt.

Since: 0.1.0

Definition at line 103 of file main.c.

◆ s_msg_lerr

const uint8_t s_msg_lerr[] = "reflow-content-hil: FAIL layout\r\n"

static

Fatal chapter layout or font-size reflow diagnostic.

Distinguishes content-processing failures from platform initialization.

Note: Emission is followed by a debugger break and permanent halt.

Since: 0.1.0

Definition at line 111 of file main.c.

Referenced by main().

◆ s_msg_pre

const uint8_t s_msg_pre[] = "reflow-content-hil: pages="

static

Prefix for the original page-count diagnostic.

Begins the single stable result line consumed by the HIL operator.

Note: Followed immediately by an unsigned decimal page count.

Since: 0.1.0

Definition at line 119 of file main.c.

Referenced by main().

◆ s_msg_rpages

const uint8_t s_msg_rpages[] = " rpages="

static

Separator introducing the larger-font page count.

Marks the result produced after the cached chapter is reflowed.

Note: Followed immediately by an unsigned decimal page count.

Since: 0.1.0

Definition at line 135 of file main.c.

Referenced by main().

◆ s_rc_chapter

const char s_rc_chapter[]

static

Initial value:

                             =
"<html><body><h1>The Machine</h1>"
"<p>The Time Traveller was expounding a recondite matter to us. His pale grey "
"eyes shone and twinkled, and his usually pale face was flushed and animated.</p>"
"<p>The fire burnt brightly, and the soft radiance of the incandescent lights "
"caught the bubbles that flashed and passed in our glasses.</p>"
"<p>Our chairs, being his patents, embraced and caressed us rather than "
"submitted to be sat upon, and there was that luxurious after-dinner "
"atmosphere when thought runs gracefully free of the trammels of precision.</p>"
"<p>And he put it to us in this way, marking the points with a lean forefinger, "
"as we sat and lazily admired his earnestness over this new paradox.</p>"
"</body></html>"

Fixed multi-paragraph HTML chapter used by both layout passes.

Contains enough prose to span several pages and expose changes in pagination when the font size is increased.

Note: Both render hashes are derived from these exact immutable bytes.

Since: 0.1.0

Definition at line 75 of file main.c.

Referenced by main().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ rc_consts_t

Function Documentation

◆ internal_rc_panic_halt()

◆ internal_rc_print()

◆ internal_rc_print_hex()

◆ internal_rc_print_uint()

◆ internal_rc_render_all()

◆ internal_rc_setup_or_halt()

◆ main()

Variable Documentation

◆ s_engine

◆ s_framebuffer

◆ s_msg_boot

◆ s_msg_crc

◆ s_msg_eol

◆ s_msg_fail

◆ s_msg_lerr

◆ s_msg_pre

◆ s_msg_rpages

◆ s_rc_chapter