[convert] command
The convert command emits a standalone C inference module—a set of portable .c/.h files implementing your model’s operators as optimized Ambiq-tuned kernels.
LiteRT scalar constants retain their rank-zero shape (), distinct from a
one-element vector (1,). Shape-building graphs that pack scalars into a reshape
target do not require a new conversion option to preserve those ranks. Unresolved
dynamic dimensions still follow the existing shape-validation behavior.
Usage
Usage: helia-aot convert [OPTIONS]
Convert a model to standalone C inference module.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ general ────────────────────────────────────────────────────────────────────────────────────────╮
│ --path PATH Path to yaml configuration │
│ --transforms [TEXT ...] Transforms configuration │
│ --operators [TEXT ...] Operator attributes │
│ --verbose INT Verbosity level (default: 1) │
│ --force --no-force Force conversion even if output exists (default: │
│ False) │
│ --log-file PATH Optional log file path │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ model ──────────────────────────────────────────────────────────────────────────────────────────╮
│ --model.path PATH Path to target model file (default: model.tflite) │
│ --model.subgraph INT Subgraph index (default: 0) │
│ --model.type TEXT Model type (e.g., tflite, litert) │
│ --model.name TEXT Model name (default: model) │
│ --model.description TEXT Description of the model │
│ --model.version TEXT Model version (default: v1.0.0) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ module ─────────────────────────────────────────────────────────────────────────────────────────╮
│ --module.path PATH Output path for the generated │
│ module. Use a directory for an │
│ unpacked module, a '.zip' suffix │
│ for a generic zip archive, or a │
│ '.pack' suffix for an │
│ Open-CMSIS-Pack archive (requires │
│ module.type=cmsis_pack). (default: │
│ output.zip) │
│ --module.type <neuralspot|zephyr|cmake|nsx|cmsis Module type (default: neuralspot) │
│ _pack> │
│ --module.name TEXT Module name (default: helia_aot_nn) │
│ --module.prefix TEXT Prefix added to sources for unique │
│ namespace (default: aot) │
│ --module.schedule <table|static> Operator dispatch shape in the │
│ generated model: 'table' (default) │
│ keeps the runtime function-pointer │
│ table and per-node callback seam; │
│ 'static' emits straight-line direct │
│ calls (no table, no loop, no │
│ indirect dispatch). (default: │
│ table) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ test ───────────────────────────────────────────────────────────────────────────────────────────╮
│ --test.enabled --no-test.enabled Include test case (default: │
│ False) │
│ --test.tolerance FLOAT Test tolerance (default: 1.0) │
│ --test.skip-verification --no-test.skip-verification Skip runtime output │
│ verification (default: False) │
│ --test.golden-data PATH Golden input/output npz file │
│ --test.num-iterations INT Number of times to run the │
│ same stimulus through the │
│ model (default: 1) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ memory ─────────────────────────────────────────────────────────────────────────────────────────╮
│ --memory.planner <greedy> Memory planner strategy │
│ (default: greedy) │
│ --memory.constraints [TEXT ...] Memory constraints │
│ (ordered by preference) │
│ --memory.tensors [TEXT ...] Tensor attributes │
│ --memory.allocate-arenas --no-memory.allocate-ar… If true, the module will │
│ use internal, statically │
│ allocated arenas. If │
│ false, the caller must │
│ bind every region via │
│ <prefix>_bind_arena() / │
│ <prefix>_bind_arenas() │
│ before model_init. │
│ (default: True) │
│ --memory.auto-hydrate-con… --no-memory.auto-hydrat… Deprecated — retained for │
│ backwards compatibility │
│ but no longer changes │
│ generated runtime │
│ behavior. model_init │
│ always invokes │
│ hydrate_constants between │
│ context_init and the │
│ operator init loop. │
│ Override the weak │
│ hydrate_constants symbol │
│ for custom hydration │
│ mechanisms (DMA / async │
│ pre-stage / model swap). │
│ (default: True) │
│ --memory.dump-residency-j… --no-memory.dump-reside… If true, write a │
│ machine-readable residency │
│ report │
│ (``<prefix>_residency.jso… │
│ alongside the emitted │
│ module. Mirrors the │
│ verbose log summary as │
│ JSON for tooling that │
│ needs to introspect arena │
│ layout, staged-vs-cold │
│ residency, and per-tensor │
│ placement post-planning. │
│ (default: False) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ platform ───────────────────────────────────────────────────────────────────────────────────────╮
│ --platform.name TEXT Target platform name (default: │
│ apollo510_evb) │
│ --platform.cpu TEXT CPU core type (e.g., cortex-m55) │
│ --platform.speeds [INT ...] List of supported clock speeds in MHz │
│ --platform.memories JSON Memory sizes in bytes │
│ --platform.capabilities [TEXT ...] List of SoC capabilities │
│ --platform.preferred-memory-order [TEXT ...] Preferred memory order for allocations │
│ --platform.min-alignment INT Minimum alignment requirement in bytes │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ documentation ──────────────────────────────────────────────────────────────────────────────────╮
│ --documentation.html --no-documentation.html Generate html documentation site │
│ (experimental). (default: False) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
Quick start:
helia-aot convert --model.path model.tflite --module.path ./out
helia-aot convert --path my-model.yaml --verbose 2
helia-aot convert --model.path model.tflite --module.type zephyr --test.enabled
Examples
Basic Conversion
Advanced Conversion
helia-aot convert \
--model.path ad01-int8.tflite \
--model.subgraph 0 \
--module.path ./out \
--module.name ad01-int8 \
--module.type zephyr \
--module.prefix ad01 \
--memory.planner greedy \
--test.enabled \
--verbose 1
Advanced Conversion with YAML
# Put the options in a YAML configuration
cat <<EOF > ad01-int8.yaml
model:
path: ad01-int8.tflite
subgraph: 0
module:
path: ./out
name: ad01-int8
type: zephyr
prefix: ad01
memory:
planner: greedy
test:
enabled: true
verbose: 1
EOF
# Run the conversion via yaml configuration
helia-aot convert --path ad01-int8.yaml --verbose 2
Available Arguments
The following arguments are available for the convert command. The default values are shown in the table below.
Note
These are top-level flags. For nested fields, use dotted notation to scope their local flags (e.g., --model.path, --module.type, --memory.planner).
ConvertArgs
| Flag | Type | Default | Description |
|---|---|---|---|
model |
ModelArgs | ModelArgs |
Model configuration. |
module |
ModuleArgs | ModuleArgs |
Module configuration. |
test |
TestArgs | TestArgs |
Test configuration. |
transforms |
list[TransformSpec] | [] |
Transforms configuration. |
memory |
MemoryArgs | MemoryArgs |
Memory configuration. |
platform |
PlatformArgs | PlatformArgs |
Target platform configuration. |
operators |
list[AttributeRuleset] | [] |
Operator attributes. |
documentation |
DocumentationArgs | DocumentationArgs |
Documentation configuration. |
verbose |
int (0–3) |
1 |
Verbosity level. |
force |
bool |
False |
Force conversion even if output exists. |
log_file |
Path |
None |
Optional log file path. |
ModelArgs
| Flag | Type | Default | Description |
|---|---|---|---|
path |
Path |
model.tflite |
Path to target model file. |
subgraph |
int |
0 |
Subgraph index. |
type |
str |
None |
Model type (e.g., tflite, litert). If not set, inferred by file extension. |
name |
str |
model |
Optional model name. |
description |
str |
None |
Optional description of the model. |
version |
str |
v1.0.0 |
Optional model version. |
ModuleArgs
| Flag | Type | Default | Description |
|---|---|---|---|
path |
Path |
output.zip |
Output path for the generated module. Use a directory for an unpacked module, a .zip suffix for a generic zip archive, or a .pack suffix for an Open-CMSIS-Pack archive (requires module.type=cmsis_pack). |
type |
ModuleType |
neuralspot |
Module type (e.g., neuralspot, zephyr, cmake, nsx, cmsis_pack). |
name |
str |
helia_aot_nn |
Module name (valid C identifier). |
prefix |
str |
aot |
Prefix added to sources for unique namespace (valid C identifier). |
schedule |
ScheduleMode |
table |
Operator dispatch shape: table keeps the runtime function-pointer table and per-node callback seam; static emits straight-line direct calls. |
TestArgs
| Flag | Type | Default | Description |
|---|---|---|---|
enabled |
bool |
False |
Include test case. |
tolerance |
float |
1.0 |
Test tolerance (integers are coerced). |
skip_verification |
bool |
False |
Skip runtime output verification. |
golden_data |
Path |
None |
Optional path to golden input/output npz file. |
num_iterations |
int |
1 |
Number of times to run the same stimulus through the model. |
MemoryArgs
| Flag | Type | Default | Description |
|---|---|---|---|
planner |
MemoryPlannerType |
greedy |
Memory planner strategy. |
constraints |
list[MemoryConstraint] |
None |
Memory constraints (ordered by preference). |
tensors |
list[AttributeRuleset] |
[] |
Tensor attributes. |
allocate_arenas |
bool |
True |
If true, the module declares its own arena buffers. If false, the caller must bind every region with <prefix>_bind_arena() / <prefix>_bind_arenas() before <prefix>_model_init; <prefix>_context_init returns non-zero when any region is unbound. |
auto_hydrate_constants |
bool |
True |
Deprecated — retained for backwards compatibility but no longer changes emitted runtime behavior. <prefix>_model_init always invokes <prefix>_hydrate_constants between <prefix>_context_init and the operator init loop, so kernels that read constants in their _init hook always observe hydrated arenas. Override the weak <prefix>_hydrate_constants symbol for DMA / async pre-stage / model-swap. |
dump_residency_json |
bool |
False |
If true, write a machine-readable residency report <prefix>_residency.json alongside the emitted module. Mirrors the --verbose 2 log summary as JSON for tooling that introspects arena layout, staged-vs-cold residency, and per-tensor placement. |
Tensor backing model
All tensors — scratch, persistent (resource-variable), and constant
(weight) — are backed by per-memory arenas in the generated C
module. There are no per-tensor static symbols. Each tensor
descriptor carries (region, offset, size) resolved at runtime
against ctx->arena_buffers[region].
Persistents zero-init via memset() in context_init (caller-
supplied arena bytes are not BSS-zeroed). Constants are cold
when their source memory equals their runtime memory (kernels read
in place); they are staged when those memories differ — a
contiguous source blob <prefix>_arena_const_<mem>__source[] lives
in cold storage and the writable runtime arena
<prefix>_arena_const_<mem> is hydrated by the caller before
model_run.
Routing is per-tensor via the constant_destination_memory:
attribute on tensor rules. See
Tensor attributes
for the full description, the hydration contract, and the
caller-supplied arena wiring example.
PlatformArgs
| Flag | Type | Default | Description |
|---|---|---|---|
name |
str |
apollo510_evb |
Target platform name. |
cpu |
str |
None |
CPU core type (e.g., cortex-m55). Optional for built-in platforms. |
speeds |
list[int] |
[] |
Supported clock speeds in MHz. |
memories |
dict[MemoryType, int] |
{} |
Memory sizes in bytes (JSON on the CLI). |
capabilities |
list[SocCapability] |
[] |
Available SoC capabilities (e.g., MVE, DSP). |
preferred_memory_order |
list[MemoryType] |
[] |
Placement preference for the memory planner. |
min_alignment |
int |
None |
Minimum alignment in bytes (positive power of two). |
Run helia-aot list-targets to see every supported target name, or
helia-aot target-info --name <target> for a target's memories and
capabilities. An unknown platform.name fails with an error listing all valid targets.
Targets that are not registered can still be used by supplying the remaining platform.*
fields (cpu, speeds, memories, preferred-memory-order, min-alignment), which
builds a custom platform for that conversion only. To make a custom platform available
process-wide (e.g., across repeated Python API conversions), register it explicitly with
helia_aot.platforms.register_platform.
DocumentationArgs
| Flag | Type | Default | Description |
|---|---|---|---|
html |
bool |
False |
Generate html documentation site (experimental). |
AttributeRuleset
Used in lists like
operators[]ormemory.tensors[].
| Flag | Type | Default | Description |
|---|---|---|---|
type |
str |
* |
Entity type (e.g., CONV_2D) or * for all. |
id |
str, list[str], None |
None |
Entity identifier(s). |
attributes |
dict[str, BasicType] |
{} |
Key-value map of entity attributes. |
TransformSpec
Used in lists like
transforms[].
| Flag | Type | Default | Description |
|---|---|---|---|
name |
str |
* |
Name of the transform (* matches all). |
enabled |
bool |
True |
Whether the transform is enabled. |
options |
dict[str, NestedType] |
{} |
Additional transform options. |