Docs / Configuration / Kconfig reference
Kconfig referencev0.5.0
SynapticOS is configured entirely through Kconfig. All symbols live under the SYNAPTIC menuconfig in the module's top-level Kconfig file, and every one of them can be overridden per application in prj.conf or a board overlay.
Enabling SynapticOS
CONFIG_SYNAPTIC is the master switch. It depends on SOC_SERIES_MCXNX4X (the MCX N94x family, including the FRDM-MCXN947) or BOARD_QEMU_CORTEX_M3 — on any other target the option is not visible. Everything else in this reference is only available once CONFIG_SYNAPTIC=y.
# Minimal SynapticOS application configuration CONFIG_SYNAPTIC=y CONFIG_SYNAPTIC_PROFILING=y CONFIG_SYNAPTIC_SHELL=y CONFIG_LOG=y CONFIG_SHELL=y
Symbol reference
All 25 symbols from the v0.5.0 Kconfig (SYNAPTIC_MPU_PROTECT added in Phase 3; SYNAPTIC_MODEL_STORE and SYNAPTIC_STORE_AUTO_INIT added in Phase 4; the layer-execution, health, and coverage symbols added in Phase 5). Sizes are in bytes; ranges are enforced by Kconfig, so an out-of-range value fails at configure time rather than at runtime.
| Symbol | Type | Default | Range | Description |
|---|---|---|---|---|
SYNAPTIC | bool | n | — | Enable the SynapticOS AI-native runtime: inference scheduling, tensor memory management, and NPU orchestration. Depends on SOC_SERIES_MCXNX4X or BOARD_QEMU_CORTEX_M3. |
SYNAPTIC_TENSOR_ARENA_SIZE | int | 131072 | 4096 – 524288 | Size of the SRAM region dedicated to tensor allocations. Default 128 KB; adjust to your models' requirements. |
SYNAPTIC_SCRATCH_POOL_SIZE | int | 16384 | 1024 – 65536 | Size of the reusable scratch buffer pool for per-layer intermediate computations. |
SYNAPTIC_MAX_MODELS | int | 4 | 1 – 16 | Maximum number of models that can be registered in the model registry simultaneously. |
SYNAPTIC_MAX_CONCURRENT_JOBS | int | 2 | 1 – 4 | Maximum number of inference jobs that can be queued or running concurrently. |
SYNAPTIC_MAX_PIPELINE_STAGES | int | 8 | 4 – 16 | Maximum number of stages (preprocess + model + postprocess) in a single inference pipeline. |
SYNAPTIC_LAYER_EXEC | bool | y | — | New in Phase 5: execute models in the synthetic layered format (magic SYNL/SYND) one layer at a time, letting the scheduler preempt a preemptible job at a layer boundary when a higher-priority job arrives and resume it later from saved context. Costs a live context, a scratch buffer, and two suspension slots. |
SYNAPTIC_LAYER_ACT_MAX | int | 1024 | 64 – 4096 | New in Phase 5: largest single activation (layer output) a layered model may produce. Depends on SYNAPTIC_LAYER_EXEC. |
SYNAPTIC_LAYER_PLAN_MAX | int | 2048 | 128 – 16384 | New in Phase 5: size of the shared activation plan area all live activations of a layered model are placed into (memory-optimal placement). Must hold the planned peak of the deepest model in use; sessions whose planned peak exceeds it are rejected at begin. Also sets the size of each suspension slot. Depends on SYNAPTIC_LAYER_EXEC. |
SYNAPTIC_HEALTH | bool | y | — | New in Phase 5: the health monitor — registered software sources must check in within their period while busy; a 100 ms monitor thread feeds the hardware watchdog (with CONFIG_WATCHDOG and a watchdog0 alias) only while all sources are fresh, reports stale sources through a fault callback otherwise, and on dual-core CPU0 builds recovers a hung CPU1 by parking and re-releasing it. |
SYNAPTIC_WATCHDOG_TIMEOUT_MS | int | 2000 | 500 – 60000 | New in Phase 5: reset fires this long after the health monitor last considered every source fresh. Must comfortably exceed the health tick (100 ms) plus the longest legitimate scheduling gap. Depends on SYNAPTIC_HEALTH and WATCHDOG. |
SYNAPTIC_CPU1_HANG_MS | int | 500 | 200 – 10000 | New in Phase 5: CPU1 heartbeat loss threshold — a stall longer than this while linked triggers park + re-release recovery (600 ms detect + 1.3 ms re-release measured on the board). Depends on SYNAPTIC_HEALTH and SYNAPTIC_DUAL_CORE. |
SYNAPTIC_POWERQUAD | bool | y | — | Route FFT and Q15 matrix operations through the PowerQuad coprocessor. Init runs known-answer self-calibration and falls back to the software kernels per-operation if it fails. Depends on SOC_SERIES_MCXNX4X. |
SYNAPTIC_PROFILING | bool | y if DEBUG | — | Per-inference profiling of execution time, memory usage, and NPU utilization. Zero overhead when disabled. |
SYNAPTIC_MODEL_STORE | bool | y (not on CPU1) | — | New in Phase 4: persist the model registry across reboots — two ping-pong registry copies (generation + CRC32, newest valid wins) plus A/B model slots, all accessed through a narrow flash port. On the FRDM-MCXN947 the store lives in the bank 1 tail above the CPU1 image reserve; on QEMU a RAM-backed port emulates the flash so the logic is fully unit-testable. |
SYNAPTIC_STORE_AUTO_INIT | bool | y | — | New in Phase 4: on boards with the MCX ROM-API flash HAL, bring the model store up over the generated partition map before main() so persistent models reappear without application code. Runs before CPU1 release; a failure only disables persistence. Depends on SYNAPTIC_MODEL_STORE. |
SYNAPTIC_OTA | bool | y | — | Over-the-air model update support using dual-bank flash with A/B slot management. Implemented in Phase 4. Depends on SYNAPTIC_MODEL_STORE. |
SYNAPTIC_DUAL_CORE | bool | y | — | Asymmetric dual-core operation: CPU0 runs the AI runtime, CPU1 runs the application. Depends on SECOND_CORE_MCUX. |
SYNAPTIC_IPC_RING_SIZE | int | 16 | 4 – 64 | Number of entries in the inter-core IPC ring buffer. Depends on SYNAPTIC_DUAL_CORE. |
SYNAPTIC_SHARED_REGION_SIZE | int | 98304 | — | Size of the shared SRAM region for IPC and tensor exchange between CPU0 and CPU1. Default 96 KB. Depends on SYNAPTIC_DUAL_CORE. |
SYNAPTIC_MPU_PROTECT | bool | y | — | New in Phase 3: cross-core MPU protection — a runtime-programmed read-only guard over CPU1's RAM, a fault policy that logs violations and aborts only the offending thread, and the syn mpu test self-test. Write-only, one-directional protection (ARMv8-M cannot deny privileged reads with the background map on; CPU1 has no MPU). Depends on SYNAPTIC_DUAL_CORE and ARM_MPU. |
SYNAPTIC_SHELL | bool | y | — | Register the syn shell commands for model management, profiling, and runtime inspection. Depends on SHELL. |
SYNAPTIC_LOG_LEVEL | int | 3 | 0 – 4 | Log verbosity for all SynapticOS modules: 0=OFF, 1=ERR, 2=WRN, 3=INF, 4=DBG. |
SYNAPTIC_COVERAGE | bool | n | — | New in Phase 5: gcov-instrument the SynapticOS library only (selects FORCE_COVERAGE, COVERAGE, COVERAGE_DUMP) — tree-wide instrumentation overflows QEMU's 64 KB by a wide margin, so the build system blanks Zephyr's global coverage flags and instruments only the listed files. Lives outside the SYNAPTIC menu so the test apps can toggle it from overlay fragments. |
SYNAPTIC_COVERAGE_FILES | string | "*.c" | — | New in Phase 5: space-separated src/core file globs to instrument. Counter RAM scales with instrumented code, so each coverage app narrows this to the files its suites exercise; tools/syn_coverage.sh merges the runs with gcovr into one report (83.7% lines over the QEMU-buildable subset at v0.5.0). Depends on SYNAPTIC_COVERAGE. |
As of v0.5.0 every symbol configures an implemented subsystem: the dual-core symbols (SYNAPTIC_DUAL_CORE, SYNAPTIC_IPC_RING_SIZE, SYNAPTIC_SHARED_REGION_SIZE, SYNAPTIC_MPU_PROTECT) since Phase 3, the model-lifecycle symbols (SYNAPTIC_MODEL_STORE, SYNAPTIC_STORE_AUTO_INIT, SYNAPTIC_OTA) since Phase 4, and the layer-execution, health, and coverage symbols since Phase 5 — all board-verified on the FRDM-MCXN947. The NPU backend behind the HAL remains the deterministic stub until the Neutron SDK integration; the layered-model format the SYNAPTIC_LAYER_* symbols configure is the synthetic stub format.
Overriding defaults in prj.conf
Set any symbol in your application's prj.conf to override the default. Board-specific values go in a boards/<board>.conf overlay, which Zephyr merges automatically when that board is selected — this is how samples/hello_inference shrinks itself for QEMU:
# Reduce arena for QEMU's 64 KB RAM CONFIG_SYNAPTIC_TENSOR_ARENA_SIZE=8192 CONFIG_SYNAPTIC_SCRATCH_POOL_SIZE=2048 CONFIG_SHELL=n CONFIG_SYNAPTIC_SHELL=n
The qemu_cortex_m3 target has only 64 KB of RAM. The default 128 KB tensor arena will not fit — keep CONFIG_SYNAPTIC_TENSOR_ARENA_SIZE in the 4–8 KB range on QEMU (the unit tests use 4096, the sample overlay uses 8192).