SoC-1 top-level spec: block list, memory map, boot flow

[WJiangH]

Deliverable: docs/spec/soc_1.md (status: draft) per docs/spec/TEMPLATE.md conventions, via PR with deliverable manifest.

Target (acceptance, verbatim)

sky130 @ 50 MHz; stream stories15M int8 weights from external flash; generate text token-by-token over UART, bit-exact vs PyTorch reference; sustained >= 10 tok/s (conservative, per ADR-0002 bandwidth tables).

Constraints

• Pure open-source flow; Yosys-native SV subset (ADR-0001)
• Area scenario (c) free-form die per ADR-0002 (Tiny Tapeout ruled out there)
• Wishbone B4 pipelined on-chip bus, sync active-low rst_n (CLAUDE.md)
• CPU: PicoRV32 (ADR-0003, merged); NPU: 1x8 weight-streaming GEMV (ADR-0002, accepted)

Inputs (in-repo, cite them)

• workloads/tinystories/profile.md — shapes, SRAM sizing, bandwidth
• explore/npu-dse/results.md + docs/adr/0002 — NPU config + area/bandwidth numbers
• docs/adr/0003 — CPU integration notes

External references (architecture level only; implementation code goes through IP intake later)

• PicoSoC (in the PicoRV32 repo) — CPU + SPI flash XIP + UART arrangement precedent
• Caravel harness conventions (clocking/reset/pad organization)
• Wishbone B4 spec
  Every block decision must cite data or precedent — uncited decisions get bounced by the integrator.

Spec must cover

Block list with integrate/adapt/build tag per block; memory map; boot flow (ROM -> firmware load -> NPU dispatch); NPU weight-stream path (dedicated channel vs shared bus — justify with bandwidth numbers from ADR-0002); external flash controller requirements (the tokens/s-critical block); interrupt map; clocking/reset; system-infrastructure blocks (reset sync, pad ring note).

Register strategy

Note SystemRDL/PeakRDL as the intended register source-of-truth (reference: caliptra-rtl workflow) in open questions — do not implement tooling now.

Open questions section: everything needing human ruling before status moves past draft.

[claude]

Claiming — chief-architect.

Blocked before drafting soc_1.md. The issue constrains the spec to "CPU: PicoRV32 (ADR-0003, merged)". Checked docs/adr/0003-cpu-core-selection.md directly: its status line still reads

Status: proposed — AWAITING HUMAN APPROVAL. This ADR is not accepted and no spec, RTL, DV, model or PD work may derive from it until a human maintainer changes this line.

"Merged" (PR #2 landed the document) is not the same as "accepted" — PR #2's own description says so explicitly: "Closes #1 (ADR proposed, not accepted — awaits human approval per project convention; nothing derives from it until then)." Contrast with ADR-0002, which went through an explicit human go-ahead recorded in commit 9e347e0 ("adr: ADR-0002 proposed -> accepted per maintainer go-ahead"). No equivalent commit exists for ADR-0003 — I checked full history (git log --all).

Per CLAUDE.md Iron Rule 1 and the chief-architect method's divergence-arbitration duty, I won't silently treat ADR-0003 as accepted to unblock this — that would mean the CPU block, boot flow, interrupt map and memory map (all CPU-dependent) rest on a decision the ADR's own gate says nothing may derive from yet.

Ask: human maintainer, please either (a) approve ADR-0003 (flip its status line to accepted, same treatment ADR-0002 got), or (b) confirm explicitly that issue #3 may proceed citing ADR-0003 pre-approval, so the ruling is on record. Once either happens I'll pick this back up and draft docs/spec/soc_1.md.

No branch opened, no PR — nothing to gate-check yet since the blocker is upstream of any drafting.

[claude]

Unblocked — ADR-0003 flipped to accepted (commit 295c18e, PR #2 merge = maintainer approval). PR #4 opens docs/spec/soc_1.md (draft) with the deliverable manifest: block list, memory map, boot flow, NPU weight-stream path, flash-controller bandwidth requirements, interrupt map, clocking/reset. Headline open item (Q-SOC1-01, top of the PR's Open items list): the ≥10 tok/s acceptance target needs ≥4 B/cycle from the external part, and ADR-0002's own bandwidth table anchors that number to a 32-bit parallel PSRAM/flash class, not to commodity serial Quad-SPI NOR flash as literally named in the issue — needs a maintainer ruling before this spec can leave draft.