Unload and staged models

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: the request is serviced in the inference task and REFUSED unless the engine is idle, because a parallel set dequeues every member on every pass. The two counters below are how a caller learns which happened.

Contract

An asynchronous request, not a command. It is serviced at the top of the inference pass (ai_engine.c:1401-1416) and refused unless the engine is idle — both s_current < 0 and s_active < 0, i.e. the stop must have been observed by the inference task, not merely requested. 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()). Why it matters: a DEEPCRAFT finalize() frees the model but leaves its handle dangling and enqueue() keeps returning success — clearing s_model_ready[idx] is what forces the next select down the cold-init path "instead of feeding a corpse" (ai_engine.c:1255-1260).

Variant

mtb-mpy and mtb-only

Origin

Lifted from deepcraft_task.c:691-695 (compiled into the prebuilt archive; not shipped as source).

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

Origin

Lifted from deepcraft_task.c:377 (compiled into the prebuilt archive; not shipped as source).

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

Origin

Lifted from deepcraft_task.c:378 (compiled into the prebuilt archive; not shipped as source).

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, and registration takes a critical section (deepcraft_task.c:700-711); 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. Validation-before-trust happens at ai_model_staged.c:452-470; 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

Origin

Lifted from deepcraft_task.c:712-714 (compiled into the prebuilt archive; not shipped as source).

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 (answered in the IPC callback, so it still arrives when ai_task is wedged).

Variant

mtb-mpy and mtb-only

Origin

Lifted from deepcraft_task.c:380 (compiled into the prebuilt archive; not shipped as source).

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

Origin

Lifted from deepcraft_task.c:381 (compiled into the prebuilt archive; not shipped as source).

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

Origin

Lifted from deepcraft_task.c:382 (compiled into the prebuilt archive; not shipped as source).

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 the IPC callback, which is where the shipped Q_DIAG answer reads it. 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

Origin

Lifted from deepcraft_task.c:379 (compiled into the prebuilt archive; not shipped as source).