Drop the Current Phase section because it is a progress marker that would go stale or create noisy commits as the roadmap advances.
Add a minimal .gitignore for local Codex state only, keeping broader ignore rules out until the repo actually needs them.
Add a Tutorial tree that mirrors the roadmap from Phase 0 through Linux bring-up.
Each phase and subphase gets a short learning note with consistent sections for
context, goals, new concepts, mental model, learning tasks, pitfalls, tooling,
testing, and references.
The tutorial material is intentionally explanatory rather than implementation
code. It gives a systems-oriented learner enough FPGA, SystemVerilog, RISC-V,
firmware, and Linux bring-up context to approach each roadmap phase without
turning the notes into copy-paste RTL.
Convert the memory-bus guidance from a loose list of request/response fields into
packed mem_req_t and mem_rsp_t payload structs carried by separate valid/ready
handshakes. Spell out that the same channel shape is instantiated independently
for the instruction bus and data bus so the design remains Harvard at the bus
level while still sharing a single contract.
Clarify fault ownership before RTL exists: slaves only raise rsp.err for access
faults they can own, the LSU detects misaligned loads/stores before issuing a
D-bus request, the decoder owns illegal instructions and ebreak/ecall decode
events, and the future MMU owns page faults before translated requests reach the
bus.
Update the roadmap to use the structured bus field names, correct the
misalignment tests and GCC illegal-instruction explanation, and prefer modern
RISC-V device-tree ISA properties with an optional legacy riscv,isa string for
older kernels.
Broaden the documented end target from RV32IM plus machine-mode support to a
Linux-capable RV32IMA core with Zicsr, Zifencei, M/S/U privilege, and Sv32.
Add atomics as a required Phase 12 milestone, move the optional pipeline and
memory-system work later, and introduce explicit Linux bring-up preparation for
boot ABI, device tree, UART driver compatibility, OpenSBI versus direct M-mode
boot, and kernel/initramfs handoff.
Tighten compiler guidance so the advertised -march string follows the hardware
that is actually decoded: rv32im for early bare-metal work, then
rv32im_zicsr_zifencei after CSR/fence.i support, and rv32ima_zicsr_zifencei once
atomics land. The roadmap also calls out loud illegal-instruction halts instead
of silently treating unsupported operations as NOPs.
Replace the first broad project sketch with more concrete hardware assumptions
for implementation on the Arty A7 100T.
Document the 50 MHz MMCM-derived clock, synchronous active-high reset after the
board reset synchronizer, and a split instruction/data BRAM map with reset PC at
0x2000_0000. Update the UART layout to separate TX, RX, and status registers,
and make the README/roadmap agree on the address ranges that firmware and the
future linker script will use.
Also split the M extension out of the combinational ALU into a dedicated
multi-cycle unit with start/busy/done handshaking, describe BRAM latency and
stall behavior in the single-cycle logical model, and add riscv-tests as the
planned compliance check once GCC-generated programs are running.
Establish the repository as a documentation-first plan for a custom
SystemVerilog RISC-V CPU targeting the Digilent Arty A7 100T.
Add the initial README, roadmap, and contributor guidance that define the
starting RV32IM direction, Vivado/RISC-V toolchain expectations, basic
SystemVerilog conventions, and the phased path from an architecture contract
toward a Linux-capable SoC.
This commit intentionally contains planning and interface direction only; RTL,
firmware, testbenches, and Vivado project files are left for later phases.
imple