# adn-vlsi/sc-soc architecture

> Architecture diagram of the GitHub repository adn-vlsi/sc-soc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adn-vlsi/sc-soc
- Repository: https://github.com/adn-vlsi/sc-soc

## Overview

1. **What this repo is**
   SC-SoC is a mixed hardware/software repository for a single-core RISC-V SoC. The architectural center is an RV32IMF CPU core brought in as a submodule, surrounded by reusable RTL IP, subsystem integration, and simulation-based verification.

2. **Top-level integration boundary**
   The main SoC entry points are `hardware/source/sc_soc.sv` and `hardware/source/ctrl_subsystem.sv`. These tie the CPU to control logic, memory, UART, GPIO, clocking, and SoC-specific register blocks, forming the integration layer above the reusable leaf modules.

3. **Core compute subsystem**
   The CPU is not implemented in this repo; it lives in `submodule/rv32imf/` and is compiled through `hardware/filelist/rv32imf.f`. That makes the processor an external architectural dependency, while this repo owns the bus fabric, peripherals, and the surrounding system integration.

4. **Control-plane and register-access blocks**
   A major theme is AXI4-Lite-controlled peripherals: `axi4l_clint`, `axi4l_mem`, `axi4l_uart_regif`, and `axi4l_ctrl_regif`. These modules expose structured memory-mapped register interfaces and are paired with generated-style “regif” layers that separate bus decoding from functional logic.

5. **Memory subsystem**
   Memory support is split into generic storage blocks (`mem`, `dual_port_mem`) and bus-facing wrappers (`axi4l_mem_ctrlr`, `axi4l_to_memif`, `axi4l_mem`). The data flow is typically: AXI4-Lite transactions enter a controller/adapter, get translated into a simpler memory interface, and then reach the underlying RAM or FIFO-like storage.

6. **Peripheral and I/O subsystem**
   The repo includes UART transmit/receive logic, a UART subsystem wrapper, GPIO, and I/O pad utilities. This suggests a conventional SoC I/O boundary where peripheral logic is separated from pad/control adaptation, with UART being the clearest externally visible streaming interface.

7. **Clocking, CDC, and utility IP**
   Supporting RTL includes `clk_div`, `clk_mux`, `cdc_fifo`, `dual_edge_reg`, `delay_gen`, `bin_2_gray`, `gray_2_bin`, and `fifo`. These are reusable infrastructure blocks used to solve timing, clock-domain crossing, buffering, and encoding/decoding problems across the SoC and testbenches.

8. **Interface and package layer**
   `hardware/interface/` defines SystemVerilog interfaces for AXI4-Lite, APB, and UART, while `hardware/include/package/` holds shared parameter and type packages. This is the architectural boundary that keeps protocol wiring and common constants consistent across RTL, VIP, and testbench code.

9. **Verification architecture**
   Each major block has a dedicated testbench under `hardware/testbench/`, often with many scenario files (`tc*.sv`) and method variants. The verification flow uses reusable VIP in `hardware/include/vip/` for AXI4-Lite and valid/ready behavior, plus waveform configs in `wcfg/` and documentation in `document/`.

10. **Software bring-up path**
    `software/source/` and `software/include/` contain bare-metal RISC-V C/assembly programs, startup code, and simple support libraries. These programs are linked with `software/linkers/core.ld` and compiled into simulation artifacts, so software acts as a stimulus/validation layer for the SoC and peripherals.

11. **Build and simulation tooling**
    The top-level `Makefile` drives compilation and simulation through Xilinx tools (`xvlog`, `xelab`, `xsim`) and can also build RISC-V software with the GNU embedded toolchain. Filelists in `hardware/filelist/` define compilation boundaries for common cells, APB, AXI, SoC integration, and the CPU submodule.

12. **Repository-level flow**
    The practical flow is: develop RTL in `hardware/source/`, connect it through interfaces/packages, verify it in a matching testbench, and use software tests or SoC-level benches to validate integration. The documentation set mirrors this structure, so each reusable block and subsystem has a dedicated architectural note and verification note.

Main entry points: [`hardware/source/sc_soc.sv`](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/sc_soc.sv) (SC SoC), [`hardware/testbench/sc_soc_tb.sv`](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/testbench/sc_soc_tb.sv) (SoC TB), [`Makefile`](https://github.com/adn-vlsi/sc-soc/tree/main/Makefile) (Build Flow), [`hardware/source/ctrl_subsystem.sv`](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/ctrl_subsystem.sv) (Ctrl Subsys)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_top["SoC Integration"]
  node_sc_soc["SC SoC<br/>top-level SoC<br/>[sc_soc.sv]"]
  node_ctrl_subsystem["Ctrl Subsys<br/>integration block<br/>[ctrl_subsystem.sv]"]
  node_rv32imf_core["RV32IMF Core<br/>external CPU"]
  node_build{{"Build Flow<br/>tooling"}}
end

subgraph group_rtl["Reusable RTL"]
  node_axi4l_mem[("AXI4L Mem<br/>bus memory<br/>[axi4l_mem.sv]")]
  node_axi4l_mem_ctrlr["Mem Ctrlr<br/>bus adapter<br/>[axi4l_mem_ctrlr.sv]"]
  node_axi4l_to_memif["AXI4L to Mem<br/>protocol bridge<br/>[axi4l_to_memif.sv]"]
  node_axi4l_clint["AXI4L CLINT<br/>timer/interrupt<br/>[axi4l_clint.sv]"]
  node_axi4l_uart_regif["UART RegIF<br/>register interface"]
  node_axi4l_ctrl_regif["Ctrl RegIF<br/>register interface"]
  node_uart_subsystem["UART Subsys<br/>serial peripheral<br/>[uart_subsystem.sv]"]
  node_gpio["GPIO<br/>digital I/O<br/>[gpio.sv]"]
  node_memory_core[("Mem Core<br/>storage primitives<br/>[mem.sv]")]
  node_clock_cdc{{"Clocking & CDC<br/>utility IP<br/>[clk_div.sv]"}}
  node_interfaces["Interfaces<br/>[axi4l_if.sv]"]
  node_packages["Packages<br/>shared params<br/>[sc_soc_pkg.sv]"]
end

subgraph group_verif["Verification"]
  node_vip["VIP<br/>verification IP<br/>[axi4l.svh]"]
  node_soc_tb["SoC TB<br/>system testbench<br/>[sc_soc_tb.sv]"]
  node_peripheral_tbs["Block TBs<br/>module testbenches<br/>[axi4l_mem_tb.sv]"]
  node_test_assets["Test Assets<br/>simulation support<br/>[sc_soc_tb.wcfg]"]
end

subgraph group_sw["Software"]
  node_software["Bare-metal SW<br/>bring-up code<br/>[hello.c]"]
end

node_sc_soc -->|"instantiates"| node_rv32imf_core
node_sc_soc -->|"connects"| node_ctrl_subsystem
node_sc_soc -->|"connects"| node_uart_subsystem
node_sc_soc -->|"maps"| node_axi4l_mem
node_ctrl_subsystem -->|"contains"| node_axi4l_clint
node_ctrl_subsystem -->|"contains"| node_axi4l_ctrl_regif
node_uart_subsystem -->|"contains"| node_axi4l_uart_regif
node_axi4l_mem -->|"uses"| node_axi4l_mem_ctrlr
node_axi4l_mem_ctrlr -->|"adapts"| node_axi4l_to_memif
node_axi4l_to_memif -->|"targets"| node_memory_core
node_axi4l_clint -->|"depends on"| node_clock_cdc
node_uart_subsystem -->|"depends on"| node_clock_cdc
node_gpio -->|"uses"| node_interfaces
node_interfaces -->|"shares types"| node_packages
node_vip -->|"drives"| node_interfaces
node_soc_tb -->|"uses"| node_vip
node_soc_tb -->|"runs"| node_software
node_peripheral_tbs -->|"uses"| node_vip
node_build -->|"drives"| node_soc_tb
node_build -->|"builds"| node_software
node_build -->|"includes"| node_rv32imf_core
node_test_assets -->|"supports"| node_soc_tb

click node_sc_soc "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/sc_soc.sv"
click node_ctrl_subsystem "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/ctrl_subsystem.sv"
click node_rv32imf_core "https://github.com/adn-vlsi/sc-soc/tree/main/submodule/rv32imf"
click node_axi4l_mem "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_mem.sv"
click node_axi4l_mem_ctrlr "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_mem_ctrlr.sv"
click node_axi4l_to_memif "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_to_memif.sv"
click node_axi4l_clint "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_clint.sv"
click node_axi4l_uart_regif "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_uart_regif.sv"
click node_axi4l_ctrl_regif "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_ctrl_regif.sv"
click node_uart_subsystem "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/uart_subsystem.sv"
click node_gpio "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/gpio.sv"
click node_memory_core "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/mem.sv"
click node_clock_cdc "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/clk_div.sv"
click node_interfaces "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/interface/axi4l_if.sv"
click node_packages "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/include/package/sc_soc_pkg.sv"
click node_vip "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/include/vip/axi4l.svh"
click node_soc_tb "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/testbench/sc_soc_tb.sv"
click node_peripheral_tbs "https://github.com/adn-vlsi/sc-soc/blob/main/hardware/testbench/axi4l_mem_tb.sv"
click node_test_assets "https://github.com/adn-vlsi/sc-soc/blob/main/wcfg/sc_soc_tb.wcfg"
click node_software "https://github.com/adn-vlsi/sc-soc/blob/main/software/source/hello.c"
click node_build "https://github.com/adn-vlsi/sc-soc/tree/main/Makefile"

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_sc_soc,node_ctrl_subsystem,node_rv32imf_core,node_build toneBlue
class node_axi4l_mem,node_axi4l_mem_ctrlr,node_axi4l_to_memif,node_axi4l_clint,node_axi4l_uart_regif,node_axi4l_ctrl_regif,node_uart_subsystem,node_gpio,node_memory_core,node_clock_cdc,node_interfaces,node_packages toneAmber
class node_vip,node_soc_tb,node_peripheral_tbs,node_test_assets toneMint
class node_software toneRose
```

## Components

### SoC Integration

Top-level RTL that binds CPU, memory, peripherals, and control logic.

- [SC SoC](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/sc_soc.sv): top-level SoC · Main SoC integration point that ties the CPU to memory, peripherals, and control logic. · `hardware/source/sc_soc.sv`
- [Ctrl Subsys](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/ctrl_subsystem.sv): integration block · Control-plane subsystem that aggregates register blocks and SoC-side control logic. · `hardware/source/ctrl_subsystem.sv`
- [RV32IMF Core](https://github.com/adn-vlsi/sc-soc/tree/main/submodule/rv32imf): external CPU · RISC-V processor submodule brought in as an external dependency rather than implemented here. · `submodule/rv32imf`
- [Build Flow](https://github.com/adn-vlsi/sc-soc/tree/main/Makefile): tooling · Makefile-driven compilation and simulation flow, including HDL compilation and software builds. · `Makefile`

### Reusable RTL

Shared hardware blocks, buses, peripherals, and infrastructure IP.

- [AXI4L Mem](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_mem.sv): bus memory · AXI4-Lite accessible memory block used as a control-plane storage target. · `hardware/source/axi4l_mem.sv`
- [Mem Ctrlr](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_mem_ctrlr.sv): bus adapter · Translates AXI4-Lite transactions into a simpler memory interface. · `hardware/source/axi4l_mem_ctrlr.sv`
- [AXI4L to Mem](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_to_memif.sv): protocol bridge · Bridge between AXI4-Lite and the internal memory interface used by storage blocks. · `hardware/source/axi4l_to_memif.sv`
- [AXI4L CLINT](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_clint.sv): timer/interrupt · AXI4-Lite controlled core-local interrupt and timer block. · `hardware/source/axi4l_clint.sv`
- [UART RegIF](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_uart_regif.sv): register interface · AXI4-Lite register layer for UART control and status access. · `hardware/source/axi4l_uart_regif.sv`
- [Ctrl RegIF](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/axi4l_ctrl_regif.sv): register interface · AXI4-Lite register layer for system control and configuration registers. · `hardware/source/axi4l_ctrl_regif.sv`
- [UART Subsys](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/uart_subsystem.sv): serial peripheral · UART wrapper that combines transmit, receive, and control-plane logic. · `hardware/source/uart_subsystem.sv`
- [GPIO](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/gpio.sv): digital I/O · General-purpose input/output peripheral for external pins and control. · `hardware/source/gpio.sv`
- [Mem Core](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/mem.sv): storage primitives · Underlying RAM/FIFO-style storage building blocks used by memory-facing wrappers. · `hardware/source/mem.sv`
- [Clocking & CDC](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/source/clk_div.sv): utility IP · Clock division, muxing, synchronization, FIFO crossing, and encoding helpers. · `hardware/source/clk_div.sv`
- [Interfaces](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/interface/axi4l_if.sv): sv interfaces · SystemVerilog protocol interfaces for AXI4-Lite, APB, and UART. · `hardware/interface/axi4l_if.sv`
- [Packages](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/include/package/sc_soc_pkg.sv): shared params · Common parameter and type packages shared across RTL and verification. · `hardware/include/package/sc_soc_pkg.sv`

### Verification

Testbenches, VIP, and simulation assets used to validate the RTL.

- [VIP](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/include/vip/axi4l.svh): verification IP · Reusable AXI4-Lite and valid/ready verification components. · `hardware/include/vip/axi4l.svh`
- [SoC TB](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/testbench/sc_soc_tb.sv): system testbench · Top-level SoC simulation environment and regression harness. · `hardware/testbench/sc_soc_tb.sv`
- [Block TBs](https://github.com/adn-vlsi/sc-soc/blob/main/hardware/testbench/axi4l_mem_tb.sv): module testbenches · Representative testbenches for memory, UART, CLINT, GPIO, and utility RTL blocks. · `hardware/testbench/axi4l_mem_tb.sv`
- [Test Assets](https://github.com/adn-vlsi/sc-soc/blob/main/wcfg/sc_soc_tb.wcfg): simulation support · Waveform configs, scenario files, and local testbench helpers used in simulation. · `wcfg/sc_soc_tb.wcfg`

### Software

Bare-metal programs and runtime support used for bring-up and simulation stimulus.

- [Bare-metal SW](https://github.com/adn-vlsi/sc-soc/blob/main/software/source/hello.c): bring-up code · C and assembly programs, startup code, and support libraries used as simulation stimuli. · `software/source/hello.c`

## Connections

- SC SoC → RV32IMF Core: instantiates · The SoC integrates the external CPU core as its compute engine.
- SC SoC → Ctrl Subsys: connects · Top-level SoC wiring brings in the control subsystem.
- SC SoC → UART Subsys: connects · SoC routes serial I/O through the UART subsystem.
- SC SoC → AXI4L Mem: maps · Top-level integration exposes memory-mapped storage to the system fabric.
- Ctrl Subsys → AXI4L CLINT: contains · Control subsystem includes timer/interrupt functionality.
- Ctrl Subsys → Ctrl RegIF: contains · Control subsystem exposes its register access layer.
- UART Subsys → UART RegIF: contains · UART subsystem is controlled through an AXI4-Lite register interface.
- AXI4L Mem → Mem Ctrlr: uses · Memory block is accessed through a dedicated bus controller.
- Mem Ctrlr → AXI4L to Mem: adapts · Controller delegates protocol translation to a memory-interface bridge.
- AXI4L to Mem → Mem Core: targets · Translated requests reach the underlying storage primitives.
- AXI4L CLINT → Clocking & CDC: depends on · Timer/interrupt logic relies on clocking and synchronization utilities.
- UART Subsys → Clocking & CDC: depends on · UART logic uses buffering and timing support blocks.
- GPIO → Interfaces: uses · Peripheral wiring is standardized through shared protocol interfaces.
- Interfaces → Packages: shares types · Interfaces depend on common parameters and type definitions.
- VIP → Interfaces: drives · Verification components exercise the same bus and stream interfaces as RTL.
- SoC TB → VIP: uses · Top-level testbench uses VIP for stimulus and checking.
- SoC TB → Bare-metal SW: runs · Simulation can boot and execute bare-metal software payloads.
- Block TBs → VIP: uses · Module-level benches use reusable verification agents.
- Build Flow → SoC TB: drives · Build flow compiles and launches the top-level simulation.
- Build Flow → Bare-metal SW: builds · Tooling also compiles embedded software for simulation runs.
- Build Flow → RV32IMF Core: includes · Filelists include the CPU submodule as part of the HDL build.
- Test Assets → SoC TB: supports · Wave configs and scenario assets support SoC verification.