spec: NPU module spec (npu.md) — CSRs, weight FIFO protocol, quantization arithmetic, result path

[claude]

Deliverable manifest

Role: chief-architect-agent-Sonnet5-medium
Issue: #5

Artifacts:

• docs/spec/npu.md — NPU module spec (status: draft), CSR/descriptor register map, weight-stream ingress protocol, quantization arithmetic contract, GEMV sequencing FSM, result-path ruling, error conditions

Gates:

• make lint = PASS (blink) — docs-only change, no RTL touched, existing module unaffected
• boundary check (flow/check_boundaries.sh) = branch spec/npu matches no restricted case pattern (docs-only under docs/spec/), same precedent as spec/soc-1 (PR spec: SoC-1 top-level spec — block list, memory map, boot flow #4); verified by reading the script (direct execution required approval not granted in this session) and confirming the diff (docs/spec/npu.md only) against its logic
• make sim / make formal / make synth = not applicable, no RTL/DV/formal files changed
• riscv-arch-test/RISCOF = not applicable

Spec refs:

• Closes ADR-0002 Q1 (quantisation arithmetic: per-tensor (M,s) fixed-point requantiser, round-half-away-from-zero, sat8 int8 clamp — §4.1, NPU-09–NPU-13), Q2 (32-bit accumulator, overflow bound K ≤ 4096 — §4.1, NPU-09/10), Q4 (descriptor/backpressure contract for the soc_1.md §4.2 dedicated weight-stream channel — §2.3, NPU-06–NPU-08), Q8 (lm_head as an ordinary long descriptor, no sequencer special-case — §4.2)
• Resolves soc_1.md Q-SOC1-07 (result path: streaming argmax, chosen with area/bandwidth/orchestration-purity numbers against on-chip-buffer and CPU-streamed alternatives — §4.4, NPU-20)
• Notes Q3 (ADR-0002 SRAM macro choice) resolved by inheritance — the accepted D5 recommendation already specifies the 2 kB OpenRAM macro this spec adopts (§7)
• Closes soc_1.md SOC1-26 (malformed-descriptor error table — §5, NPU-21) and SOC1-20 (compute-done strictly after stream-done — §4.3, NPU-18)
• Claims previously-reserved irq[7] (soc_1.md §4.4 table) for a new NPU descriptor-error line (§2.5)
• Shall-IDs NPU-01 through NPU-23 across §2–§5

Open items:

• Q5 (ADR-0002, special-function-unit scope) — inherited, still open; governs RMSNorm/softmax/SwiGLU, not this module's GEMV contract
• Q6 (ADR-0002, softmax numerics) — inherited, still open
• Q7 (ADR-0002, KV-cache precision/residency) — inherited, still open
• Q-NPU-01 (new, low priority) — this spec commits to greedy (argmax) decoding only (NPU-20); temperature/top-k sampling would need a result-path revisit, flagged so it isn't silently reconciled later
• Status remains draft: 4 open items above remain (3 inherited from ADR-0002, 1 new low-priority note)

Friction:

• flow/check_boundaries.sh required approval to execute directly; verified by reading the script instead (same friction noted in PR spec: SoC-1 top-level spec — block list, memory map, boot flow #4's manifest for spec/soc-1)
• The int8×int8→int32 quantization contract (issue item 3) required reconciling llama2.c's actual reference quantizer (runq.c, fetched via WebFetch since it's not in-repo and not otherwise cited) against ADR-0002's costed hardware (one requantiser block, no per-group scale-table storage) — upstream's default GS=64 grouping doesn't match the costed design; resolved by choosing GS=n (per-tensor/per-channel), a legitimate degenerate case of the same upstream algorithm, not an invented scheme, but this took real investigation rather than being derivable from in-repo docs alone
• The NPU array's 1×8 shape (ADR-0002 D2, sized for a future 64-bit/8 B-per-cycle port) is wider than soc_1.md's actually-committed 32-bit/4 B-per-cycle port (SOC1-19) — not a defect, soc_1.md already anticipates this ("future part swap... no datapath redesign"), but it took cross-referencing D4's table against SOC1-19 to confirm the mismatch was intentional rather than a live divergence needing arbitration

Skill candidates:

• .claude/skills/chief-architect/references/spec-authoring-patterns.md — when a module's quantization/numerics contract depends on an upstream open-source reference implementation's actual algorithm (not just its stated model format), fetching and citing that source directly (as done here for llama2.c/runq.c) is worth codifying as a standard step before ruling on arithmetic contracts, rather than assuming the DSE/ADR's summary is complete
• .claude/skills/integrator/references/citation-attribution.md — reconfirmed this run: cite ADR-0002 by its own D/Q labels (no numbered §), cite results.md/profile.md by §N (both have numbered sections) — consistent with the prior PR's citation fix

[claude]

Integrator review — request changes

Boundary: clean (single file, docs/spec/npu.md, matches chief-architect's spec domain; commit author chief-architect-agent-Sonnet5-medium per /CLAUDE.md signature convention). Gates (lint, boundaries) pass per CI, docs-only change, no thresholds/waivers touched. Citations spot-checked against ADR-0002, soc_1.md, and profile.md/results.md (K/N shapes, 4B/c vs 8B/c tok/s figures, §4.1 quantisation contract lineage, irq/CSR window precedent) — all consistent.

1. docs/spec/npu.md:364-368 — arithmetic error in the rejected-alternative area estimate (off by ~2×).

"Needs 32 KB of new SRAM — 16× the existing 2 kB macro. At ADR-0002's own OpenRAM density (≈142,000 µm²/KB, explore/npu-dse/results.md §1) that is ≈2.27 mm²..."

results.md §1 gives the 2 kB macro at 284,538 µm² (17.37 µm²/bit → ≈142,000 µm²/KB, matches). Applying that density to 32 KB (or equivalently 16 × 284,538 µm²) gives ≈4.55 mm², not 2.27 mm² — the stated figure is off by a factor of ~2. (31,250 B exact vocab-logit size gives ≈4.45 mm², same order.)

This doesn't flip the rejection verdict (4.55 mm² is more over the 3.24 mm² core budget than claimed, so the decision in §4.4 is unaffected), but it's a cited, wrong number presented as evidence in a normative design-rejection argument, and should be corrected before this leaves draft.

Please fix the figure (and re-verify the surrounding sentence's math) and re-push.

[WJiangH]

@claude chief-architect: single fix per integrator review — docs/spec/npu.md:364-368, the 32 KB SRAM area is ~4.55 mm2 (16 x 284,538 um2), not 2.27 mm2; correct the figure and re-verify the sentence's arithmetic. The rejection verdict itself stands. Role-signed commit, push.

[claude]

Claude finished @WJiangH's task in 53s —— View job

---

Fixed per integrator review

• Read trigger comment and integrator feedback
• Locate docs/spec/npu.md:364-368 and verify the arithmetic
• Correct the area figure and re-verify surrounding sentence math
• Role-signed commit and push

Fix: docs/spec/npu.md:364-368 — corrected the on-chip-buffer rejected-alternative area figure from ≈2.27 mm² to ≈4.55 mm² (16 × 284,538 µm² per explore/npu-dse/results.md §1's 2 kB macro figure, ≈142,000 µm²/KB × 32 KB). Also tightened the sentence's conclusion to reflect the corrected margin against the 3.24 mm² core budget ("blow the die budget more than twice over" rather than the prior unquantified phrasing).

Verdict unaffected: the corrected figure is more over budget than originally stated, so §4.4's rejection of the on-chip-buffer alternative (in favor of streaming argmax) stands unchanged.

Commit: 5949a23, authored chief-architect-agent-Sonnet5-medium <chief-architect@agents.openchip> per /CLAUDE.md signature convention. Docs-only change (1 file, +4/-3); no RTL/DV/formal impacted, no gates re-run needed beyond the existing docs-only lint/boundary pass already on this PR.
· branch spec/npu

[claude]

Integrator review — request changes

Boundary: clean (single file, docs/spec/npu.md, chief-architect's spec domain; commit author chief-architect-agent-Sonnet5-medium per signature convention). Gates: boundaries pass, gates pass (docs-only, no thresholds/waivers touched). The area-figure fix itself (≈2.27→≈4.55 mm²) is now correct: 16 × 284,538 µm² (explore/npu-dse/results.md §1, 2 kB OpenRAM macro LEF) = 4,552,608 µm² ≈ 4.55 mm² — confirmed.

1. docs/spec/npu.md:369 — new quantifier introduced by the fix isn't supported by the numbers.

"...this alone would blow the die budget more than twice over, for a buffer needed only transiently..."

"This alone" = the 32 KB buffer, ≈4.55 mm². Against the 3.24 mm² total core budget (results.md §5, line ~160), that's 4.55 / 3.24 ≈ 1.4× — about 40% over budget, not "more than twice over" (which would need ≈6.48 mm², or ≥16× a macro nearly double the actual 2 kB size). Even folding in the module's existing 0.449 mm² spend (results.md §7.2/§4c), total is 4.55 + 0.449 = 4.999 mm² ≈ 1.54× budget — still not "twice over." No reading of the cited figures reaches 2×.

The underlying rejection verdict is still unaffected (4.55 mm² alone already exceeds the 3.24 mm² budget, so §4.4's conclusion holds) — this is a wording/arithmetic-precision finding on the just-edited sentence, not a verdict challenge. Please replace "more than twice over" with a figure that actually follows from the cited numbers (e.g. "≈1.4× the total core budget, by itself" or similar), and re-push.

[WJiangH]

@claude chief-architect: one wording fix per integrator — docs/spec/npu.md:369 replace 'more than twice over' with the supported figure (≈1.4× the 3.24 mm2 core budget by itself). Only that edit. Role-signed commit, push.

[claude]

Claude finished @WJiangH's task in 43s —— View job

---

Fixed per integrator review

• Read trigger comment and integrator feedback
• Locate docs/spec/npu.md:369 and verify the arithmetic
• Replace "more than twice over" with supported figure (≈1.4×)
• Role-signed commit and push

Fix: docs/spec/npu.md:369 — replaced the unsupported "more than twice over" claim with the figure the cited numbers actually support: "this alone is ≈1.4× the 3.24 mm² core budget" (4.55 mm² / 3.24 mm² ≈ 1.4×). Only this sentence changed; the rest of the on-chip-buffer rejection paragraph and §4.4's verdict (streaming argmax chosen over on-chip buffer) are unaffected.

Commit: cd2fe05, authored chief-architect-agent-Sonnet5-medium <chief-architect@agents.openchip> per /CLAUDE.md signature convention. Docs-only change (1 file, +1/-1); no RTL/DV/formal impacted, no gates re-run needed beyond the existing docs-only lint/boundary pass already on this PR.
· branch spec/npu

[claude]

Integrator review — merged

Verdict: clean, merged. Both prior findings are correctly resolved.

Boundary: single file docs/spec/npu.md, chief-architect's spec domain; commit author chief-architect-agent-Sonnet5-medium per /CLAUDE.md. No RTL/DV/formal/flow paths touched.

Gates: CI boundaries pass, gates pass. Docs-only — no thresholds/waivers/constraints touched.

Spot-check evidence (this round):

• docs/spec/npu.md:366-369 — area fix confirmed: 16 × 284,538 µm² (explore/npu-dse/results.md §1, 2 kB OpenRAM macro LEF) = 4,552,608 µm² ≈ 4.55 mm². Against the 3.24 mm² core budget (results.md line 160): 4.55 / 3.24 ≈ 1.4×, matching the corrected "≈1.4× the 3.24 mm² core budget" wording exactly.
• ADR-0002 D1/D2/D4/D5 cross-checked against docs/adr/0002-npu-architecture.md: 1×8 array shape (D2), 25.4 tok/s (D4), 8×32-bit accumulator (D5), 3.24 mm² core budget — all consistent with npu.md's citations.
• soc_1.md SOC1-05 (0x0002_0000 CSR window), SOC1-11 (stall-don't-drop weight stream), SOC1-19 (build-time port-width parameter), SOC1-20 (irq[6] compute-done distinct from irq[4] stream-done) — all consistent with npu.md's claims.

No further findings. Merged via merge commit, branch deleted.