# rocm/clr architecture

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

- Interactive diagram: https://gitdiagram.com/rocm/clr
- Repository: https://github.com/rocm/clr

## Overview

##### Project Type and Purpose
- This is a multi‐language compute runtime library (not a typical web or microservice app). It implements AMD’s HIP and OpenCL™ APIs (“hipamd” and “opencl” folders) atop a shared core runtime library (“rocclr”). It compiles down to static/shared libraries used by GPU drivers and user applications.

##### High‐Level Architecture & Components
a. Language Frontends
- hipamd – HIP runtime implementation on AMD GPUs
- opencl – OpenCL™ runtime implementation on AMD GPUs
b. Shared Core Runtime (rocclr)
- Compiler submodule – SPIR-V, HSAIL, PAL translation backends
- Device submodule – GPU command submission, memory management, profiling
- Platform submodule – API objects (contexts, queues, kernels) and interoperability (GL/D3D)
- ELF loader – parses code objects (ELF)
- OS abstraction – cross‐platform support for Linux/Windows, threading, allocation
- Utilities – logging, flags, versioning
c. External Dependencies & Services
- HSA Runtime Loader (libhsa)
- PAL (Platform Abstraction Library) – low‐level GPU interface
- System OS Kernel / GPU Driver

##### Relationships & Data Flow
- User application calls HIP or OpenCL™ API →
- hipamd/opencl frontend layers translate calls into internal rocclr calls →
- rocclr “Platform” constructs command buffers, dispatches to “Device” module →
- Device module uses HSA loader & PAL interfaces to submit work to GPU →
- OS layer handles memory allocation, threads, synchronization →
- GPU executes kernels, returns events/status back up the stack →
- Profiling/tracing subsystems record API usage (hip_api_trace, cl_profile_amd)

##### Architectural Patterns & Design Principles
- Layered Architecture: clear separation between frontends, core runtime, OS abstraction, and hardware interface
- Adapter/Facade: rocclr abstracts HSA and PAL differences, exposing a unified interface to hipamd/opencl
- Plugin‐style backends: compiler submodule isolates target‐specific translation logic
- Cross‐platform portability: OS layer abstracts Windows/Linux differences

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Language Frontends
    hipamd["hipamd"]:::frontend
    opencl["opencl"]:::frontend

    %% Core Runtime
    subgraph "Shared Core Runtime (rocclr)"
        direction TB
        compiler["compiler"]:::core
        device["device"]:::core
        platform["platform"]:::core
        elf["elf"]:::core
        os_abstraction["os"]:::core
        utils["utils"]:::core
    end

    %% External Interfaces
    HSA["HSA Runtime Loader"]:::external
    PAL["PAL Interface"]:::external

    %% OS Kernel / GPU Driver
    os_kernel["OS Kernel / GPU Driver"]:::os

    %% Physical GPU Hardware
    gpu["Physical GPU"]:::hardware

    %% Connections
    hipamd -->|API calls| compiler
    hipamd -->|API calls| device
    hipamd -->|API calls| platform
    opencl -->|API calls| compiler
    opencl -->|API calls| device
    opencl -->|API calls| platform

    compiler -->|compilation backends| device
    compiler -->|compilation backends| platform

    device -->|command submission| HSA
    device -->|command submission| PAL

    HSA -->|HSA calls| os_kernel
    PAL -->|PAL calls| os_kernel

    os_kernel -->|driver interaction| gpu
    gpu -->|events/status| device

    elf -->|load code objects| device
    os_abstraction -->|memory/threads| device
    utils -->|logging/profiling| device

    %% Click Events
    click hipamd "https://github.com/rocm/clr/tree/amd-staging/hipamd/"
    click opencl "https://github.com/rocm/clr/tree/amd-staging/opencl/"
    click compiler "https://github.com/rocm/clr/tree/amd-staging/rocclr/compiler/"
    click device "https://github.com/rocm/clr/tree/amd-staging/rocclr/device/"
    click platform "https://github.com/rocm/clr/tree/amd-staging/rocclr/platform/"
    click elf "https://github.com/rocm/clr/tree/amd-staging/rocclr/elf/"
    click os_abstraction "https://github.com/rocm/clr/tree/amd-staging/rocclr/os/"
    click utils "https://github.com/rocm/clr/tree/amd-staging/rocclr/utils/"
    click HSA "https://github.com/rocm/clr/blob/amd-staging/rocclr/cmake/FindAMD_HSA_LOADER.cmake"
    click PAL "https://github.com/rocm/clr/blob/amd-staging/rocclr/cmake/FindAMD_PAL.cmake"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef os fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef hardware fill:#DDA0DD,stroke:#333,stroke-width:1px
```
