# thethirdone/rars architecture

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

- Interactive diagram: https://gitdiagram.com/thethirdone/rars
- Repository: https://github.com/thethirdone/rars

## Overview

##### Main Components
- Assembler Module:
- Components: Tokenizer, parser, macro processor (see src/rars/assembler with classes like Assembler.java, Macro.java, Tokenizer.java, etc.), and support for multiple file assembly.
- Inputs: Assembly source code (from examples/ and test/ directories).
- Outputs: Machine code / intermediate representations that feed into the simulation engine.

- Simulator / Runtime Engine:
- Components: Simulation core in src/rars/simulator (Simulator.java and its supporting classes) that emulates program execution.
- Interactions: Communicates with the hardware simulation module to manipulate memory, registers, and interrupts.

- RISC-V Instruction Set & Hardware Simulation:
- Components: Packages under src/rars/riscv including:
- Instructions (classes for ADD, SUB, Branch, etc. under src/rars/riscv/instructions).
- System call definitions (in src/rars/riscv/syscalls).
- Hardware emulation components (in src/rars/riscv/hardware such as Memory.java, RegisterFile.java, and InterruptController.java).
- Role: Defines the behavior of individual instructions and low-level hardware mimicking.

- Graphical User Interface (GUI) & Debugger:
- Components: Located in the src/rars/venus package, the ‘venus’ module handles editor windows, registers display (src/rars/venus/registers), and simulation controls.
- Features: Editing, debugging (breakpoints, stepping), visualizations of memory segments, and user interaction panels.

- Plug-in Tools & Extensions:
- Components: src/rars/tools contains various simulators and visualization tools (e.g., CacheSimulator, TimerTool, BitmapDisplay).
- Interactions: They may hook into the simulation runtime showing modularity and extensibility.

- API and Configuration:
- Components: src/rars/api (to expose programmatic access) and configuration files (e.g., Config.properties, Settings.properties, Syscall.properties) that manage runtime and system configurations.
- Role: Allow integration and customization of the simulator’s behavior.

##### Interactions & Relationships
- The user interacts (via the GUI or CLI launcher like Launch.java) with the front-end.
- Front-end modules (from the venus package) send assembly source and simulation commands to the core assembler and simulator.
- The Assembler module (scanner, parser, macro expansion) converts code into machine-level instructions.
- The Simulator executes these instructions by invoking the RISC-V instruction classes, which in turn interact with the hardware simulation layer.
- The hardware layer manages memory, registers, and device simulation, ensuring that system calls (found in the syscalls module) correctly mimic operating system behavior.
- Tools and utilities are available as plug-ins, visible in their own module (src/rars/tools), and can be hot-loaded to extend the instruction set or functionality.
- The API provides programmatic control and extension points, and the configuration files set parameters for various components at runtime.

##### Architectural Patterns and Design Principles
- Modular Design: Clear separation into modules for assembling, running, and interacting with programs.
- Extensibility: The Tools package indicates use of plug-in architecture, and instructions being hot-loaded shows dynamic compenents.
- Configuration Driven: The presence of many properties files signals that runtime behavior is heavily configurable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Assembly Source Files (examples/, test/)"]:::external
    B["Assembler Module"]:::assembler
    C["Machine Code / Intermediate Representation"]:::process
    D["Simulator / Runtime Engine"]:::simulator
    E["RISC-V Instruction Set Implementation"]:::riscv
    F["Hardware Emulation"]:::hardware
    G["GUI & Debugger"]:::gui
    H["Plug-in Tools & Extensions"]:::tools

    subgraph "API & Configuration"
        I0["API & Configuration"]:::api
        I1["Config.properties"]:::api
        I2["Settings.properties"]:::api
        I3["Syscall.properties"]:::api
    end

    A -->|"input"| B
    B -->|"assembles_to"| C
    C -->|"feeds"| D
    D <-->|"executes"| E
    D <-->|"manages"| F

    G -->|"sendsAssembly"| B
    G -->|"sendsCommands"| D
    H -->|"extends"| D

    I0 -->|"configures"| B
    I0 -->|"configures"| D
    I0 -->|"configures"| E
    I0 -->|"configures"| F
    I0 -->|"configures"| G
    I0 -->|"configures"| H

    I0 --> I1
    I0 --> I2
    I0 --> I3

    %% Click Events
    click B "https://github.com/thethirdone/rars/tree/master/src/rars/assembler"
    click D "https://github.com/thethirdone/rars/blob/master/src/rars/simulator/Simulator.java"
    click E "https://github.com/thethirdone/rars/tree/master/src/rars/riscv/instructions"
    click F "https://github.com/thethirdone/rars/tree/master/src/rars/riscv/hardware"
    click G "https://github.com/thethirdone/rars/tree/master/src/rars/venus"
    click H "https://github.com/thethirdone/rars/tree/master/src/rars/tools"
    click I0 "https://github.com/thethirdone/rars/tree/master/src/rars/api"
    click I1 "https://github.com/thethirdone/rars/blob/master/src/Config.properties"
    click I2 "https://github.com/thethirdone/rars/blob/master/src/Settings.properties"
    click I3 "https://github.com/thethirdone/rars/blob/master/src/Syscall.properties"

    %% Classes and Colors
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef assembler fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef process fill:#E0FFFF,stroke:#000,stroke-width:2px;
    classDef simulator fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef riscv fill:#FF8C00,stroke:#000,stroke-width:2px;
    classDef hardware fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef gui fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef tools fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef api fill:#F5DEB3,stroke:#000,stroke-width:2px;
```
