How openxiangshan/xiangshan works
Project type and purpose
• XiangShan is an open‑source, high‑performance RISC‑V processor microarchitecture implemented in Chisel/Scala.
• It generates a full SoC wrapper (Top) with an out‑of‑order core, memory hierarchy (L1–L3), and AXI4‑based peripheral interface.
• It integrates simulation frameworks (difftest, Verilator emu), agile‑development scripts, and device models.
File structure
• Top‑level directories:
• src/main/scala: all Chisel design code
– top: Chisel entry point, configuration parser, Generator
– system: SoC wrapper around the core and memory bus
– xiangshan: core microarchitecture (frontend, backend, cache, mem, transforms)
– device: virtual AXI4 peripherals (RAM, flash, UART, PLIC, CLINT, keyboard, VGA)
– utils: helper traits, bus codecs, arbiter, Bundles, Verilog record generators
• huancun, coupledL2: stand‑alone L2/L3 cache submodules
• fudian: floating‑point unit submodule
• difftest: cosimulation framework connecting to NEMU
• ready‑to‑run, debug, scripts: simulation images, debug harnesses, performance/test scripts
• Makefile, build.sbt/build.sc, mill‑version: build, test, generate verilog
Readme insights
• The master branch implements the Kunminghu microarchitecture:
– Frontend: multiple branch predictors, predecode, IFU, ICache
– Backend: decode → rename → dispatch → execution units (integer, vector, CSR, FPU) → ROB → commit
– Memory subsystem: L1 DCache, MMU/TLB, L2/L3 (huancun), prefetchers, store buffers, SB‐buffer
– SoC‑level AXI4 interconnect to on‑chip devices
• A high‑level SVG of the Kunminghu pipeline is provided in images/xs‑arch‑kunminghu.svg.
Main components & interactions
a. SoC wrapper (Top)
• Clock/reset, configuration loader (YAML parser)
• AXI4 interconnect fabric
• Attached AXI4 devices: RAM, flash, PLIC, CLINT, UART, keyboard, VGA
b. Core pipeline
• Fetch & branch prediction hierarchy → ICache
• Instruction queue → decode
• Rename & register file → dispatch queues
• Execution clusters: ALU, branch, multiplier, divider, CSR, FPU, vector units
• Out‑of‑order scheduler, issue window, ROB → retirement
c. Memory hierarchy
• L1 DCache → Walk TLB → L2/L3 submodule (huancun or coupledL2) → main memory
• Store buffer & SBuffer for memory disambiguation
• Prefetchers at L1 and L2 levels
d. Control & side channels
• CSR pipeline (CSR module, trap/interrupt handling)
• Difftest co‑simulation interface
• Debug module: performance counter, SC‑stat, trace buffer
Architectural patterns & design principles
• Modular Chisel‑based RTL: separate packages for frontend/backend/cache/device.
• OOO pipeline with decoupled handshake nodes (DataDontCareNode, DebugIdentityNode).
• AXI4 bus for memory and peripherals; YAML‑driven configuration.
• FIRRTL transforms (in xiangshan/transforms) for naming and print control.
• Agile scripts automate generation, simulation, performance collection.
• Clear labels on each block matching package names (e.g., xiangshan.frontend.IFU, L1Cache)
• A note or inset illustrating the software toolchain (mill, sbt, Makefile targets, Verilator)