# 0bab1/holy_core_course architecture

> Architecture diagram of the GitHub repository 0bab1/holy_core_course, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0bab1/holy_core_course
- Repository: https://github.com/0bab1/holy_core_course

## Overview

##### Project Type & Purpose
- This is an **educational**, open-source 32-bit RISC-V core project (“HOLY CORE”) organized into multiple learning “editions”:
- Single-cycle edition (fully combinational fetch–decode–execute in one cycle)
- FPGA edition (adds cache, AXI, I/O and targets a Zybo Z720 board)
- The goal is to teach digital-design fundamentals in SystemVerilog with a cocotb-based test workflow, then show how to synthesize and run on FPGA.

##### Directory Structure Analysis
a. Top-level artifacts
– setup.md, readme.md, LICENSE, CI workflow, .gitignore
– ref_tables.pdf, images/ (docs & banners)
b. Edition folders
– single_cycle_edition/
· src/ (alu.sv, control.sv, cpu.sv, load_store_decoder.sv, memory.sv, reader.sv, regfile.sv, signext.sv)
· packages/ (holy_core_pkg.sv)
· tb/ (cocotb tests in Python + Makefiles + small SV harnesses)
– fpga_edition/
· src/ (same CPU building blocks + holy_cache.sv + external_req_arbitrer.sv)
· packages/ (AXI interface pkg, core pkg)
· fpga/ (holy_wrapper.v, AXI details, Vivado .tcl & constraints)
· test_programs/ (assembly test scripts for on-board runs)
· tb/ (extended cocotb testbenches + SV translators)
c. Tooling & configs
– Makefiles per module for simulation
– Python/cocotb test runners
– Vivado/TCL scripts for FPGA build
– CI pipeline triggers simulation tests

##### Key Components
- Core datapath blocks: ALU, Control Unit, Register File, Sign-Extender, Load/Store Decoder, Memory Interface
- Packaging: holy_core.sv as top-level CPU instantiation
- FPGA wrapper: holy_wrapper.v exposes AXI bus, connects to holy_cache.sv and external_req_arbitrer.sv
- External interfaces:
- On-chip memory (BRAM) + Cache + AXI4 master
- GPIO / LEDs on Zybo Z720
- Host-side cocotb harness (Python + Makefile) for simulation
- Tools & workflows:
- Simulation flow (cocotb + Python)
- Synthesis/Implementation flow (Vivado via TCL)

##### Relationships & Data Flow
- In **simulation**: Python testbenches drive SV test harness → instantiate core modules → connect to model memory or AXI translators → observe outputs via cocotb.
- In **FPGA**: holy_wrapper.v sits at top, instantiates holy_core + holy_cache + external_req_arbitrer → AXI master drives external DDR → I/O pins map to constraints.xdc → Vivado bitstream → Zybo board.
- Within the core: Instruction fetch → Reader → Sign-Extender → Control → ALU → Memory interface → Register writeback.

##### Architectural Patterns & Principles
- Modular RTL blocks in SystemVerilog, packaged by functionality
- Clear separation of concerns: datapath vs control vs bus interfacing
- Test-driven design: cocotb harnesses wrap each block under test
- Two distinct build flows (simulation vs FPGA) with separate toolchains

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Swimlanes
    subgraph "Simulation Layer" 
        direction TB
        cocotb["cocotb (Python)"]:::sim
        sv_tb["SV Testbench"]:::sim
        cocotb -->|"drives"| sv_tb
        sv_tb -->|"instantiates"| Core["Core (single-cycle edition)"]:::core
    end

    subgraph "Hardware Layer"
        direction TB
        vivado["Vivado/TCL"]:::hw
        holy_wrapper["holy_wrapper.v"]:::hw
        holy_wrapper -->|"instantiates"| holy_core["holy_core"]:::core
        holy_wrapper -->|"connects to"| holy_cache["holy_cache"]:::hw
        holy_wrapper -->|"connects to"| arbiter["external_req_arbitrer"]:::hw
        holy_cache -->|"AXI4"| DDR["External DDR"]:::ext
        arbiter -->|"AXI4"| DDR
        holy_wrapper -->|"I/O pins"| GPIO["GPIO/LED"]:::ext
        vivado -->|"synth/impl"| holy_wrapper
    end

    %% Core datapath
    subgraph "Core Internals" 
        direction TB
        IF["Instruction Fetch (reader)"]:::core
        SE["Sign-Extender"]:::core
        CU["Control Unit"]:::core
        ALU["ALU"]:::core
        MEM_IF["Memory Interface"]:::core
        RF["Register File"]:::core

        IF -->|"instr"| SE
        SE -->|"imm"| CU
        CU -->|"ctrl"| ALU
        SE -->|"op2"| ALU
        ALU -->|"addr/data"| MEM_IF
        MEM_IF -->|"data"| RF
        CU -->|"regwrite"| RF
    end

    Core --> IF
    Core --> SE
    Core --> CU
    Core --> ALU
    Core --> MEM_IF
    Core --> RF

    %% Packages
    subgraph "SV Packages" 
        direction TB
        core_pkg["holy_core_pkg"]:::pkg
        axi_pkg["AXI Interface pkg"]:::pkg
    end

    holy_core --> core_pkg
    holy_cache --> axi_pkg

    %% Testbench memory models
    subgraph "Memory Models" 
        direction TB
        mem_model["Model Memory / AXI Translator"]:::sim
    end
    sv_tb --> mem_model
    mem_model --> Core

    %% Build & CI
    subgraph "Tooling & CI"
        direction TB
        make["Makefile"]:::tool
        ci["CI Workflow"]:::tool
    end
    make --> sv_tb
    ci --> make

    %% Click Events
    click ALU "https://github.com/0bab1/holy_core_course/blob/master/single_cycle_edition/src/alu.sv"
    click ALU "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/src/alu.sv"
    click CU "https://github.com/0bab1/holy_core_course/blob/master/single_cycle_edition/src/control.sv"
    click CU "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/src/control.sv"
    click RF "https://github.com/0bab1/holy_core_course/blob/master/single_cycle_edition/src/regfile.sv"
    click RF "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/src/regfile.sv"
    click SE "https://github.com/0bab1/holy_core_course/blob/master/single_cycle_edition/src/signext.sv"
    click SE "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/src/signext.sv"
    click MEM_IF "https://github.com/0bab1/holy_core_course/blob/master/single_cycle_edition/src/memory.sv"
    click MEM_IF "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/src/memory.sv"
    click IF "https://github.com/0bab1/holy_core_course/blob/master/single_cycle_edition/src/reader.sv"
    click IF "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/src/reader.sv"
    click Core "https://github.com/0bab1/holy_core_course/blob/master/single_cycle_edition/src/cpu.sv"
    click holy_core "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/src/holy_core.sv"
    click core_pkg "https://github.com/0bab1/holy_core_course/blob/master/single_cycle_edition/packages/holy_core_pkg.sv"
    click core_pkg "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/packages/holy_core_pkg.sv"
    click axi_pkg "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/packages/axi_if.sv"
    click holy_cache "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/src/holy_cache.sv"
    click arbiter "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/src/external_req_arbitrer.sv"
    click holy_wrapper "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/fpga/holy_wrapper.v"
    click DDR "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/fpga/axi_details.sv"
    click GPIO "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/fpga/zybo_z720/constraints.xdc"
    click vivado "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/fpga/zybo_z720/holy_vivado_setup.tcl"
    click make "https://github.com/0bab1/holy_core_course/tree/master/single_cycle_edition/Makefile"
    click make "https://github.com/0bab1/holy_core_course/tree/master/fpga_edition/Makefile"
    click ci "https://github.com/0bab1/holy_core_course/blob/master/.github/workflows/ci.yml"
    click cocotb "https://github.com/0bab1/holy_core_course/blob/master/single_cycle_edition/tb/test_runner.py"
    click cocotb "https://github.com/0bab1/holy_core_course/blob/master/fpga_edition/tb/test_runner.py"

    %% Styles
    classDef sim fill:#FFE4B5,stroke:#CD853F
    classDef hw fill:#E0FFFF,stroke:#20B2AA
    classDef core fill:#FFFACD,stroke:#DAA520
    classDef pkg fill:#E6E6FA,stroke:#9370DB
    classDef ext fill:#F0FFF0,stroke:#32CD32
    classDef tool fill:#F5F5F5,stroke:#A9A9A9
```
