# rocm/rocr-runtime architecture

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

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

## Overview

ROCR Runtime provides the HSA API for AMD GPU applications and uses ROCt/libhsakmt to reach the ROCk kernel driver. The principal workflow is: an application calls HSA APIs, the runtime discovers agents and memory, loads executable code, creates queues and signals, dispatches work through a selected device backend, and returns status or results. Image operations, profiling, and alternate VirtIO/XDNA backends are additional runtime branches. The graph reflects sampled implementation paths and README-documented layering; unsampled internals are represented conservatively.

Main entry points: [`runtime/hsa-runtime/core/runtime/runtime.cpp`](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/runtime.cpp) (Runtime Core), [`runtime/hsa-runtime/core/driver/driver.cpp`](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/driver/driver.cpp) (Driver Manager), [`libhsakmt/src/libhsakmt.c`](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/libhsakmt/src/libhsakmt.c) (ROCt Thunk), [`runtime/hsa-runtime/core/runtime/hsa.cpp`](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/hsa.cpp) (Runtime Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HSA API"]
  node_hsa_api["HSA API<br/>[hsa.h]"]
  node_runtime_entry["Runtime Entry<br/>[hsa.cpp]"]
end

subgraph group_core["Runtime Core"]
  node_runtime_core["Runtime Core<br/>[runtime.cpp]"]
  node_topology["Agent Topology<br/>[amd_topology.cpp]"]
  node_memory["Memory Regions"]
  node_queues["AQL Queues<br/>[amd_aql_queue.cpp]"]
  node_signals["Signals<br/>[signal.cpp]"]
  node_loader["Code Loader<br/>[executable.cpp]"]
  node_loader_context["Loader Context"]
end

subgraph group_device["Device Backends"]
  node_driver_manager["Driver Manager<br/>[driver.cpp]"]
  node_kfd_driver["KFD Backend<br/>[amd_kfd_driver.cpp]"]
  node_thunk["ROCt Thunk<br/>[libhsakmt.c]"]
  node_vm_manager["Virtual Memory<br/>[fmm.c]"]
  node_virtio_driver["VirtIO Backend"]
  node_xdna_driver["XDNA Backend"]
end

subgraph group_extensions["Runtime Extensions"]
  node_image_runtime["Image Runtime<br/>[image_runtime.cpp]"]
  node_image_backends["ASIC Image Backends"]
  node_profiling["PC Sampling<br/>[pcs_runtime.cpp]"]
end

node_app(("GPU Application"))
node_kfd_kernel["ROCK Kernel"]
node_drm_device["DRM Device"]
node_gpu["AMD GPU"]

node_app -->|"calls"| node_hsa_api
node_hsa_api -->|"enters"| node_runtime_entry
node_runtime_entry -->|"dispatches"| node_runtime_core
node_runtime_core -->|"discovers"| node_topology
node_runtime_core -->|"allocates"| node_memory
node_runtime_core -->|"loads"| node_loader
node_runtime_core -->|"submits"| node_queues
node_runtime_core -->|"synchronizes"| node_signals
node_runtime_core -->|"selects"| node_driver_manager
node_runtime_core -->|"manages"| node_image_runtime
node_runtime_core -.->|"profiles"| node_profiling
node_loader -->|"uses"| node_loader_context
node_driver_manager -->|"selects"| node_kfd_driver
node_driver_manager -.->|"selects"| node_virtio_driver
node_driver_manager -.->|"selects"| node_xdna_driver
node_kfd_driver -->|"calls"| node_thunk
node_thunk -->|"manages"| node_vm_manager
node_thunk -->|"issues IOCTLs"| node_kfd_kernel
node_thunk -->|"opens"| node_drm_device
node_kfd_kernel -->|"dispatches"| node_gpu
node_image_runtime -->|"formats"| node_image_backends
node_runtime_entry -->|"returns status"| node_app

click node_hsa_api "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/inc/hsa.h"
click node_runtime_entry "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/hsa.cpp"
click node_runtime_core "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/runtime.cpp"
click node_topology "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/amd_topology.cpp"
click node_memory "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/amd_memory_region.cpp"
click node_queues "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/amd_aql_queue.cpp"
click node_signals "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/signal.cpp"
click node_loader "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/loader/executable.cpp"
click node_loader_context "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/amd_loader_context.cpp"
click node_driver_manager "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/driver/driver.cpp"
click node_kfd_driver "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/driver/kfd/amd_kfd_driver.cpp"
click node_thunk "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/libhsakmt/src/libhsakmt.c"
click node_vm_manager "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/libhsakmt/src/fmm.c"
click node_image_runtime "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/image/image_runtime.cpp"
click node_image_backends "https://github.com/rocm/rocr-runtime/tree/amd-staging_deprecated/runtime/hsa-runtime/image"
click node_profiling "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/pcs/pcs_runtime.cpp"
click node_virtio_driver "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/driver/virtio/amd_kfd_virtio_driver.cpp"
click node_xdna_driver "https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/driver/xdna/amd_xdna_driver.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hsa_api,node_runtime_entry toneBlue
class node_runtime_core,node_topology,node_memory,node_queues,node_signals,node_loader,node_loader_context toneAmber
class node_driver_manager,node_kfd_driver,node_thunk,node_vm_manager,node_virtio_driver,node_xdna_driver toneMint
class node_image_runtime,node_image_backends,node_profiling toneRose
class node_app,node_kfd_kernel,node_drm_device,node_gpu toneIndigo
```

## Components

### HSA API

- [HSA API](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/inc/hsa.h): `runtime/hsa-runtime/inc/hsa.h`
- [Runtime Entry](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/hsa.cpp): `runtime/hsa-runtime/core/runtime/hsa.cpp`

### Runtime Core

- [Runtime Core](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/runtime.cpp): `runtime/hsa-runtime/core/runtime/runtime.cpp`
- [Agent Topology](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/amd_topology.cpp): `runtime/hsa-runtime/core/runtime/amd_topology.cpp`
- [Memory Regions](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/amd_memory_region.cpp): `runtime/hsa-runtime/core/runtime/amd_memory_region.cpp`
- [AQL Queues](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/amd_aql_queue.cpp): `runtime/hsa-runtime/core/runtime/amd_aql_queue.cpp`
- [Signals](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/signal.cpp): `runtime/hsa-runtime/core/runtime/signal.cpp`
- [Code Loader](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/loader/executable.cpp): `runtime/hsa-runtime/loader/executable.cpp`
- [Loader Context](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/runtime/amd_loader_context.cpp): `runtime/hsa-runtime/core/runtime/amd_loader_context.cpp`

### Device Backends

- [Driver Manager](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/driver/driver.cpp): `runtime/hsa-runtime/core/driver/driver.cpp`
- [KFD Backend](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/driver/kfd/amd_kfd_driver.cpp): `runtime/hsa-runtime/core/driver/kfd/amd_kfd_driver.cpp`
- [ROCt Thunk](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/libhsakmt/src/libhsakmt.c): `libhsakmt/src/libhsakmt.c`
- [Virtual Memory](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/libhsakmt/src/fmm.c): `libhsakmt/src/fmm.c`
- [VirtIO Backend](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/driver/virtio/amd_kfd_virtio_driver.cpp): `runtime/hsa-runtime/core/driver/virtio/amd_kfd_virtio_driver.cpp`
- [XDNA Backend](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/core/driver/xdna/amd_xdna_driver.cpp): `runtime/hsa-runtime/core/driver/xdna/amd_xdna_driver.cpp`

### Runtime Extensions

- [Image Runtime](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/image/image_runtime.cpp): `runtime/hsa-runtime/image/image_runtime.cpp`
- [ASIC Image Backends](https://github.com/rocm/rocr-runtime/tree/amd-staging_deprecated/runtime/hsa-runtime/image): `runtime/hsa-runtime/image`
- [PC Sampling](https://github.com/rocm/rocr-runtime/blob/amd-staging_deprecated/runtime/hsa-runtime/pcs/pcs_runtime.cpp): `runtime/hsa-runtime/pcs/pcs_runtime.cpp`

### Other components

- **GPU Application**
- **ROCK Kernel**
- **DRM Device**
- **AMD GPU**

## Connections

- GPU Application → HSA API: calls
- HSA API → Runtime Entry: enters
- Runtime Entry → Runtime Core: dispatches
- Runtime Core → Agent Topology: discovers
- Runtime Core → Memory Regions: allocates
- Runtime Core → Code Loader: loads
- Runtime Core → AQL Queues: submits
- Runtime Core → Signals: synchronizes
- Runtime Core → Driver Manager: selects
- Runtime Core → Image Runtime: manages
- Runtime Core → PC Sampling: profiles
- Code Loader → Loader Context: uses
- Driver Manager → KFD Backend: selects
- Driver Manager → VirtIO Backend: selects
- Driver Manager → XDNA Backend: selects
- KFD Backend → ROCt Thunk: calls
- ROCt Thunk → Virtual Memory: manages
- ROCt Thunk → ROCK Kernel: issues IOCTLs
- ROCt Thunk → DRM Device: opens
- ROCK Kernel → AMD GPU: dispatches
- Image Runtime → ASIC Image Backends: formats
- Runtime Entry → GPU Application: returns status
