Firmware update

Functions
void	fw_hash_compute_at_boot (void)
	Compute and cache the SHA-256 identity digest (about 80 ms once); idempotent.
const char *	fw_hash_hex (void)
	The cached 64-char digest; always non-NULL — "unknown" before compute. Never free it.
void	fw_hash_prefix8 (char *out9)
	First 8 hex chars + NUL into out9 (at least 9 bytes). No caller anywhere.
void	fw_hash_get_diagnostics (fw_hash_diag_t *out)
	Fill a caller-owned hash-diagnostics snapshot for the _diag block of bento.fw.query.
void	bento_fw_handle_query (const char *json, const jsmntok_t *toks, int n_toks)
	Handler for bento.fw.query: cheap read-only metadata probe. Dispatcher-only.
void	bento_fw_handle_update_begin (const char *json, const jsmntok_t *toks, int n_toks)
	Handler for bento.fw.update.begin: launches the LCD Y/N prompt; ack deferred to the decision.
void	bento_fw_emit_boot_complete (void)
	Emit bento.fw.update.complete once per boot on the first CONNECTED transition.
void	bento_fw_on_user_decision (int approve)
	Deliver the CM55 LCD Y/N decision for the current prompt; no-op when none is pending.

Detailed Description

Eight functions: the firmware hash (fw_hash_*) and the update flow (bento_fw_*). Compiled only with ENABLE_PAGE_BENTO_BUDDY=1 (default 0, proj_cm33_ns/Makefile:64, :305); rebuild after make getlibs — Flag gate (read first).

Declarations: fw_hash.h, bento_fw.h (which forward-declares jsmntok_t itself and does not need vendor/jsmn.h). Implementation fw_hash.c / bento_fw.c is archived in libbento_secure.a. Every desktop-triggered flash passes an on-device LCD Y/N prompt showing the first 8 hex chars of the target SHA-256 — no bypass, no timeout-default-to-yes.

Variant

mtb-mpy and mtb-only

Function Documentation

fw_hash_compute_at_boot()

void fw_hash_compute_at_boot

(

void

)

Compute and cache the SHA-256 identity digest (about 80 ms once); idempotent.

Contract

Computes SHA-256 over a build-deterministic identity string and caches the hex digest (about 80 ms once). Idempotent — a second call is a no-op. Falls back to the sentinel "unknown" if mbedtls or the linker symbols are unavailable. In the shipped firmware it is called from the lazy BLE bring-up, not from main(). Template call sites: 0; archived call site ble_nus_lazy.c:193 (fw_hash_compute_at_boot(); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

fw_hash_hex()

const char * fw_hash_hex

(

void

)

The cached 64-char digest; always non-NULL — "unknown" before compute. Never free it.

Contract

Pointer to the cached 64-char lowercase digest + NUL; always non-NULL — "unknown" before fw_hash_compute_at_boot(). Never free it. Template call sites: 0; archived call sites bento_fw.c:217 and :378 (fw_hash_hex(), as a s argument in the query answer — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

fw_hash_prefix8()

void fw_hash_prefix8

(

char *

out9

)

First 8 hex chars + NUL into out9 (at least 9 bytes). No caller anywhere.

Contract

First 8 hex chars + NUL into out9, which must be at least 9 bytes (the parameter name is the contract). Before the digest is computed the prefix is that of "unknown". No caller anywhere.

Variant

mtb-mpy and mtb-only

Example (authored — no shipped call site)

__attribute__((used))
static void bento_ex_fw_hash_prefix8(void)
{
    fw_hash_compute_at_boot();         /* idempotent — cache the digest    */
 
    char prefix[9];                    /* contract: >= 9 bytes             */
    fw_hash_prefix8(prefix);
 
    /* prefix now holds e.g. "3fa9c21b" — show it on the physical-ack
     * prompt so the operator can match it against the desktop's hash. */
    (void)prefix;
}

fw_hash_get_diagnostics()

void fw_hash_get_diagnostics

(

fw_hash_diag_t *

out

)

Fill a caller-owned hash-diagnostics snapshot for the _diag block of bento.fw.query.

Contract

Fills a caller-owned snapshot, populated each time fw_hash_compute_at_boot() runs; surfaced in the _diag block of the bento.fw.query answer so the desktop can verify the digest is stable across boots. Template call sites: 0; archived call site bento_fw.c:188 (fw_hash_get_diagnostics(&hd); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

bento_fw_handle_query()

void bento_fw_handle_query	(	const char *	json,
		const jsmntok_t *	toks,
		int	n_toks )

Handler for bento.fw.query: cheap read-only metadata probe. Dispatcher-only.

Contract

Handler for bento.fw.query: cheap read-only metadata probe; emits the JSON ack (version, hash, _diag) on the NUS link. Dispatcher-only. Template call sites: 0; archived call site nus_commands.c:1844 (bento_fw_handle_query(json, toks, n_toks); return; — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

bento_fw_handle_update_begin()

void bento_fw_handle_update_begin	(	const char *	json,
		const jsmntok_t *	toks,
		int	n_toks )

Handler for bento.fw.update.begin: launches the LCD Y/N prompt; ack deferred to the decision.

Contract

Handler for bento.fw.update.begin: launches the LCD Y/N prompt and emits the final ack — approve gives ok:true with sensor streams stopped (sensor_stream_stop_all()); decline or timeout gives an error; a running stream answers busy. Duplicate prompts are rate-limited within 5 s. Dispatcher-only. Template call sites: 0; archived call site nus_commands.c:1847 (bento_fw_handle_update_begin(json, toks, n_toks); return; — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

bento_fw_emit_boot_complete()

void bento_fw_emit_boot_complete

(

void

)

Emit bento.fw.update.complete once per boot on the first CONNECTED transition.

Contract

Emits bento.fw.update.complete once per boot on the first post-boot CONNECTED transition; the desktop compares the hash with its cache to decide "update landed" versus "just a reboot" (bonds are RAM-only, so every reboot forces a re-pair). Idempotent within a boot. Template call sites: 0; archived call site ble_nus_lazy.c:92 (bento_fw_emit_boot_complete();, comment :89 "...is idempotent" — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

bento_fw_on_user_decision()

void bento_fw_on_user_decision

(

int

approve

)

Deliver the CM55 LCD Y/N decision for the current prompt; no-op when none is pending.

Contract

Called when the CM55 LCD returns the Y/N decision for the current prompt: non-zero = proceed, zero = decline. No-op when no prompt is pending. The ack to the desktop is deferred to this point (bento_fw.c:328). Template call sites: 0; archived call site ipc_bento_buddy_bridge.c:156 (bento_fw_on_user_decision(msg->value != 0 ? 1 : 0); — CM55 tap arriving over IPC; compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only