Functions
void	ai_engine_unload (uint32_t idx)
	Asynchronous unload request — refused unless the engine is idle.
uint32_t	ai_engine_unload_done (void)
	Cumulative count of completed unloads; read as a pair with refused.
uint32_t	ai_engine_unload_refused (void)
	Cumulative count of refused unloads; read with ai_engine_unload_done().
int	ai_model_staged_load (uint32_t header_addr)
	Build and register a model CM33 staged in shared memory; task context only.
uint32_t	ai_model_staged_count (void)
	Models built this boot — the ack-by-observation signal for staged_load.
uint32_t	ai_model_staged_rejects (void)
	Loads refused this boot; pair with ai_model_staged_last_rc().
int32_t	ai_model_staged_last_rc (void)
	The loader's last return code (-1..-7, or the registry index on success).
uint32_t	ai_model_staged_heap_free (void)
	Free bytes on the CM55 heap; the one ISR-safe read on this topic.

Detailed Description

Eight functions: the asynchronous unload request and its two counters, and the run-time loader (ai_model_staged.h) with its four counters. Both halves share one design: no ack event — confirmation is by observation of a counter.

Variant: mtb-mpy and mtb-only

Function Documentation

◆ ai_engine_unload()

void ai_engine_unload ( uint32_t idx )

Asynchronous unload request — refused unless the engine is idle.

Release a run-time model and free what it owns. Asynchronous, and honoured only while the engine is idle: call ai_engine_stop() and wait for ai_engine_active() == -1 first, or the request is REFUSED. The two counters below are how a caller learns which happened.

Contract: An asynchronous request, not a command. It is refused unless the engine is idle — the stop must have been confirmed (ai_engine_active() == -1), not merely requested — and the model is loaded and has a finalize(). Poll ai_engine_unload_done() / ai_engine_unload_refused() to learn which happened (MicroPython: edge_ai.stop(), then edge_ai.unload(i), then read edge_ai.diag()). When an unload completes, the model's finalize() runs to release what it owns, and the next select of that model reloads it from scratch on the cold-init path.

Variant: mtb-mpy and mtb-only

◆ ai_engine_unload_done()

uint32_t ai_engine_unload_done ( void )

Cumulative count of completed unloads; read as a pair with refused.

Contract: Cumulative count of unload requests that completed. Read as a pair with ai_engine_unload_refused(): compare the delta of both against the values before the request. Any CM55 context.

Variant: mtb-mpy and mtb-only

◆ ai_engine_unload_refused()

uint32_t ai_engine_unload_refused ( void )

Cumulative count of refused unloads; read with ai_engine_unload_done().

Contract: Cumulative count of unload requests refused because the engine was not idle, the index was out of range, or the model was not ready. Ditto — read with ai_engine_unload_done().

Variant: mtb-mpy and mtb-only

◆ ai_model_staged_load()

int ai_model_staged_load ( uint32_t header_addr )

Build and register a model CM33 staged in shared memory; task context only.

Contract: Builds a model from the manifest CM33 staged in shared memory and registers it; returns the new registry index or a negative loader code (-1 bad manifest … -7 wrong frame width — the full table is in ai_model_staged.h). Task context only, never an ISR or IPC pipe callback: mtb_ml_model_init() mallocs from the same CM55 heap LVGL draws from; an IPC callback must queue the call. ai_engine_init() must precede it (the row needs a task to run on — the shipped idiom re-calls init immediately before). No ack event — confirmation is ai_model_staged_count() rising. The manifest is validated in full before anything in it is trusted (codes -1..-7); only IMU (window + quantize) models are loadable. AI_STAGED_MAX slots per boot, never reused. A -2 also covers a duplicate model name, so loading the same file twice looks exactly like hitting the ceiling.

Variant: mtb-mpy and mtb-only

◆ ai_model_staged_count()

uint32_t ai_model_staged_count ( void )

Models built this boot — the ack-by-observation signal for staged_load.

Contract: Models built this boot. The ack-by-observation signal for ai_model_staged_load(): snapshot before, poll after. Read off-core via Q_DIAG, which answers even while inference is stalled.

Variant: mtb-mpy and mtb-only

◆ ai_model_staged_rejects()

uint32_t ai_model_staged_rejects ( void )

Loads refused this boot; pair with ai_model_staged_last_rc().

Contract: Loads refused this boot. Pair with ai_model_staged_last_rc() to learn why the most recent one was refused; a refused load that looked like a completed one would make any staging measurement unreadable.

Variant: mtb-mpy and mtb-only

◆ ai_model_staged_last_rc()

int32_t ai_model_staged_last_rc ( void )

The loader's last return code (-1..-7, or the registry index on success).

Contract: The loader's last return code (the -1..-7 namespace above, or the registry index on success). Ditto — read with ai_model_staged_rejects(). Signature verdicts live in a different namespace (stage_info()['sig_rc']) and deliberately do not overlap.

Variant: mtb-mpy and mtb-only

◆ ai_model_staged_heap_free()

uint32_t ai_model_staged_heap_free ( void )

Free bytes on the CM55 heap; the one ISR-safe read on this topic.

Contract: Free bytes on the CM55 heap, including unclaimed sbrk headroom. ISR-safe read — the one function on this page that may be called from an IPC callback; edge_ai.diag() reports it as cm55_heap_free. A -3 from the loader with a large value here means the model's arena, not the heap, was the limit.

Variant: mtb-mpy and mtb-only

Functions