01. eulernpu 개요
eulernpu는 온보드 FPGA에서 현실적으로 증명 가능한 NPU 풀스택입니다. 스펙 정의 → validator → compiler → runtime → simulator → RTL/FPGA → CLI 가 한 줄로 이어져 있고, 그 한 줄의 끝에는 실제 silicon에서 측정된 숫자가 놓여 있습니다.
정체성 — 무엇이고 무엇이 아닌가
- ✅ small-model inference accelerator 풀스택
- ✅ transformer / MLP / CNN / robotics policy / LLM을 공통 primitive 위에서 지원
- ✅ operator-first, spec-first, validation-first, board-realistic, measured design
- ❌ 범용 GPU가 아니다
- ❌ OpenCL 호환 제품이 아니다
- ❌ 그래픽 렌더링 제품이 아니다
eulergpu의 하위 모델이 아닙니다. eulergpu는 참고 가능한 기반 자산이고, eulernpu는 독립된 제품/코드베이스/문서 체계를 가집니다.
4-Layer Spec
모든 기능은 먼저 스펙으로 정의된 뒤 구현됩니다. 스펙은 다음 4 계층으로 나뉩니다.
| 계층 | 무엇 | 위치 |
|---|---|---|
| 1. operator | 145개 op, 18개 그룹 (A–R) | docs/specs/operator_set.md |
| 2. component | 14개 하드웨어 컴포넌트 타입 | docs/specs/spec_schema.md |
| 3. backend/board capability | 6개 보드 프로파일 × 145 ops 매트릭스 | docs/specs/capability_matrix.md |
| 4. compile/deployment | 출력 포맷, 최적화, target | docs/specs/spec_schema.md |
스펙 한 줄 변경이 validator + valid/invalid fixture + 테스트 + 문서 + 구현 6곳에 동시에 닿는 것이 정상입니다. "스펙만 추가하고 구현 안 함"은 미완료입니다.
4 Backends
| backend | 역할 |
|---|---|
cpu_ref | 골든 reference, 결정적 |
npu_sim | cycle / memory model 시뮬레이션, profile/trace |
zynq_ps | ARM Cortex-A9에서 그래프 실행 |
fpga_board | 실제 silicon (PL HLS IP + bare-metal C) |
PL 오프로드 결정은 측정 없이 하지 않습니다. 항상 npu_sim profile → silicon
측정 비교가 선행됩니다.
단일 CLI 진입점
오직 하나입니다:
eulernpu <command> [args...]
eulernpu-info, eulernpu-compile 같은 하이픈 결합 명령은 금지입니다.
모든 기능은 eulernpu 단일 entrypoint의 서브커맨드입니다.
모든 에러는 3줄 포맷을 따릅니다:
<Category>: <what>
Fix: <one line>
See: <doc path>
--lang ko|en|zh|ja|es 글로벌 옵션으로 help/로그/에러 언어를 고정합니다.
기본값은 ko. 명령어/옵션/JSON 키/op 이름은 번역하지 않습니다.
Silicon-validated 자산
이 코드베이스가 실제 보드에서 증명한 것들:
| Project | 보드 | 패턴 | 결과 |
|---|---|---|---|
| 06 L2 (KWS, 단일 op 오프로드) | QMTECH XC7Z020 | matmul_systolic IP | 11/11 MATCH, cycle model 잠금 |
| 06 L3 (KWS, 풀 그래프 NPU) | QMTECH XC7Z020 | kws_npu_top IP | 8.07× 가속, Apple-ANE 패턴 |
| 07 (Bearing, 깊은 풀 그래프) | QMTECH XC7Z020 | bearing_npu_top IP | 11.13× 가속, CWRU 4-class |
| 08 (LLM, L2 hybrid) | QMTECH XC7Z020 | llm_ffn_npu_top IP + ARM KV | nanoGPT 10.77M 정직 측정 |
세 단계 모두 같은 eulernpu/hls/kernels/ 템플릿, 같은 Vivado BD 패턴, 같은
xsdb 하네스를 재사용합니다.
자세한 silicon 결과는:
어디서 시작하는가
| 목적 | 다음 단계 |
|---|---|
| 스펙이 무엇인지 보고 싶다 | 02. validate |
| 작은 모델을 cpu_ref에 돌려 보고 싶다 | 03. compile_run |
| 시뮬레이션으로 cycle/memory 추적 | 04. npu_sim |
| INT8 양자화 | 05. quantize |
| 모델 예제 카탈로그 | 06. models |
| FPGA / Zynq에 올리는 일반 흐름 | 07. fpga_overview |
| 음성 인식을 실 silicon에 올린 사례 | 08. kws_silicon |
| 베어링 결함 감지 silicon | 09. bearing_silicon |
| LLM L2 hybrid silicon + 정직 BENCHMARK | 10. llm_silicon_hybrid |
핵심 철학
- Inference-first — small-model 추론 가속
- Operator-first — 모델은 op 조합, 모놀리식 모델이 아님
- Spec-first — 구현 전에 스펙으로 먼저 정의
- Validation-first — compile/run 이전에 일찍 실패
- Host-first — CPU에서 먼저 맞춘다
- Board-realistic — XC7Z020 한계를 항상 의식
- Deterministic — 백엔드 사이 재현 가능
- Measured design — 측정 없이 오프로드하지 않는다
- Separation of concerns — 컴파일/런타임/드라이버/RTL 분리