01. eulernpu Overview
eulernpu is a full-stack NPU project that can be realistically proven on an on-board FPGA. Spec definition → validator → compiler → runtime → simulator → RTL/FPGA → CLI line up in a single chain, and at the end of that chain is a number measured on real silicon.
Identity — what it is and isn't
- ✅ A full-stack inference accelerator for small models
- ✅ Supports transformer / MLP / CNN / robotics policy / LLM on shared primitives
- ✅ Operator-first, spec-first, validation-first, board-realistic, measured design
- ❌ Not a general-purpose GPU
- ❌ Not OpenCL-compatible
- ❌ Not a graphics product
eulernpu is not a sub-model of eulergpu. eulergpu is a reference-only asset; eulernpu has its own product, codebase, and documentation.
4-Layer Spec
Every feature is defined in spec first, implemented second. The spec splits into four layers.
| Layer | What | Where |
|---|---|---|
| 1. operator | 145 ops in 18 groups (A–R) | docs/specs/operator_set.md |
| 2. component | 14 hardware component types | docs/specs/spec_schema.md |
| 3. backend/board capability | 6 board profiles × 145 ops matrix | docs/specs/capability_matrix.md |
| 4. compile/deployment | output format, optimization, target | docs/specs/spec_schema.md |
A one-line spec change touches validator + valid/invalid fixtures + tests + docs + implementation — six places at once is normal. "Added a spec key, implementation pending" is not done.
4 Backends
| backend | Role |
|---|---|
cpu_ref | Golden reference, deterministic |
npu_sim | Cycle / memory model simulation, profile/trace |
zynq_ps | Graph execution on ARM Cortex-A9 |
fpga_board | Real silicon (PL HLS IP + bare-metal C) |
PL offload decisions are not made without measurement. npu_sim profile
→ silicon measurement comparison is always the gate.
Single CLI Entrypoint
Only one:
eulernpu <command> [args...]
Hyphen-joined commands like eulernpu-info, eulernpu-compile are
banned. All features are subcommands of the single eulernpu
entrypoint.
All errors follow a 3-line format:
<Category>: <what>
Fix: <one line>
See: <doc path>
The global --lang ko|en|zh|ja|es option fixes help/log/error language.
Default is ko. Command/option/JSON key/op names are not translated.
Silicon-validated Assets
What this codebase has actually proven on real boards:
| Project | Board | Pattern | Result |
|---|---|---|---|
| 06 L2 (KWS, single-op offload) | QMTECH XC7Z020 | matmul_systolic IP | 11/11 MATCH, locks the cycle model |
| 06 L3 (KWS, full-graph NPU) | QMTECH XC7Z020 | kws_npu_top IP | 8.07× speedup, Apple-ANE pattern |
| 07 (Bearing, deeper full graph) | QMTECH XC7Z020 | bearing_npu_top IP | 11.13× speedup, CWRU 4-class |
| 08 (LLM, L2 hybrid) | QMTECH XC7Z020 | llm_ffn_npu_top IP + ARM KV | honest measurement on nanoGPT 10.77M |
All three stages reuse the same eulernpu/hls/kernels/ templates, the
same Vivado BD pattern, and the same xsdb harness.
Detailed silicon results:
Where to Start
| Goal | Next step |
|---|---|
| Want to see what a spec looks like | 02. validate |
| Want to run a small model on cpu_ref | 03. compile_run |
| Trace cycles/memory in simulation | 04. npu_sim |
| INT8 quantization | 05. quantize |
| Model example catalog | 06. models |
| General FPGA / Zynq flow | 07. fpga_overview |
| The KWS-on-silicon case study | 08. kws_silicon |
| Bearing fault detection silicon | 09. bearing_silicon |
| LLM L2 hybrid silicon + honest BENCHMARK | 10. llm_silicon_hybrid |
Core Philosophy
- Inference-first — small-model inference acceleration
- Operator-first — models are op compositions, not monoliths
- Spec-first — define in spec before implementing
- Validation-first — fail early, before compile/run
- Host-first — get it right on CPU first
- Board-realistic — always conscious of XC7Z020 constraints
- Deterministic — reproducible across backends
- Measured design — no offload without measurement
- Separation of concerns — compiler/runtime/driver/RTL split