Chipyard CPU Config Selection (v0)

Status: spec only. No generated RTL is checked in yet. This document selects the v0 Chipyard configuration, pins the upstream SHA, and lays out the wrapper directory layout that will hold the generated CPU subsystem once it is imported.

Decision

v0 CPU subsystem is Rocket RV64GC, single hart, SV39 MMU, L1 I$ + D$, with CLINT and PLIC. Wrapped in a thin AXI/TileLink adapter to the existing e1_linux_soc_contract memory and MMIO contract. Rationale lives in docs/rtl/open_rtl_prototype_path.md; this doc is the actionable selection.

The CLINT and PLIC come from the Chipyard/Rocket generator; the existing e1_interrupt_controller becomes a compatibility shim and will be retired once the generated PLIC drives the downstream IRQ contract.

Upstream pin

Pinned Chipyard reference (this is the floor; bump only with provenance recorded under build/evidence/cpu_ap/):

repo:    https://github.com/ucb-bar/chipyard
ref:     1.12.0
SHA:     TODO_PIN_CHIPYARD_SHA
record:  git -C external/chipyard rev-parse HEAD > build/evidence/cpu_ap/chipyard.sha
         git -C external/chipyard submodule status --recursive \
              > build/evidence/cpu_ap/chipyard-submodules.txt

Bootstrap is scripts/bootstrap_chipyard.sh; that script must be updated to git checkout <SHA> after the SHA is filled in. Until then it floats on the default branch and must not satisfy any release gate.

Generator invocation (target, not yet wired into Makefile):

cd external/chipyard
./scripts/init-submodules-no-riscv-tools.sh
make -C sims/verilator CONFIG=ElizaE1RocketConfig verilog
# emit Verilog only; do not run sim from this repo's CI

ElizaE1RocketConfig is a local config class that lives under rtl/wrappers/chipyard/src/main/scala/. It composes Chipyard's AbstractConfig with WithNBigCores(1), the Eliza memory map (MemoryBusKey at 0x8000_0000), and the Eliza MMIO bus (PeripheryBusKey carved to expose 0x0C00_0000 and 0x1001_0000).

Wrapper directory layout

All imported/generated artefacts live under rtl/wrappers/ to keep them isolated from the hand-written e1_* contract RTL:

rtl/wrappers/
  README.md                              # provenance + regen instructions
  chipyard/
    src/main/scala/
      ElizaE1Config.scala         # Config class composition
      ElizaBootROM.scala             # references fw/boot-rom artefact path
    generated/                           # checked-in generated Verilog, machine written
      ElizaE1RocketTop.v          # generator output, DO NOT hand-edit
      ElizaE1RocketTop.fir        # FIRRTL for re-elaboration
      ElizaE1RocketTop.dts        # device tree fragment, checked vs sw/platform
      generated.manifest                 # chipyard SHA, scala/jdk, command, timestamp
    rocket_subsystem_wrapper.sv          # SV wrapper: clocks, resets, AXI bridges
    plic_compat_shim.sv                  # adapts generated PLIC IRQ ID space to existing
                                         # e1_interrupt_controller register window
    clint_axi_adapter.sv                 # exposes CLINT mtime/mtimecmp to debug-MMIO scan
  README_PROVENANCE.md

rtl/wrappers/chipyard/generated/ is the only place generated RTL may live. scripts/run_rtl_check.sh must refuse to include it in the default lint or synthesis source list until the wrapper hand-off is signed off; until then it is built only by the explicit make rocket-elab target.

Integration steps

Each step is a separate logical commit on its own branch off ws/cpu-boot-spec:

1. Pin upstream. Fill TODO_PIN_CHIPYARD_SHA in this doc, add the git checkout step to scripts/bootstrap_chipyard.sh, and archive build/evidence/cpu_ap/chipyard.sha + recursive submodule status.
2. Add Scala config. Author ElizaE1Config.scala under rtl/wrappers/chipyard/src/main/scala/. No build wiring yet.
3. Add elaboration target. New make rocket-elab runs the Chipyard generator and copies output to rtl/wrappers/chipyard/generated/ along with generated.manifest. Target is not invoked by make smoke or make ci until step 6 lands.
4. Bridge RTL. Add rocket_subsystem_wrapper.sv to translate the generated AXI4 ports to the AXI-Lite32 contract used by e1_linux_soc_contract. Width adapters live in this file only.
5. Boot ROM hookup. Reference the assembled stub from fw/boot-rom/ (see docs/arch/boot-rom-spec.md) as the Chipyard BootROMParams.contentFileName.
6. Verification crossover. Wire a new cocotb top (e1_rocket_soc_tb.sv) that drops the wrapper into the contract harness, runs a wfi smoke and a CLINT timer interrupt smoke, and archives build/evidence/cpu_ap/rocket_smoke.log.
7. Retire stub alias. Rename e1_cpu_subsystem_stub.sv to e1_tiny_cpu_contract.sv; keep a thin alias module under the old name for one release cycle.

Blocking gates (do not flip until evidence exists)

• has_cpu = true in any release manifest is forbidden until step 6 emits build/evidence/cpu_ap/rocket_smoke.log containing a CLINT mtimecmp interrupt entry and an OpenSBI banner.
• Synthesis (make synth) must continue to exclude generated Rocket Verilog until provenance and license review are recorded.
• Formal (REQUIRE_SBY=1) must not be claimed over generated RTL; only the wrapper SV files are in scope for the property set.