Docs / API reference / syn_model.h

syn_model.hv0.1.0

<synaptic/syn_model.h> manages the model lifecycle: an array-backed registry where each model is described by a syn_model_info_t and addressed by an opaque 1-based handle. The API covers registration and lookup (by handle or by name), loading and unloading through the NPU HAL, and an atomic-style hot-swap between two registered models. The surrounding concepts are described in Model lifecycle & OTA updates.

Types & constants

Name	Kind	Description
`syn_model_handle_t`	typedef	`uint32_t` — opaque model handle returned by the registry. Handles are 1-based slot indices.
`SYN_MODEL_INVALID`	define	`((syn_model_handle_t)0)` — the invalid-handle sentinel. Lookup functions write it to the output handle on failure.
`syn_model_info_t`	struct	Model descriptor. Fields: `char name[32]`, `char version[16]`, `uint32_t input_size`, `uint32_t output_size`, `uint32_t flash_offset`, `uint32_t flash_size`, `uint32_t sram_required`, `uint32_t crc32`, `syn_npu_dtype_t input_dtype`, `syn_npu_dtype_t output_dtype`, `uint8_t input_shape[4]`, `uint8_t output_shape[4]`.

Functions

Signature	Description
`int syn_model_register(const syn_model_info_t info, syn_model_handle_t handle)`	Registers a model and writes its new handle to `handle`. Returns 0 on success, `-EINVAL` on NULL arguments, `-EEXIST` if a model with the same name is already registered, `-ENOMEM` if all registry slots are in use. On error, `handle` is set to `SYN_MODEL_INVALID`.
`int syn_model_unregister(syn_model_handle_t handle)`	Removes a model from the registry, unloading it first if it is loaded. Returns 0 on success, `-EINVAL` for an invalid or inactive handle.
`int syn_model_get_info(syn_model_handle_t handle, syn_model_info_t *info)`	Copies the model's descriptor into `*info`. Returns 0 on success, `-EINVAL` for an invalid handle or NULL `info`.
`int syn_model_get_by_name(const char name, syn_model_handle_t handle)`	Looks up a registered model by name. Returns 0 and writes the handle on success, `-EINVAL` on NULL arguments, `-ENOENT` (with `*handle = SYN_MODEL_INVALID`) if no such model exists.
`int syn_model_list(syn_model_handle_t handles, uint8_t count, uint8_t max)`	Fills `handles` with up to `max` active handles and writes how many were stored to `*count`. Returns 0 on success, `-EINVAL` on NULL arguments.
`int syn_model_load(syn_model_handle_t handle)`	Marks the model loaded; if the registry holds model data for it, the data is first pushed to the NPU via `syn_hal_npu_load_model()`. Returns 0 on success, `-EINVAL` for an invalid handle, `-EALREADY` if already loaded, or a negative errno propagated from the NPU HAL.
`int syn_model_unload(syn_model_handle_t handle)`	Marks the model unloaded. Returns 0 on success, `-EINVAL` for an invalid handle, `-EALREADY` if it was not loaded.
`bool syn_model_is_loaded(syn_model_handle_t handle)`	Returns `true` if the handle refers to an active, loaded model; `false` otherwise (including for invalid handles).
`int syn_model_swap(syn_model_handle_t old_handle, syn_model_handle_t new_handle)`	Hot-swap: marks `old_handle` unloaded and `new_handle` loaded in one call. Returns 0 on success, `-EINVAL` if either handle is invalid or inactive.

Usage

From the hello_inference sample — describe a model, register it, push the binary to the NPU, and mark it loaded:

static const uint8_t model_bin[64] = {0};   /* model binary */

syn_model_info_t model_info = {0};

strncpy(model_info.name, "test_classify", sizeof(model_info.name));
strncpy(model_info.version, "1.0.0", sizeof(model_info.version));
model_info.input_size    = 16 * 16 * 3;
model_info.output_size   = 10;
model_info.flash_size    = sizeof(model_bin);
model_info.sram_required = 4096;
model_info.input_dtype   = SYN_NPU_DTYPE_INT8;
model_info.output_dtype  = SYN_NPU_DTYPE_INT8;

syn_model_handle_t handle;
int ret = syn_model_register(&model_info, &handle);
if (ret != 0) {
    return ret;   /* -EEXIST: duplicate name, -ENOMEM: registry full */
}

/* Push the binary to the NPU, then mark the model loaded */
ret = syn_hal_npu_load_model(model_bin, sizeof(model_bin));
if (ret != 0) {
    return ret;
}
syn_model_load(handle);

Notes

Implementation status: fully implemented in v0.1.0 (src/core/syn_model.c) — array-backed registry with duplicate-name detection and NPU HAL integration.
Capacity: the registry holds CONFIG_SYNAPTIC_MAX_MODELS models (default 8). See the Kconfig reference.
Handles: handle values are slot index + 1, so SYN_MODEL_INVALID (0) can never collide with a real handle. A handle stays valid until syn_model_unregister(); after that the slot may be reused by a later registration.
Names are keys: registration rejects duplicate names with -EEXIST, and syn_model_get_by_name() matches on the full name[32] field.
Swap semantics: in v0.1.0 syn_model_swap() flips the loaded flags in the registry; re-programming the NPU with the new model's weights is the caller's responsibility (or arrives staged through syn_model_ota.h).
Related: loaded models are executed through syn_infer.h or directly via syn_hal_npu.h; the syn model shell command lists the registry at runtime.

← Previoussyn_mem.h — tensor arena Next →syn_model_ota.h — OTA updates