# qazalin/remu architecture

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

- Interactive diagram: https://gitdiagram.com/qazalin/remu
- Repository: https://github.com/qazalin/remu

## Overview

The project is a minimal RDNA3 emulator implemented in Rust. It is built as a dynamic library (libremu.so) that is intended to be used with the tinygrad project for testing its kernels. The key purpose of this project is to emulate a subset of RDNA3 GPU instructions, with emphasis on integration and testing using tinygrad.

##### Main Components
- Emulator Core: Represented by the Rust library in the src folder, primarily handled by lib.rs. This is the central hub orchestrating the emulation.
- State Management: The state.rs file likely manages the current state of the emulated GPU (registers, memory, etc.).
- Thread and Concurrency: The thread.rs file suggests that the project might support concurrent execution, possibly simulating parallel processing.
- Work Group Management: The work_group.rs file probably organizes work items or clusters similar to GPU workgroups.
- Helper Functions: helpers.rs captures utility functions used throughout the project.
- Build and Deployment: The Cargo.toml, Cargo.lock, and GitHub workflow configuration in .github/workflows indicate standardized build, dependency management, and CI testing.
- External Integration: Although the emulator runs as a shared library loaded by tinygrad, its integration is highlighted in the README with instructions on downloading and linking libremu.so.

##### Relationships and Interactions
- The Emulator Core (lib.rs) interfaces with all other internal modules: it calls functions from state.rs to update or read GPU state, uses thread.rs to manage concurrent emulation tasks, and leverages work_group.rs to manage group execution.
- Helper functions (helpers.rs) are used across these modules for common operations.
- The build system (Cargo) and CI (GitHub workflows) are separate from the runtime architecture but ensure that all components are integrated correctly.
- Externally, the shared library (libremu.so) is meant to be used by tinygrad, meaning there is a clear boundary between the emulator (server/engine side) and the consuming application (client side).

##### Architectural Patterns and Design Principles
- Modular Design: The project is divided into clearly separated modules (state, thread, work_group, helpers) that exemplify separation of concerns.
- Concurrency: The use of thread.rs suggests an emphasis on simulating parallelism, which is a key aspect of GPU emulation.
- Library/Plugin Architecture: Building as a shared library allows for integration with other systems like tinygrad, making the emulator extensible and pluggable.
- CI/CD Integration: The presence of GitHub workflows assures that the design includes testing and deployment automation.

##### Including Technologies, Frameworks, and Libraries
- Rust: The core language and its ecosystem (Cargo for package management) form the basis of the project.
- GitHub Actions: For CI/CD processes which ensure ongoing integration and testing.
- External Tools: tinygrad acts as the client/consumer that leverages the emulator functionalities.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Internal Emulation Modules
    A["Emulator Core (lib.rs)"]:::internal
    B["GPU State Module (state.rs)"]:::internal
    C["Thread Manager (thread.rs)"]:::internal
    D["Work Group Scheduler (work_group.rs)"]:::internal
    E["Helper Functions (helpers.rs)"]:::internal

    %% External Client
    F["External Client (tinygrad)"]:::external

    %% Build and CI Infrastructure Subgraph
    subgraph "Build and CI Infrastructure"
        G1["Cargo.toml"]:::build
        G2["Cargo.lock"]:::build
        G3[".github/workflows/test.yml"]:::build
    end

    %% Relationships among internal modules
    A -->|"updates_state"| B
    A -->|"manages_threads"| C
    A -->|"schedules_workgroups"| D
    A -->|"uses_helpers"| E

    %% External integration: tinygrad loads the shared library
    F -->|"loads_libremu.so"| A

    %% Build/CI supports building and testing the Emulator Core
    G1 -->|"builds_tests"| A
    G2 -->|"builds_tests"| A
    G3 -->|"builds_tests"| A

    %% Click Events for Component Mappings
    click A "https://github.com/qazalin/remu/blob/master/src/lib.rs"
    click B "https://github.com/qazalin/remu/blob/master/src/state.rs"
    click C "https://github.com/qazalin/remu/blob/master/src/thread.rs"
    click D "https://github.com/qazalin/remu/blob/master/src/work_group.rs"
    click E "https://github.com/qazalin/remu/blob/master/src/helpers.rs"
    click F "https://github.com/qazalin/remu/blob/master/README.md"
    click G1 "https://github.com/qazalin/remu/blob/master/Cargo.toml"
    click G2 "https://github.com/qazalin/remu/blob/master/Cargo.lock"
    click G3 "https://github.com/qazalin/remu/blob/master/.github/workflows/test.yml"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#cc0000,stroke-width:2px;
    classDef build fill:#ccffcc,stroke:#009933,stroke-width:2px;
```
