# superm1/rocr-runtime architecture

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

- Interactive diagram: https://gitdiagram.com/superm1/rocr-runtime
- Repository: https://github.com/superm1/rocr-runtime

## Overview

- The HSA Runtime (the “ROCr” part) that provides a thin, user-mode API for AMD GPU programming, implementing features such as runtime initialization, agent information, memory management, and more.
- The ROCt Thunk Library (located as libhsakmt) which acts as the “thunk” layer interfacing directly with the kernel driver (ROCk).

##### Main Components & Layers
a. User Applications: Represent client applications that link against the HSA runtime (using the provided CMake packages).
b. HSA Runtime Library (ROCr): This is the core runtime layer that offers the GPU API for error handling, initialization/shutdown, memory management, low-level queue management, and dispatch via the HSA Architected Queuing Language.
c. ROCt Thunk Library (libhsakmt): This library provides the interface between the user-mode runtime and the underlying ROCm kernel driver (ROCk). It encapsulates system-level calls and direct hardware interactions.
d. Kernel Driver (ROCk): Although not built within this repository, denote it as the hardware or kernel-level interface required for complete GPU interaction.
e. Test Suites & Validation:
- rocrtst: The runtime test suites for validating and performance testing the HSA implementation.
- kfdtest: The specific set of tests that validate the ROCt interface.
f. Build & Packaging Infrastructure: Optionally, include components such as CMake build scripts, packaging directories (RPM, DEBIAN), and CI configurations which orchestrate the integration and release pipelines.

##### Relationships & Interactions
- An internal link between the HSA Runtime and the ROCt Thunk Library (libhsakmt) since the runtime statically links with ROCt.

##### Architectural Patterns & Design Principles
- Modularity by separating the runtime API (user-facing) from the hardware-specific thunk (driver interfacing).
- Layered approach where the HSA Runtime abstracts low-level hardware details, ensuring a clean separation between application logic and kernel-level operations.

##### Technologies and Frameworks
- CMake (as seen in the root CMakeLists.txt and cmake_modules directories) coordinating the build.
- The CI/CD configurations (.github and .azuredevops folders) that help automate integration and testing.
- Linux-specific development targeting ROCm systems, as noted by dependencies and build instructions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Layer"
        UA["User Applications"]:::user
    end

    subgraph "HSA Runtime Layer"
        RT["HSA Runtime Library"]:::runtime
    end

    subgraph "ROCt Thunk Layer"
        TH["ROCt Thunk Library"]:::thunk
    end

    subgraph "Kernel Interface"
        KD["Kernel Driver (ROCk)"]:::hardware
    end

    subgraph "Test Suites & Validation"
        T1["rocrtst Test Suites"]:::test
        T2["kfdtest Test Suite"]:::test
    end

    subgraph "Build & Packaging Infrastructure"
        B1["CMake Build Scripts"]:::infra
        B2["CI/CD Pipelines"]:::infra
        B3["Packaging"]:::infra
    end

    UA -->|"links"| RT
    RT -->|"static_link"| TH
    TH -->|"interfaces"| KD

    T1 -->|"tests"| RT
    T1 -->|"tests"| TH
    T2 -->|"validates"| TH

    B1 -->|"builds"| RT
    B1 -->|"builds"| TH
    B2 -->|"triggers"| RT
    B2 -->|"triggers"| TH
    B3 -->|"packages"| RT
    B3 -->|"packages"| TH

    click UA "https://github.com/superm1/rocr-runtime/tree/amd-staging/samples/"
    click RT "https://github.com/superm1/rocr-runtime/tree/amd-staging/runtime/hsa-runtime/"
    click TH "https://github.com/superm1/rocr-runtime/tree/amd-staging/libhsakmt/"
    click T1 "https://github.com/superm1/rocr-runtime/tree/amd-staging/rocrtst/"
    click T2 "https://github.com/superm1/rocr-runtime/tree/amd-staging/libhsakmt/tests/kfdtest/"
    click B1 "https://github.com/superm1/rocr-runtime/blob/amd-staging/CMakeLists.txt"
    click B2 "https://github.com/superm1/rocr-runtime/tree/amd-staging/.github/"
    click B3 "https://github.com/superm1/rocr-runtime/tree/amd-staging/DEBIAN/"

    classDef user fill:#AED6F1,stroke:#000,stroke-width:2px;
    classDef runtime fill:#A9DFBF,stroke:#000,stroke-width:2px;
    classDef thunk fill:#F9E79F,stroke:#000,stroke-width:2px;
    classDef hardware fill:#F5B7B1,stroke:#000,stroke-width:2px;
    classDef test fill:#D7BDE2,stroke:#000,stroke-width:2px;
    classDef infra fill:#D6EAF8,stroke:#000,stroke-width:2px;
```
