Docs / Concepts / Architecture overview

Architecture overviewv0.5.0

SynapticOS treats AI inference as the primary workload, not an afterthought. Where a traditional RTOS schedules threads and manages peripherals, SynapticOS elevates inference pipelines, tensor memory, and neural accelerators to first-class OS primitives — all layered on top of Zephyr RTOS v3.7.0.

Design philosophy

Five principles drive every subsystem:

• Inference-first scheduling. The fundamental scheduling unit is the inference job, not the thread. Threads still exist (inherited from Zephyr) but serve inference orchestration.
• Zero-copy tensor pipelines. Data flows from sensor → pre-processing → NPU → post-processing without unnecessary memory copies.
• Hardware-agnostic acceleration. A clean HAL abstracts the NPU, DSP, and DMA so models stay portable across silicon.
• Dual-core asymmetry by design. CPU0 owns the AI runtime; CPU1 owns the application. They communicate through shared memory and mailbox IPC.
• OTA-ready model lifecycle. Models are versioned, updatable, and swappable at runtime without reboot.

The layer stack

An application never touches accelerator registers directly. Calls descend through the syn_* API into core services, then through the HAL, and finally into Zephyr and the hardware:

┌───────────────────────────────────────────────────────────┐
│  APPLICATION          your code: sensors, comms, logic    │
├───────────────────────────────────────────────────────────┤
│  SYNAPTIC API (syn_*) syn_model_load() · syn_infer_submit()│
│                       syn_mem_tensor_alloc()               │
├───────────────────────────────────────────────────────────┤
│  CORE SERVICES        inference engine · memory manager    │
│                       model registry · OTA · profiler     │
├───────────────────────────────────────────────────────────┤
│  HAL (syn_hal_*)      NPU (Neutron) · DSP (PowerQuad)     │
│                       DMA (SmartDMA)                       │
├───────────────────────────────────────────────────────────┤
│  ZEPHYR RTOS v3.7.0   scheduler · IPC · drivers · shell   │
├───────────────────────────────────────────────────────────┤
│  MCXN947              2x Cortex-M33 · eIQ Neutron NPU     │
│                       PowerQuad · SmartDMA · 512 KB SRAM  │
└───────────────────────────────────────────────────────────┘

The HAL boundary is what makes the runtime hardware-agnostic: the same application code builds against the eIQ Neutron backend on the FRDM-MCXN947 and against deterministic software stubs on QEMU. On the dual-core MCXN947, CPU0 boots first, runs the full kernel plus the SynapticOS subsystem, and owns the NPU exclusively; CPU1 runs a minimal kernel with application threads and reaches the NPU only via IPC requests to CPU0.

Source tree layout

SynapticOS is a single Zephyr module. The ten Phase 1 public headers under include/synaptic/ are frozen — they define the API contract that later phases fill in. Phase 2 added one new header, syn_process.h, without touching the frozen ten.

synaptic-os/
├── include/synaptic/       Public API headers (10 frozen + syn_process.h)
├── src/
│   ├── core/               Runtime: memory, models, inference engine, profiling, shell
│   ├── hal/
│   │   ├── common/         Shared software DSP kernels (FFT, Q15 matmul)
│   │   ├── mcxn947/        Neutron NPU, PowerQuad DSP, SmartDMA drivers
│   │   └── stub/           Software fallbacks for QEMU / CI
│   ├── preprocess/         Image, audio, quantization stages
│   └── postprocess/        Classification, detection output stages
├── samples/
│   ├── hello_inference/    End-to-end inference demo
│   ├── face_detection/     Continuous vision-pipeline demo (Phase 2)
│   ├── dual_model/         Cross-core inference demo (Phase 3)
│   └── ota_update/         OTA-over-UART demo (Phase 4)
├── tests/
│   ├── unit/               108 unit tests across 13 suites
│   └── unit_store/         25 store/OTA/swap tests across 3 suites (Phase 4)
├── tools/                  Model packer, flash layout generator, OTA sender (Phase 4)
├── boards/nxp/             Device tree overlays, board configs, partition map
└── docs/                   Guides and specifications

The build system picks the HAL backend at configure time: on MCXN947-series SoCs it compiles src/hal/mcxn947/, on every other target it compiles src/hal/stub/. Both implement the same syn_hal_* interface, so nothing above the HAL changes.

Subsystem map

Where the roadmap stands

Phase 1 (Foundation, v0.1.0) is complete and hardware-verified: memory manager, HAL with stub and hardware scaffolding, model registry, profiler, and shell. Phase 2 (Inference Pipeline, v0.2.0) is complete and hardware-verified as well: the pipeline engine, priority scheduler, built-in processors, and PowerQuad DSP acceleration shipped, and the deliverables were verified live on the FRDM-MCXN947 on 2026-07-12. Phase 3 (Dual-Core & IPC, v0.3.0) is complete and hardware-verified too: dual-core boot with blank-bank fallback, the lock-free IPC rings, cross-core inference offload, and the MPU guard, verified on the board on 2026-07-14. Phase 4 (Model Lifecycle, v0.4.0) is complete and hardware-verified: the dual-core-safe flash partition map, the persistent model store, power-loss-safe A/B OTA updates with hot-swap, and the packaging tools, verified on the board on 2026-07-15, with the test suite at 133 tests across 16 suites (100% pass on QEMU). Phase 5 (Production Hardening, v0.5.0) is complete and hardware-verified: deadline dispatch and layer preemption, memory-optimal activation planning, the health monitor with watchdog reset and CPU1 hang recovery demonstrated live, zero-copy DMA ingest, the binary OTA transport with a power-loss injection at 81% of a raw transfer, and an 11,106-job soak with zero errors — verified on the board on 2026-08-09/10, with the test suite at 158 tests across 21 suites and 83.7% line coverage of the QEMU-buildable core. Phase 6 (Ecosystem & Tooling) is next. The roadmap:

The next three pages walk through the Phase 1 subsystems in depth, starting with the piece everything else depends on: the tensor memory model.