Level RISC-V documentation

GitHub repository

Source code: github.com/kerimturak/level-v
Documentation: kerimturak.github.io/level-v

• Quick start

  ---

  Set up the project and run your first simulation

  Getting started guide

• Architecture

  ---

  Five-stage pipeline, branch predictor, cache subsystem

  Architecture details

• Core modules

  ---

  CPU, fetch, decode, execute, memory, writeback

  Core documentation

• Peripheral modules

  ---

  UART, SPI, I2C, GPIO, timer, PWM, DMA, VGA

  Peripheral documentation

---

Project highlights

Feature	Value
ISA	RV32IMC (base integer + multiply + compressed)
Pipeline	Five-stage (IF → ID → EX → MEM → WB)
Cache	8-way set-associative, 8 KB I-cache, 8 KB D-cache
Branch predictor	GShare (512-entry PHT, 256-entry BTB, 16-deep RAS)
Bus	Wishbone B4 pipelined
Clock	50 MHz target
Language	SystemVerilog (IEEE 1800-2017)

---

Documentation layout

docs/
├── index.md                   # This page
├── getting-started.md         # Setup guide
├── architecture.md            # Architecture
├── tools.md                   # Tool setup
│
├── core/                      # Core module docs
│   ├── index.md               # Core overview
│   ├── cpu_module.md          # CPU top level
│   ├── hazard_unit_module.md  # Hazard handling
│   ├── stage01_fetch/         # Fetch stage
│   ├── stage02_decode/        # Decode stage
│   ├── stage03_execute/       # Execute stage
│   ├── stage04_memory/        # Memory stage
│   ├── stage05_writeback/     # Writeback stage
│   ├── mmu/                   # Memory subsystem
│   └── pmp_pma/               # Physical memory attributes
│
├── periph/                    # Peripheral docs
│   ├── index.md               # Peripheral overview
│   ├── uart.md
│   ├── spi.md
│   ├── i2c.md
│   ├── gpio.md
│   ├── timer.md
│   ├── plic.md
│   ├── pwm.md
│   ├── dma.md
│   ├── wdt.md
│   └── vga.md
│
├── include/                   # Include files
├── pkg/                       # Packages
├── ram/                       # Memory modules
├── tracer/                    # Instruction tracer
├── util/                      # Utilities
├── wrapper/                   # Top-level wrappers
│
├── script/                    # Build system
├── sim/                       # Simulation
├── env/                       # Test environments
│
├── FIXES_HISTORY.md           # Running log: what we fixed and why
└── PERF_PIPELINE_LOG.md       # LOG_PERF_STALL reference

---

Quick commands

# Build with Verilator
make verilate

# Run a single test
make t T=rv32ui-p-add

# CoreMark benchmark
make run_coremark SIM_UART_MONITOR=1

# Full ISA suite
make isa

# Lint
make lint

---

References

• Fixes history — ongoing log of significant fixes (what / why / files)
• Pipeline performance log (LOG_PERF_STALL) — stall/flush types and tuning ideas
• RISC-V ISA specifications
• Wishbone B4 specification
• Verilator manual

---

Contact

• GitHub: kerimturak/level-v
• Issues: GitHub issues