# elaine-ch/comparch-project architecture

> Architecture diagram of the GitHub repository elaine-ch/comparch-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elaine-ch/comparch-project
- Repository: https://github.com/elaine-ch/comparch-project

## Overview

##### Project type and purpose
- This is a hybrid tool‐chain + hardware design project for a simple CPU in SystemVerilog, accompanied by a Java‐based assembler.
- The Java assembler (in Assembler/) translates .sv assembly text into machine code and JLUT entries. The hardware RTL (in “SystemVerilog code/” and “myHardware/”) implements the CPU datapath and control. Testbenches (in testbenches/) simulate the design with the generated machine code.

##### File structure
Top level:
- Assembler/ – Java source (Assembler.java, Converter.java, Translator.java, CommentRemover.java) plus sample assembly input and machine‐code outputs.
- Programs/ – Example SV programs, data memory initial contents, input test cases and their text‐based JLUT and machine‐code files.
- SystemVerilog code/ and myHardware/ – RTL modules of the CPU: ALU.sv, Ctrl.sv, DatMem.sv, InstROM.sv, JLUT.sv, ProgCtr.sv, RegFile.sv, Top.sv, mux2x1.sv.
- testbenches/ – SV testbenches for individual modules and full CPU runs.

Architectural patterns:
- A two‐stage toolchain: assembler → hardware.
- A simple single‐cycle CPU datapath with separate instruction ROM (InstROM) and jump‐lookup (JLUT).
- Manual post‐processing step for branch target resolution (labels and beq conversions).

##### Insights from the README
- Core workflow: edit assembly1.txt → run Java assembler → get mach_code1.txt + jlut.txt → manually fix branch instructions/labels → update InstROM.sv and JLUT.sv → run SV testbench.
- No CI/CD or automated integration; the code-to-hardware handoff is file‐based.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Java Assembler Inputs
    assembly0(("assembly0.txt")):::files
    assembly1(("assembly1.txt")):::files

    %% Java Assembler Tool
    subgraph "Java Assembler Tool"
        direction TB
        Asm["Assembler.java"]:::java
        Conv["Converter.java"]:::java
        Trans["Translator.java"]:::java
        Comm["CommentRemover.java"]:::java
    end

    assembly0 --> Asm
    assembly1 --> Asm

    %% Assembler Outputs
    subgraph "Assembler Outputs"
        direction TB
        clean0(("clean_assembly0.txt")):::files
        clean1(("clean_assembly1.txt")):::files
        mc0(("machine_code0.txt")):::files
        mc1(("machine_code1.txt")):::files
        jlut(("jlut.txt")):::files
    end

    Asm --> clean0
    Asm --> clean1
    Asm --> mc0
    Asm --> mc1
    Asm --> jlut

    %% Manual Step
    manual["Manual branch target resolution"]:::manual

    mc0 --> manual
    mc1 --> manual
    jlut --> manual

    %% File-based Interface to RTL
    mc0 --> InstROM
    mc1 --> InstROM
    jlut --> JLUT

    %% CPU RTL Modules
    subgraph "CPU (SystemVerilog)" 
        direction TB
        Top["Top.sv"]:::hardware
        subgraph "Memory Modules"
            direction TB
            InstROM["InstROM.sv"]:::hardware
            JLUT["JLUT.sv"]:::hardware
        end
        subgraph "Core Units"
            direction TB
            PC["ProgCtr.sv"]:::hardware
            RF["RegFile.sv"]:::hardware
            ALU["ALU.sv"]:::hardware
            DM["DatMem.sv"]:::hardware
            MUX["mux2x1.sv"]:::hardware
            CU["Ctrl.sv"]:::hardware
        end
        InstROM --> Top
        JLUT --> Top
        Top --> PC
        Top --> RF
        Top --> ALU
        Top --> DM
        Top --> MUX
        Top --> CU
        CU --> ALU
        CU --> RF
        CU --> DM
    end

    %% Testbenches
    subgraph "Testbench Harnesses"
        direction TB
        ALU_tb["ALU_tb.sv"]:::testbench
        ProgCtr_tb["ProgCtr_tb.sv"]:::testbench
        JLUT_tb["JLUT_tb.sv"]:::testbench
        InstrRom_tb["InstrRom_tb.sv"]:::testbench
        full_tb["program2_tb.sv"]:::testbench
    end

    ALU_tb --> ALU
    ProgCtr_tb --> PC
    JLUT_tb --> JLUT
    InstrRom_tb --> InstROM
    full_tb --> Top

    classDef java fill:#ADD8E6,stroke:#333
    classDef files fill:#B0E0E6,stroke:#333,stroke-dasharray: 2 2
    classDef hardware fill:#98FB98,stroke:#333
    classDef testbench fill:#FFA500,stroke:#333
    classDef manual fill:#D3D3D3,stroke:#333,stroke-dasharray: 5 5

    %% Click Events for Java Assembler
    click Asm "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/Assembler.java"
    click Conv "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/Converter.java"
    click Trans "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/Translator.java"
    click Comm "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/CommentRemover.java"
    click assembly0 "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/assembly0.txt"
    click assembly1 "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/assembly1.txt"
    click clean0 "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/clean_assembly0.txt"
    click clean1 "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/clean_assembly1.txt"
    click mc0 "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/machine_code0.txt"
    click mc1 "https://github.com/elaine-ch/comparch-project/blob/main/Assembler/machine_code1.txt"

    %% Click Events for RTL Modules
    click InstROM "https://github.com/elaine-ch/comparch-project/blob/main/SystemVerilog code/InstROM.sv"
    click JLUT "https://github.com/elaine-ch/comparch-project/blob/main/SystemVerilog code/JLUT.sv"
    click PC "https://github.com/elaine-ch/comparch-project/blob/main/SystemVerilog code/ProgCtr.sv"
    click RF "https://github.com/elaine-ch/comparch-project/blob/main/SystemVerilog code/RegFile.sv"
    click ALU "https://github.com/elaine-ch/comparch-project/blob/main/SystemVerilog code/ALU.sv"
    click DM "https://github.com/elaine-ch/comparch-project/blob/main/SystemVerilog code/DatMem.sv"
    click MUX "https://github.com/elaine-ch/comparch-project/blob/main/SystemVerilog code/mux2x1.sv"
    click CU "https://github.com/elaine-ch/comparch-project/blob/main/SystemVerilog code/Ctrl.sv"
    click Top "https://github.com/elaine-ch/comparch-project/blob/main/SystemVerilog code/Top.sv"
```
