# liangkangnan/tinyriscv architecture

> Architecture diagram of the GitHub repository liangkangnan/tinyriscv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liangkangnan/tinyriscv
- Repository: https://github.com/liangkangnan/tinyriscv

## Overview

TinyRISC-V is a Verilog single-core 32-bit RV32IM processor and SoC intended for FPGA use. The principal workflow is to load a program into the system, fetch and execute its instructions through a three-stage pipeline, and interact with memory-mapped peripherals; firmware can also be sent to an FPGA board over serial. The README documents interrupts, JTAG, UART updates, and example software. RTL source excerpts were not provided, so internal wiring is limited to documented relationships; the FPGA framework README was not sampled.

Main entry points: [`rtl/soc/tinyriscv_soc_top.v`](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/soc/tinyriscv_soc_top.v) (SoC top), [`rtl/core`](https://github.com/liangkangnan/tinyriscv/tree/master/rtl/core) (Fetch-decode-execute), [`rtl/core/tinyriscv.v`](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/tinyriscv.v) (RISC-V core), [`rtl/core/ex.v`](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/ex.v) (Execute unit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Processor core"]
  node_cpu["RISC-V core<br/>[tinyriscv.v]"]
  node_pipeline["Fetch-decode-execute"]
  node_registers["Register file<br/>[regs.v]"]
  node_decoder["Instruction decode<br/>[id.v]"]
  node_execute["Execute unit<br/>[ex.v]"]
  node_divider["Divide unit<br/>[div.v]"]
  node_csr["CSR registers<br/>[csr_reg.v]"]
end

subgraph group_system["SoC and peripherals"]
  node_soc["SoC top"]
  node_bus["RIB bus<br/>[rib.v]"]
  node_rom[("ROM<br/>[rom.v]")]
  node_ram[("RAM<br/>[ram.v]")]
  node_timer["Timer<br/>[timer.v]"]
  node_gpio["GPIO<br/>[gpio.v]"]
  node_spi["SPI master<br/>[spi.v]"]
  node_uart["UART<br/>[uart.v]"]
end

subgraph group_debug["Debug and updates"]
  node_jtag["JTAG debug<br/>[jtag_top.v]"]
  node_uart_debug["UART updater<br/>[uart_debug.v]"]
  node_downloader["Serial downloader"]
end

subgraph group_software["Software examples"]
  node_examples["C examples"]
  node_freertos["FreeRTOS port"]
end

node_programmer(("Program author"))
node_fpga["FPGA board"]

node_programmer -->|"writes code"| node_examples
node_examples -->|"runs on"| node_soc
node_soc -->|"integrates"| node_cpu
node_cpu -->|"executes through"| node_pipeline
node_pipeline -.->|"uses"| node_registers
node_pipeline -.->|"uses"| node_decoder
node_pipeline -.->|"uses"| node_execute
node_execute -.->|"supports division"| node_divider
node_cpu -->|"supports CSR"| node_csr
node_soc -->|"uses bus"| node_bus
node_soc -.->|"integrates"| node_rom
node_soc -.->|"integrates"| node_ram
node_soc -.->|"integrates"| node_timer
node_soc -.->|"integrates"| node_gpio
node_soc -.->|"integrates"| node_spi
node_soc -.->|"integrates"| node_uart
node_soc -->|"supports debug"| node_jtag
node_soc -->|"supports updates"| node_uart_debug
node_downloader -->|"sends firmware"| node_fpga
node_freertos -->|"runs on"| node_soc

click node_soc "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/soc/tinyriscv_soc_top.v"
click node_cpu "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/tinyriscv.v"
click node_pipeline "https://github.com/liangkangnan/tinyriscv/tree/master/rtl/core"
click node_registers "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/regs.v"
click node_decoder "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/id.v"
click node_execute "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/ex.v"
click node_divider "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/div.v"
click node_csr "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/csr_reg.v"
click node_bus "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/rib.v"
click node_rom "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/rom.v"
click node_ram "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/ram.v"
click node_timer "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/timer.v"
click node_gpio "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/gpio.v"
click node_spi "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/spi.v"
click node_uart "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/uart.v"
click node_jtag "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/debug/jtag_top.v"
click node_uart_debug "https://github.com/liangkangnan/tinyriscv/blob/master/rtl/debug/uart_debug.v"
click node_downloader "https://github.com/liangkangnan/tinyriscv/blob/master/tools/tinyriscv_fw_downloader.py"
click node_examples "https://github.com/liangkangnan/tinyriscv/tree/master/tests/example"
click node_freertos "https://github.com/liangkangnan/tinyriscv/tree/master/tests/example/FreeRTOS"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cpu,node_pipeline,node_registers,node_decoder,node_execute,node_divider,node_csr toneBlue
class node_soc,node_bus,node_rom,node_ram,node_timer,node_gpio,node_spi,node_uart toneAmber
class node_jtag,node_uart_debug,node_downloader toneMint
class node_examples,node_freertos toneRose
class node_programmer,node_fpga toneIndigo
```

## Components

### Processor core

- [RISC-V core](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/tinyriscv.v): `rtl/core/tinyriscv.v`
- [Fetch-decode-execute](https://github.com/liangkangnan/tinyriscv/tree/master/rtl/core): `rtl/core`
- [Register file](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/regs.v): `rtl/core/regs.v`
- [Instruction decode](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/id.v): `rtl/core/id.v`
- [Execute unit](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/ex.v): `rtl/core/ex.v`
- [Divide unit](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/div.v): `rtl/core/div.v`
- [CSR registers](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/csr_reg.v): `rtl/core/csr_reg.v`

### SoC and peripherals

- [SoC top](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/soc/tinyriscv_soc_top.v): `rtl/soc/tinyriscv_soc_top.v`
- [RIB bus](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/core/rib.v): `rtl/core/rib.v`
- [ROM](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/rom.v): `rtl/perips/rom.v`
- [RAM](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/ram.v): `rtl/perips/ram.v`
- [Timer](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/timer.v): `rtl/perips/timer.v`
- [GPIO](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/gpio.v): `rtl/perips/gpio.v`
- [SPI master](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/spi.v): `rtl/perips/spi.v`
- [UART](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/perips/uart.v): `rtl/perips/uart.v`

### Debug and updates

- [JTAG debug](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/debug/jtag_top.v): `rtl/debug/jtag_top.v`
- [UART updater](https://github.com/liangkangnan/tinyriscv/blob/master/rtl/debug/uart_debug.v): `rtl/debug/uart_debug.v`
- [Serial downloader](https://github.com/liangkangnan/tinyriscv/blob/master/tools/tinyriscv_fw_downloader.py): `tools/tinyriscv_fw_downloader.py`

### Software examples

- [C examples](https://github.com/liangkangnan/tinyriscv/tree/master/tests/example): `tests/example`
- [FreeRTOS port](https://github.com/liangkangnan/tinyriscv/tree/master/tests/example/FreeRTOS): `tests/example/FreeRTOS`

### Other components

- **Program author**
- **FPGA board**

## Connections

- Program author → C examples: writes code (evidence: `README.md`)
- C examples → SoC top: runs on (evidence: `README.md`)
- SoC top → RISC-V core: integrates (evidence: `README.md`)
- RISC-V core → Fetch-decode-execute: executes through (evidence: `README.md`)
- Fetch-decode-execute → Register file: uses
- Fetch-decode-execute → Instruction decode: uses
- Fetch-decode-execute → Execute unit: uses
- Execute unit → Divide unit: supports division
- RISC-V core → CSR registers: supports CSR (evidence: `README.md`)
- SoC top → RIB bus: uses bus (evidence: `README.md`)
- SoC top → ROM: integrates
- SoC top → RAM: integrates
- SoC top → Timer: integrates
- SoC top → GPIO: integrates
- SoC top → SPI master: integrates
- SoC top → UART: integrates
- SoC top → JTAG debug: supports debug (evidence: `README.md`)
- SoC top → UART updater: supports updates (evidence: `README.md`)
- Serial downloader → FPGA board: sends firmware (evidence: `tools/tinyriscv_fw_downloader.py`)
- FreeRTOS port → SoC top: runs on (evidence: `README.md`)
