# serge45/amdgpu-arch-gemm architecture

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

- Interactive diagram: https://gitdiagram.com/serge45/amdgpu-arch-gemm
- Repository: https://github.com/serge45/amdgpu-arch-gemm

## Overview

##### Project type and purpose
- This is an open-source tool (a domain-specific code generator and tuner) for emitting AMD GCN assembly kernels specialized for single-precision GEMM and for evaluating them via a VM or native hardware runner.

##### File structure
- Top-level folders:
- generator/        – Python module that takes GEMM parameters and emits AMD GCN .s code
- vm/               – Python “GCN Virtual Machine” that simulates execution of the generated code
- tuner/            – Python tuner that drives generator + benchmark harness (runner or VM) to optimize tiling/blocking parameters
- runner/           – C++ harness (with CMake) compiling + launching the generated kernels on real AMD hardware
- test/             – Python pytest tests validating generator correctness and VM accuracy
- Config/build:
- runner/Utils/*.hpp – helper classes for buffers, kernel arguments, TOML config parsing, math helpers
- runner/CMakeLists.txt – build scripts for the native runner
- requirements.txt / requirements-test.txt – Python dependencies

##### README for additional insights
- Purpose: learn and record how to generate optimal AMD GCN assembly for SGEMM on gfx90a/908
- Current scope: only NN SGEMM

a. Main components:
1) Tuner (Python)
2) Generator (Python)
3) VM (Python)
4) Runner (C++ on GPU)
5) Test Suite (pytest)
6) Config/Parameter Store (TOML)
b. Relationships / data flow:
- Tuner reads problem specs & search space → invokes Generator → outputs .s assembly →
→ feeds either VM or Runner → execution returns performance metrics →
→ Tuner updates parameters → loop until optimum
- Test Suite invokes Generator and VM to assert correctness of code emission and simulation results
c. Architectural patterns / principles:
- Pipeline pattern: a parameter-search pipeline stitched from modular stages (generate → execute → measure)
- Separation of concerns: code-generation, simulation, native execution, and tuning are decoupled
- Extensible: new GEMM variants or hardware targets can be added by extending the generator or VM
d. Key technologies / libraries:
- Python 3.x (generator, VM, tuner, tests)
- C++17 (runner) + CMake + TOML for native execution
- pytest for test validation

##### Detail
- Sub-modules only if they add clarity (e.g., the runner’s Utils folder as an internal detail)
- External dependencies (Python, CMake, GPU hardware)
- Keep each component’s interface explicit (inputs/outputs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Python Modules"
        Tuner["Tuner"]:::python
        Generator["Generator"]:::python
        VM["VM (GCN VM)"]:::python
    end

    subgraph "Native Runner"
        RunnerCpp["Generator Runner"]:::cpp
        CMake["CMake Build"]:::cpp
        Utils["Utils"]:::cpp
    end

    subgraph "Test Suite"
        TestSGEMM["test_sgemm.py"]:::test
        TestVM["test_vm.py"]:::test
    end

    Config["TOML Config Store"]:::config

    %% Data flow
    Tuner -->|"invokes"| Generator
    Generator -->|".s Assembly"| ASM[".s Assembly"]
    ASM -->|"execute"| VM
    ASM -->|"execute"| RunnerCpp
    VM -->|"performance metrics"| Tuner
    RunnerCpp -->|"performance metrics"| Tuner
    Tuner -->|"reads configs"| Config
    RunnerCpp -->|"reads configs"| Config

    %% Test interactions
    TestSGEMM -->|"validates emission"| Generator
    TestVM -->|"validates simulation"| VM

    %% Click Events
    click Tuner "https://github.com/serge45/amdgpu-arch-gemm/blob/main/tuner/sgemm_tuner.py"
    click Generator "https://github.com/serge45/amdgpu-arch-gemm/blob/main/generator/generator.py"
    click VM "https://github.com/serge45/amdgpu-arch-gemm/blob/main/vm/gcn_virtual_machine.py"
    click RunnerCpp "https://github.com/serge45/amdgpu-arch-gemm/blob/main/runner/generator_runner.cpp"
    click CMake "https://github.com/serge45/amdgpu-arch-gemm/blob/main/runner/CMakeLists.txt"
    click Utils "https://github.com/serge45/amdgpu-arch-gemm/tree/main/runner/Utils/"
    click TestSGEMM "https://github.com/serge45/amdgpu-arch-gemm/blob/main/test/test_sgemm.py"
    click TestVM "https://github.com/serge45/amdgpu-arch-gemm/blob/main/test/test_vm.py"
    click Config "https://github.com/serge45/amdgpu-arch-gemm/blob/main/runner/Utils/toml.hpp"

    %% Styles
    classDef python fill:#add8e6,stroke:#333,stroke-width:1px
    classDef cpp fill:#90ee90,stroke:#333,stroke-width:1px
    classDef test fill:#ffffe0,stroke:#333,stroke-width:1px
    classDef config fill:#f4c2f4,stroke:#333,stroke-width:1px
    classDef artifact fill:#e0e0e0,stroke:#333,stroke-width:1px

    class ASM artifact
```
