main.c File Reference

App-shell chrome: launch reader / library / settings apps (#146 Ph2). More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_app.h"
#include "ra8_attributes.h"
#include "ra8_board_ek_ra8d2_peripherals.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_widget.h"

Include dependency graph for main.c:

Go to the source code of this file.

Data Structures
struct	app_shell_ctx_t
	Per-app stub state: a display name + lifecycle-call counters. More...

Macros
#define	APP_SHELL_SETTINGS   (1)
	Build-time selector for the optional settings app (#146 exclusion).

Enumerations
enum	app_shell_hil_t : uint32_t { k_app_shell_hil_baud = 115200U }
	VCOM-console line rate for the deterministic HIL success banner. More...
enum	app_shell_id_t : uint16_t {   k_app_id_library = 1U ,   k_app_id_reader = 2U ,   k_app_id_settings = 3U }
	Registered app ids (launch keys). More...
enum	app_shell_const_t : uint16_t {   k_app_reg_cap = 3U ,   k_app_nav_cap = 4U ,   k_app_idx_library = 0U ,   k_app_btn_back = 1U }
	Capacities, the launcher tile index, and the chrome button id. More...

Functions
static bool	app_shell_hil_console_init (void)
	Bring up the SCI8 / J-Link OB VCOM console for the HIL success banner.
static void	app_shell_hil_emit_pass (void)
	Emit the deterministic HIL success banner over the VCOM console.
static ra8_err_t	app_stub_init (ra8_app_t *a)
	Stub init: count the one-time setup and log it (runs at register).
static void	app_stub_on_enter (ra8_app_t *a)
	Stub on_enter: count the focus gain and log it.
static void	app_stub_on_leave (ra8_app_t *a)
	Stub on_leave: count the focus loss and log it.
static void	app_stub_render (const ra8_app_t *a)
	Stub render: count the frame and log it (stands in for drawing).
static bool	app_stub_on_input (ra8_app_t *a, const ra8_widget_event_t *ev)
	Stub on_input: count the event, consume only the "back" button.
static void	app_stub_deinit (ra8_app_t *a)
	Stub deinit: count the teardown and log it (wired, not yet fired).
static bool	app_shell_add (ra8_app_t *app, app_shell_ctx_t *ctx, uint16_t id, const char *name, bool removable)
	Build one app instance from the shared vtable and register it.
static bool	app_shell_register (void)
	Initialise the registry + back-stack and register every app.
static void	app_shell_log_menu (void)
	Log the launcher "menu": every registered app, its id, and its class.
static bool	app_shell_launch_library (void)
	Launcher: list the apps then launch library by its registry index.
static bool	app_shell_open_reader (void)
	Open reader from library, then route a back-button event to it.
static bool	app_shell_settings_round_trip (void)
	Open settings from reader, then go "back" to reader.
static bool	app_shell_back_to_root (void)
	Press "back" to the root: pop to library and confirm the empty trail.
static bool	app_shell_uninstall_demo (void)
	Exercise the run-time "core uninstallable" rule: refuse core, unmount one.
static bool	app_shell_selfcheck (void)
	Run the whole deterministic launcher + navigate + back-stack surface.
static void	app_shell_banner (void)
	Emit the PASS banner: app count, library enters, and the PASS line.
void	main (void)
	App entry: register the apps, run the launcher self-check, emit PASS.

Variables
static const uint8_t	k_app_shell_pass_banner [] = "app_shell_demo: demo PASS\r\n"
	Deterministic, run-to-run-stable HIL success banner (uart_scrape gate).
static ra8_app_registry_t	s_reg
	The app registry (single active app + membership table).
static ra8_app_t *	s_slots [k_app_reg_cap]
	Caller-owned storage backing the registry's app-pointer table.
static uint16_t	s_nav_stack [k_app_nav_cap]
	Caller-owned storage backing the navigation back-stack (app ids).
static ra8_app_nav_t	s_nav
	Navigation back-stack layered over s_reg.
static app_shell_ctx_t	s_library_ctx = {.name = "library"}
	Stub state for the core library app.
static ra8_app_t	s_library_app
	The core library app instance (registered into s_reg).
static app_shell_ctx_t	s_reader_ctx = {.name = "reader"}
	Stub state for the core reader app.
static ra8_app_t	s_reader_app
	The core reader app instance (registered into s_reg).
static app_shell_ctx_t	s_settings_ctx = {.name = "settings"}
	Stub state for the optional settings app.
static ra8_app_t	s_settings_app
	The optional settings app instance (registered into s_reg).
static const ra8_app_vtable_t	k_app_stub_vt
	Shared lifecycle vtable for every stub app (behaviour keyed off ctx).

Detailed Description

App-shell chrome: launch reader / library / settings apps (#146 Ph2).

The chrome / "shell" increment of the app framework (issue #146, Phase 2). It builds on the Phase-1 ra8_app registry + per-app vtable + navigation back-stack (app_launch_demo) and adds the piece a home screen needs: a small launcher that lists the registered apps and launches the one the user picks, with "back" unwinding the navigation trail. No display and no widgets this increment – the path is observable headlessly on ra8_emulator through the ITM log (each line shows up as [itm] ...).

What it does, acting as the device "chrome":

1. Registers three first-class apps into one registry, each a real ra8_app vtable (init / on_enter / render(draw) / on_input(event) / on_leave / deinit(teardown)):
   • library (id 1) – core, non-removable (removable = false): the file/book organizer.
   • reader (id 2) – core, non-removable (removable = false): the EPUB reader.
   • settings (id 3) – optional, removable (removable = true), wrapped in a build-time guard (#if APP_SHELL_SETTINGS). Building with -DAPP_SHELL_SETTINGS=0 drops it from the registry entirely – the "core uninstallable" build-time-exclusion mechanism from #146 – and the shell still builds + runs (it just skips the settings leg).
2. Presents a launcher: enumerates the registry (ra8_app_count + ra8_app_at), logs each app as a menu entry, and launches one by its position through ra8_app_nav_go_index (the by-index launcher bridge).
3. Navigates library -> reader -> settings with ra8_app_nav_go, the focus lifecycle firing under every move (on_leave -> on_enter) and each outgoing app pushed onto the back-stack.
4. Presses "back" twice with ra8_app_nav_back, unwinding settings -> reader -> library so the back-stack empties and library is foreground again.

Each stub app's callbacks just count and log their lifecycle (no real UI). A deterministic self-check asserts the exact call counts + back-stack depth at every step, then emits:

[app_shell] INFO: app_shell_demo PASS (ra8_emulator: [itm] [app_shell] INFO: app_shell_demo PASS)

so the app doubles as a ra8_emulator regression gate; any failure logs a FAIL ... line and parks in WFI.

After the navigation legs the shell exercises the run-time "core uninstallable" rule: it asks the framework to uninstall the core library app (refused, k_ra8_err_not_supported) and then the removable settings app (unmounted – its deinit fires and it leaves the registry), proving the removable flag has teeth at run time and not just at build time.

Note

Wiring real ra8_widget UIs into each app (an "app = a widget tree") is the next increment. It is deliberately kept out here so this shell stays decoupled from ra8_widget's in-flight changes: the framework only routes the lifecycle + input + render to the active app, and the concrete draw lives in each app's render callback (a no-op-but-logged stub today).

Each app's deinit callback is exercised by the uninstall leg below (ra8_app_uninstall runs an unmounted app's deinit once); a core app's deinit never fires because a core app can never be uninstalled.

[Ring 6 / APP] {World: S}

Copyright

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

Since

0.1.0

Definition in file main.c.

Macro Definition Documentation

APP_SHELL_SETTINGS

#define APP_SHELL_SETTINGS   (1)

Build-time selector for the optional settings app (#146 exclusion).

APP SHELL SETTINGS.

Defaults to 1 (settings shipped). Define it to 0 at configure time (-DAPP_SHELL_SETTINGS=0) to exclude the removable settings app from the registry, demonstrating the "core uninstallable" build-time-exclusion path: the shell still builds and runs, with settings simply absent and the settings navigation leg skipped.

Note

Compile-time only; no run-time cost.

Since

0.1.0

Definition at line 180 of file main.c.

Enumeration Type Documentation

app_shell_const_t

enum app_shell_const_t : uint16_t

Capacities, the launcher tile index, and the chrome button id.

Since

0.1.0

Enumerator
k_app_reg_cap	Registry storage slots (library/reader/settings).
k_app_nav_cap	Back-stack depth (history of focused apps).
k_app_idx_library	Registry index of library (first registered).
k_app_btn_back	Button id a chrome routes to mean "go back".

Definition at line 199 of file main.c.

app_shell_hil_t

enum app_shell_hil_t : uint32_t

VCOM-console line rate for the deterministic HIL success banner.

The EK-RA8D2 J-Link OB VCOM bridge (SCI8, PD02/PD03) runs 8N1 at this rate; the Pi HIL rig's uart_scrape reads /dev/ttyACM0 to gate the app. The banner is additive to the existing ra8_log ITM trace.

Since

0.1.0

Enumerator
k_app_shell_hil_baud	VCOM console line rate (8N1).

Definition at line 89 of file main.c.

app_shell_id_t

enum app_shell_id_t : uint16_t

Registered app ids (launch keys).

Since

0.1.0

Enumerator
k_app_id_library	Core file/book organizer (non-removable).
k_app_id_reader	Core EPUB-reader app (non-removable).
k_app_id_settings	Optional settings app (removable).

Definition at line 188 of file main.c.

Function Documentation

app_shell_add()

bool app_shell_add ( ra8_app_t * app, app_shell_ctx_t * ctx, uint16_t id, const char * name, bool removable )

static

Build one app instance from the shared vtable and register it.

Fills app with the shared k_app_stub_vt, the supplied ctx / id / name / removable flag, and registers it into s_reg (which runs its init). Factored out so app_shell_register stays short.

Parameters

[out]	app	App instance storage to populate (non-NULL).
[in,out]	ctx	Per-app stub state the vtable keys off (non-NULL).
[in]	id	Unique launch id.
[in]	name	Display name + log tag (non-NULL, static lifetime).
[in]	removable	Optional/uninstallable flag (false = core).

Returns

true if ra8_app_register returned k_ra8_ok.

Return values

true	Registered + initialised.
false	Registration failed (duplicate id, full, or init error).

Precondition

s_reg is initialised.

app, ctx, and name are non-NULL.

Postcondition

On true s_reg holds app and its init ran once.

On false s_reg is unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 495 of file main.c.

References k_app_stub_vt, k_ra8_ok, app_shell_ctx_t::name, ra8_app_register(), and s_reg.

Referenced by app_shell_register().

app_shell_back_to_root()

bool app_shell_back_to_root ( void )

static

Press "back" to the root: pop to library and confirm the empty trail.

ra8_app_nav_back pops the last remembered app (library): the foreground app leaves, library.on_enter fires (its second enter), and the back-stack empties (depth 0). Works in both builds: the foreground app is reader (no settings) or reader again after the settings round-trip.

Returns

true if library re-entered with an empty back-stack.

Return values

true	library.enters == 2, the app was popped, and depth == 0.
false	The nav call failed, nothing popped, or a counter mismatched.

Precondition

library is the only app remaining on the back-stack (depth 1).

The previous navigation legs all succeeded (caller short-circuits else).

Postcondition

On true, library is foreground and the trail is empty.

On false, the self-check aborts and main parks.

Note

Not thread-safe.

Since

0.1.0

Definition at line 755 of file main.c.

References k_ra8_ok, ra8_app_nav_back(), ra8_app_nav_depth(), s_library_ctx, and s_nav.

Referenced by app_shell_selfcheck().

app_shell_banner()

void app_shell_banner ( void )

static

Emit the PASS banner: app count, library enters, and the PASS line.

The app count is two in both builds, but for different reasons: without settings only library + reader ever register (build-time exclusion); with settings all three register and the run-time uninstall leg then unmounts settings, leaving the same two. The library-enter count proves the back-stack returned focus to the root.

Precondition

The self-check passed.

ra8_log_init has run (otherwise the lines are dropped).

Postcondition

Three [app_shell] INFO: ... lines are emitted (or dropped).

No app/registry state is modified.

Note

Not thread-safe.

Since

0.1.0

Definition at line 904 of file main.c.

References app_shell_hil_emit_pass(), ra8_app_count(), ra8_log_info, ra8_log_info_val, s_library_ctx, and s_reg.

Referenced by main().

app_shell_hil_console_init()

bool app_shell_hil_console_init ( void )

static

Bring up the SCI8 / J-Link OB VCOM console for the HIL success banner.

Configures the clock tree (ra8_cgc_init, which publishes the PCLKA the SCI8 BRR divisor is computed from) then the EK-RA8D2 debug console (ra8_board_uart_console_init, SCI8 on PD02/PD03 at k_app_shell_hil_baud). Best-effort: a failure only means the additive HIL banner cannot reach the host; the existing ra8_log ITM trace and the demo logic are unaffected.

Returns

Whether the VCOM console is ready to carry the banner.

Return values

true	Clock + SCI8 console are up.
false	A bring-up step failed (the banner is then silently skipped).

Precondition

Called once during bring-up, before the success banner is emitted.

ra8_log_init has run (failures are narrated over ITM).

Postcondition

On true, SCI8 is enabled (TE/RE) and PD02/PD03 route to it.

On false, no console state persists; the app continues normally.

Note

Not thread-safe; single-threaded init context.

Since

0.1.0

Definition at line 128 of file main.c.

References k_app_shell_hil_baud, k_ra8_ok, ra8_board_uart_console_init(), and ra8_cgc_init().

Referenced by main().

app_shell_hil_emit_pass()

void app_shell_hil_emit_pass ( void )

static

Emit the deterministic HIL success banner over the VCOM console.

Writes k_app_shell_pass_banner to the SCI8 / J-Link OB VCOM console and flushes it so the bytes clock out before the CPU parks in WFI. A no-op if the console never came up (the write returns k_ra8_err_not_initialized, ignored).

Returns

Nothing.

Precondition

Reached only on the verified success path (single, non-compound guard).

app_shell_hil_console_init was attempted during bring-up.

Postcondition

The banner has been handed to SCI8 and the TX FIFO drained (if up).

No registry / app state is modified.

Note

Not thread-safe; single-threaded init context.

Since

0.1.0

Definition at line 157 of file main.c.

References k_app_shell_pass_banner, ra8_board_uart_console_flush(), and ra8_board_uart_console_write().

Referenced by app_shell_banner().

app_shell_launch_library()

bool app_shell_launch_library ( void )

static

Launcher: list the apps then launch library by its registry index.

Shows the menu, then launches the app at k_app_idx_library through ra8_app_nav_go_index – the by-position launcher bridge. The first launch has no prior focus, so it pushes nothing: the back-stack stays empty and only library.on_enter fires. The chrome then renders the foreground app once.

Returns

true if library entered exactly once with an empty back-stack.

Return values

true	enters == 1 and depth == 0 after the launch + render.
false	Any launcher/nav/render call failed or a counter mismatched.

Precondition

app_shell_register succeeded.

No app has been launched yet (counters are zero).

Postcondition

On true, library is foreground and rendered once.

On false, the self-check aborts and main parks.

Note

Not thread-safe.

Since

0.1.0

Definition at line 602 of file main.c.

References app_shell_log_menu(), k_app_idx_library, k_ra8_ok, ra8_app_nav_depth(), ra8_app_nav_go_index(), ra8_app_render(), s_library_ctx, s_nav, and s_reg.

Referenced by app_shell_selfcheck().

app_shell_log_menu()

void app_shell_log_menu ( void )

static

Log the launcher "menu": every registered app, its id, and its class.

Enumerates the registry the way a home screen would (ra8_app_count + ra8_app_at) and logs each app as [name] INFO: core|removable=<id>. This is the launcher's list view (text stand-in for the on-screen tiles). The loop is bounded by the registry capacity (k_app_reg_cap), so it is statically provable (NASA Rule 2).

Precondition

app_shell_register succeeded.

ra8_log_init has run (otherwise the lines are dropped).

Postcondition

One menu line is emitted per registered app (or all dropped if no ITM).

No app/registry state is modified.

Note

Not thread-safe.

Since

0.1.0

Definition at line 566 of file main.c.

References k_app_reg_cap, k_ra8_ok, ra8_app_at(), ra8_app_count(), ra8_log_info_val, RA8_LOOP_BOUND, and s_reg.

Referenced by app_shell_launch_library().

app_shell_open_reader()

bool app_shell_open_reader ( void )

static

Open reader from library, then route a back-button event to it.

ra8_app_nav_go(reader) fires library.on_leave then reader.on_enter and pushes library (depth 1); the chrome renders the new foreground app. Then a back-button event is routed through ra8_app_route_input to prove the event leg of the vtable: reader.on_input counts and consumes it (focus unchanged).

Returns

true if the open + render + input round-trip matched the expected counts and depth.

Return values

true	library.leaves == 1, reader.enters == 1, reader.inputs == 1, the event was handled, and depth == 1.
false	Any nav/render/route call failed or a counter mismatched.

Precondition

app_shell_launch_library succeeded (library foreground, depth 0).

reader and library are both registered (always true: core apps).

Postcondition

On true, reader is foreground with library on the back-stack.

On false, the self-check aborts and main parks.

Note

Not thread-safe.

Since

0.1.0

Definition at line 644 of file main.c.

References k_app_btn_back, k_app_id_reader, k_ra8_ok, k_ra8_widget_ev_button, ra8_app_nav_depth(), ra8_app_nav_go(), ra8_app_render(), ra8_app_route_input(), s_library_ctx, s_nav, s_reader_ctx, and s_reg.

Referenced by app_shell_selfcheck().

app_shell_register()

bool app_shell_register ( void )

static

Initialise the registry + back-stack and register every app.

Binds s_reg and s_nav to their caller-owned storage, then registers the core library and reader apps (non-removable) and – when APP_SHELL_SETTINGS is on – the optional settings app (removable). Any failure short-circuits to a false return so main can log and park.

Returns

true if the registry, back-stack, and all apps initialised.

Return values

true	Every ra8_app_*_init / ra8_app_register returned k_ra8_ok.
false	Some init/register step failed.

Precondition

Called once from main before any launch.

The static app/ctx storage is zero-initialised (C startup).

Postcondition

On true, s_reg holds the shipped apps and s_nav is empty.

On false, s_reg may be partially populated (the caller parks).

Note

Not thread-safe (single-threaded init context).

Since

0.1.0

Definition at line 523 of file main.c.

References app_shell_add(), k_app_id_library, k_app_id_reader, k_app_id_settings, k_app_nav_cap, k_app_reg_cap, k_ra8_ok, ra8_app_nav_init(), ra8_app_registry_init(), s_library_app, s_library_ctx, s_nav, s_nav_stack, s_reader_app, s_reader_ctx, s_reg, s_settings_app, s_settings_ctx, and s_slots.

Referenced by main().

app_shell_selfcheck()

bool app_shell_selfcheck ( void )

static

Run the whole deterministic launcher + navigate + back-stack surface.

Composes app_shell_launch_library, app_shell_open_reader, the optional app_shell_settings_round_trip (only when settings ships), app_shell_back_to_root, the optional app_shell_uninstall_demo (the run-time core-uninstallable rule, only when settings ships), and a final check that library is the active app.

Returns

true if every step held.

Return values

true	All sub-checks passed and library is active.
false	Some sub-check failed.

Precondition

app_shell_register succeeded.

Called once, before the idle loop.

Postcondition

On true, library is the foreground app.

On false, main logs a failure and parks.

Note

Not thread-safe.

Since

0.1.0

Definition at line 855 of file main.c.

References app_shell_back_to_root(), app_shell_launch_library(), app_shell_open_reader(), app_shell_settings_round_trip(), app_shell_uninstall_demo(), k_app_id_library, k_ra8_ok, ra8_app_active(), and s_reg.

Referenced by main().

app_shell_settings_round_trip()

bool app_shell_settings_round_trip ( void )

static

Open settings from reader, then go "back" to reader.

ra8_app_nav_go(settings) fires reader.on_leave then settings.on_enter and pushes reader (depth 2); the chrome renders it. ra8_app_nav_back pops it: settings.on_leave then reader.on_enter (reader's second enter), depth back to 1.

Returns

true if the open + back round-trip matched the expected counts.

Return values

true	Lifecycle counts, the popped flag, and depth all matched.
false	Any nav/render call failed or a counter / depth mismatched.

Precondition

app_shell_open_reader succeeded (reader foreground, depth 1).

APP_SHELL_SETTINGS is enabled (the settings app is registered).

Postcondition

On true, reader is foreground again with library still on the stack.

On false, the self-check aborts and main parks.

Note

Not thread-safe.

Since

0.1.0

Definition at line 699 of file main.c.

References k_app_id_settings, k_ra8_ok, ra8_app_nav_back(), ra8_app_nav_depth(), ra8_app_nav_go(), ra8_app_render(), s_nav, s_reader_ctx, s_reg, and s_settings_ctx.

Referenced by app_shell_selfcheck().

app_shell_uninstall_demo()

bool app_shell_uninstall_demo ( void )

static

Exercise the run-time "core uninstallable" rule: refuse core, unmount one.

With library foreground and settings registered-but-background, asks the framework to uninstall the core library app – refused with k_ra8_err_not_supported, nothing torn down – and then the removable settings app, which unmounts: its deinit fires once, it leaves the registry (count drops to two), and ra8_app_state reports it as unmounted. library stays foreground (its slot precedes the removed one, so its active index is untouched).

Returns

true if the core uninstall was refused and settings unmounted cleanly.

Return values

true	Core refused, settings deinit fired once, count == 2, settings reports unmounted.
false	Any uninstall returned an unexpected code or a count/state mismatched.

Precondition

app_shell_back_to_root succeeded (library foreground, depth 0).

APP_SHELL_SETTINGS is enabled (the settings app is registered).

Postcondition

On true, only library + reader remain registered and library is still the foreground app.

On false, the self-check aborts and main parks.

Note

Not thread-safe.

Since

0.1.0

Definition at line 802 of file main.c.

References k_app_id_library, k_app_id_settings, k_ra8_app_state_foreground, k_ra8_app_state_unmounted, k_ra8_err_not_supported, k_ra8_ok, ra8_app_count(), ra8_app_state(), ra8_app_uninstall(), s_library_ctx, s_reg, and s_settings_ctx.

Referenced by app_shell_selfcheck().

app_stub_deinit()

void app_stub_deinit ( ra8_app_t * a )

static

Stub deinit: count the teardown and log it (wired, not yet fired).

Parameters

[in,out]

a

The app being torn down (non-NULL, ctx is app_shell_ctx_t).

Precondition

a and a->ctx are non-NULL.

ra8_log_init has run (otherwise the log line is dropped).

Postcondition

The app's deinits counter advanced by one.

One [name] INFO: deinit line is emitted (or dropped).

Note

Not thread-safe. The framework has no unregister trigger yet, so this is present for contract completeness but not invoked this increment.

Since

0.1.0

Definition at line 437 of file main.c.

References app_shell_ctx_t::deinits, app_shell_ctx_t::name, and ra8_log_info.

app_stub_init()

ra8_err_t app_stub_init ( ra8_app_t * a )

static

Stub init: count the one-time setup and log it (runs at register).

Parameters

[in,out]

a

The app being registered (non-NULL, ctx is app_shell_ctx_t).

Returns

k_ra8_ok always (the stub never fails init).

Return values

k_ra8_ok

Setup recorded.

Precondition

a and a->ctx are non-NULL.

ra8_log_init has run.

Postcondition

The app's inits counter advanced by one.

One [name] INFO: init line is emitted (or dropped if no ITM).

Note

Not thread-safe; called from ra8_app_register.

Since

0.1.0

Definition at line 338 of file main.c.

References app_shell_ctx_t::inits, k_ra8_ok, app_shell_ctx_t::name, and ra8_log_info.

app_stub_on_enter()

void app_stub_on_enter ( ra8_app_t * a )

static

Stub on_enter: count the focus gain and log it.

Parameters

[in,out]

a

The app gaining focus (non-NULL, ctx is app_shell_ctx_t).

Precondition

a and a->ctx are non-NULL.

ra8_log_init has run (otherwise the log line is dropped).

Postcondition

The app's enters counter advanced by one.

One [name] INFO: on_enter line is emitted (or dropped).

Note

Not thread-safe; called from the foreground switch path.

Since

0.1.0

Definition at line 356 of file main.c.

References app_shell_ctx_t::enters, app_shell_ctx_t::name, and ra8_log_info.

app_stub_on_input()

bool app_stub_on_input ( ra8_app_t * a, const ra8_widget_event_t * ev )

static

Stub on_input: count the event, consume only the "back" button.

Parameters

[in,out]	a	The foreground app (non-NULL, ctx is app_shell_ctx_t).
[in]	ev	The input event (non-NULL).

Returns

true if the event was the back button (consumed), false otherwise.

Return values

true	ev is a k_app_btn_back button press.
false	Any other event (the chrome keeps routing it).

Precondition

a, a->ctx, and ev are non-NULL.

ra8_log_init has run (otherwise the log line is dropped).

Postcondition

The app's inputs counter advanced by one.

On a back press one [name] INFO: back requested line is emitted.

Note

Not thread-safe.

Since

0.1.0

Definition at line 412 of file main.c.

References ra8_widget_event_t::button_id, app_shell_ctx_t::inputs, k_app_btn_back, k_ra8_widget_ev_button, ra8_widget_event_t::kind, app_shell_ctx_t::name, and ra8_log_info.

app_stub_on_leave()

void app_stub_on_leave ( ra8_app_t * a )

static

Stub on_leave: count the focus loss and log it.

Parameters

[in,out]

a

The app losing focus (non-NULL, ctx is app_shell_ctx_t).

Precondition

a and a->ctx are non-NULL.

ra8_log_init has run (otherwise the log line is dropped).

Postcondition

The app's leaves counter advanced by one.

One [name] INFO: on_leave line is emitted (or dropped).

Note

Not thread-safe.

Since

0.1.0

Definition at line 373 of file main.c.

References app_shell_ctx_t::leaves, app_shell_ctx_t::name, and ra8_log_info.

app_stub_render()

void app_stub_render ( const ra8_app_t * a )

static

Stub render: count the frame and log it (stands in for drawing).

Parameters

[in]

a

The foreground app (non-NULL, ctx is app_shell_ctx_t).

Precondition

a and a->ctx are non-NULL.

ra8_log_init has run (otherwise the log line is dropped).

Postcondition

The app's renders counter advanced by one.

One [name] INFO: render line is emitted (or dropped).

Note

Not thread-safe; the real on-target draw (an ra8_widget tree) lives here in a later increment.

Since

0.1.0

Definition at line 391 of file main.c.

References app_shell_ctx_t::name, ra8_log_info, and app_shell_ctx_t::renders.

main()

void main

(

void

)

App entry: register the apps, run the launcher self-check, emit PASS.

The application entry point Reset_Handler hands control to.

Precondition

Reset_Handler copied .data and zeroed .bss.

SystemInit set VTOR / FPU / priority grouping.

Postcondition

On success the PASS banner is emitted; otherwise a FAIL line is.

The CPU parks in WFI (observable on ra8_emulator until its budget).

Since

0.1.0

Definition at line 925 of file main.c.

References app_shell_banner(), app_shell_hil_console_init(), app_shell_register(), app_shell_selfcheck(), ra8_log_info, and ra8_log_init().

Variable Documentation

k_app_shell_pass_banner

const uint8_t k_app_shell_pass_banner[] = "app_shell_demo: demo PASS\r\n"

static

Deterministic, run-to-run-stable HIL success banner (uart_scrape gate).

Emitted over the SCI8 / J-Link OB VCOM console only on the success path, AFTER the launcher + navigation self-check passes. The ITM ra8_log verdict is left intact; this is purely additive so the Pi rig (which has no SWO / ITM capture) can gate the app.

Note

Trailing CRLF terminates the line on the wire; the gate matches the text.

Warning

Do not modify; the HIL gate (hil.conf HIL_EXPECT) matches it exactly.

Since

0.1.0

Definition at line 104 of file main.c.

Referenced by app_shell_hil_emit_pass().

k_app_stub_vt

const ra8_app_vtable_t k_app_stub_vt

static

Initial value:

                                            = {
  .init     = app_stub_init,
  .on_enter = app_stub_on_enter,
  .tick     = nullptr,
  .render   = app_stub_render,
  .on_input = app_stub_on_input,
  .on_leave = app_stub_on_leave,
  .deinit   = app_stub_deinit,
}

Shared lifecycle vtable for every stub app (behaviour keyed off ctx).

Every callback except tick is wired (init / on_enter / render / on_input / on_leave / deinit); tick stays NULL to prove the framework tolerates a partial vtable.

Note

Read-only; lives in .rodata.

Since

0.1.0

Definition at line 453 of file main.c.

s_library_app

ra8_app_t s_library_app

static

The core library app instance (registered into s_reg).

Note

Built in app_shell_register.

Warning

Must outlive the registry (static storage).

Since

0.1.0

Definition at line 281 of file main.c.

Referenced by app_shell_register().

s_library_ctx

app_shell_ctx_t s_library_ctx = {.name = "library"}

static

Stub state for the core library app.

Note

Read/written by the library app's vtable callbacks only.

Warning

Counters are asserted by the self-check; do not reset elsewhere.

Since

0.1.0

Definition at line 272 of file main.c.

Referenced by app_shell_back_to_root(), app_shell_banner(), app_shell_launch_library(), app_shell_open_reader(), app_shell_register(), and app_shell_uninstall_demo().

s_nav

ra8_app_nav_t s_nav

static

Navigation back-stack layered over s_reg.

Note

Mutated only from main.

Warning

Drives s_reg; keep their lifetimes together.

Since

0.1.0

Definition at line 263 of file main.c.

s_nav_stack

uint16_t s_nav_stack[k_app_nav_cap]

static

Caller-owned storage backing the navigation back-stack (app ids).

Note

Bound to s_nav by ra8_app_nav_init.

Warning

Sized to k_app_nav_cap.

Since

0.1.0

Definition at line 254 of file main.c.

s_reader_app

ra8_app_t s_reader_app

static

The core reader app instance (registered into s_reg).

Note

Built in app_shell_register.

Warning

Must outlive the registry (static storage).

Since

0.1.0

Definition at line 299 of file main.c.

s_reader_ctx

app_shell_ctx_t s_reader_ctx = {.name = "reader"}

static

Stub state for the core reader app.

Note

Read/written by the reader app's vtable callbacks only.

Warning

Counters are asserted by the self-check; do not reset elsewhere.

Since

0.1.0

Definition at line 290 of file main.c.

s_reg

ra8_app_registry_t s_reg

static

The app registry (single active app + membership table).

Note

Mutated only from main (single-threaded init context).

Warning

Do not access from interrupt context.

Since

0.1.0

Definition at line 236 of file main.c.

s_settings_app

ra8_app_t s_settings_app

static

The optional settings app instance (registered into s_reg).

Note

Compiled only when APP_SHELL_SETTINGS is enabled.

Warning

Must outlive the registry (static storage).

Since

0.1.0

Definition at line 318 of file main.c.

s_settings_ctx

app_shell_ctx_t s_settings_ctx = {.name = "settings"}

static

Stub state for the optional settings app.

Note

Compiled only when APP_SHELL_SETTINGS is enabled.

Warning

Counters are asserted by the self-check.

Since

0.1.0

Definition at line 309 of file main.c.

s_slots

ra8_app_t* s_slots[k_app_reg_cap]

static

Caller-owned storage backing the registry's app-pointer table.

Note

Bound to s_reg by ra8_app_registry_init.

Warning

Sized to k_app_reg_cap; never indexed past s_reg.count.

Since

0.1.0

Definition at line 245 of file main.c.