How adn-vlsi/sc-soc works
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: sc_soc.sv SC SoC · sc_soc_tb.sv SoC TB · Makefile Build Flow · ctrl_subsystem.sv Ctrl Subsys
Components 21
SoC Integration
Top-level RTL that binds CPU, memory, peripherals, and control logic.
- SC SoC · Main SoC integration point that ties the CPU to memory, peripherals, and control logic.
hardware/source/sc_soc.sv - Ctrl Subsys · Control-plane subsystem that aggregates register blocks and SoC-side control logic.
hardware/source/ctrl_subsystem.sv - RV32IMF Core · RISC-V processor submodule brought in as an external dependency rather than implemented here.
submodule/rv32imf - Build Flow · 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 · AXI4-Lite accessible memory block used as a control-plane storage target.
hardware/source/axi4l_mem.sv - Mem Ctrlr · Translates AXI4-Lite transactions into a simpler memory interface.
hardware/source/axi4l_mem_ctrlr.sv - AXI4L to Mem · Bridge between AXI4-Lite and the internal memory interface used by storage blocks.
hardware/source/axi4l_to_memif.sv - AXI4L CLINT · AXI4-Lite controlled core-local interrupt and timer block.
hardware/source/axi4l_clint.sv - UART RegIF · AXI4-Lite register layer for UART control and status access.
hardware/source/axi4l_uart_regif.sv - Ctrl RegIF · AXI4-Lite register layer for system control and configuration registers.
hardware/source/axi4l_ctrl_regif.sv - UART Subsys · UART wrapper that combines transmit, receive, and control-plane logic.
hardware/source/uart_subsystem.sv - GPIO · General-purpose input/output peripheral for external pins and control.
hardware/source/gpio.sv - Mem Core · Underlying RAM/FIFO-style storage building blocks used by memory-facing wrappers.
hardware/source/mem.sv - Clocking & CDC · Clock division, muxing, synchronization, FIFO crossing, and encoding helpers.
hardware/source/clk_div.sv - Interfaces · SystemVerilog protocol interfaces for AXI4-Lite, APB, and UART.
hardware/interface/axi4l_if.sv - Packages · 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 · Reusable AXI4-Lite and valid/ready verification components.
hardware/include/vip/axi4l.svh - SoC TB · Top-level SoC simulation environment and regression harness.
hardware/testbench/sc_soc_tb.sv - Block TBs · Representative testbenches for memory, UART, CLINT, GPIO, and utility RTL blocks.
hardware/testbench/axi4l_mem_tb.sv - Test Assets · 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 · C and assembly programs, startup code, and support libraries used as simulation stimuli.
software/source/hello.c
Connections 22
- 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.