# gr0mila/cuda-flame-graph architecture

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

- Interactive diagram: https://gitdiagram.com/gr0mila/cuda-flame-graph
- Repository: https://github.com/gr0mila/cuda-flame-graph

## Overview

cuda-flame-graph is a CUDA program profiler that launches an application with the profiler library injected, captures CPU and GPU profiling data, and emits folded stacks for flame-graph visualization. The README documents filtering and display options, plus execution-time and stall-profiling modes. The source excerpts are partial, so the graph omits uncertain callback wiring and shows only the evidenced capture, aggregation, and launch relationships.

Main entry points: [`src/profiler.cpp`](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp) (CUDA profiler), [`loader/loader.cc`](https://github.com/gr0mila/cuda-flame-graph/blob/main/loader/loader.cc) (cuprof loader), [`src/interface.cpp`](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/interface.cpp) (Options and profiles), [`loader/init.cc`](https://github.com/gr0mila/cuda-flame-graph/blob/main/loader/init.cc) (Load and unload hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch and configuration"]
  node_cuprof["cuprof loader<br/>[loader.cc]"]
  node_tool_library["Profiler library<br/>[shared_library.h]"]
  node_options["Options and profiles<br/>[interface.cpp]"]
  node_load_hook["Load and unload hooks<br/>[init.cc]"]
end

subgraph group_capture["Sample capture"]
  node_interface["Profiler lifecycle<br/>[interface.cpp]"]
  node_profiler["CUDA profiler<br/>[profiler.cpp]"]
  node_perf[("Linux perf events<br/>[profiler.cpp]")]
  node_activity["Kernel activities<br/>[profiler.cpp]"]
  node_pc_sampling["PC stall sampling<br/>[profiler.cpp]"]
end

subgraph group_processing["Stack processing"]
  node_symbolize["Stack resolution<br/>[profiler.cpp]"]
  node_filter["Frame filtering<br/>[profiler.cpp]"]
  node_aggregate[("Stack aggregation<br/>[profiler.cpp]")]
end

subgraph group_output["Results"]
  node_folded["Folded stacks<br/>[profiler.cpp]"]
end

node_user(("Profiler user"))
node_cuda_app["CUDA application"]
node_cupti["CUPTI"]
node_flamegraph["FlameGraph tool"]

node_user -->|"runs with options"| node_cuprof
node_cuprof -->|"loads library"| node_tool_library
node_cuprof -->|"calls parser"| node_options
node_options -->|"sets environment"| node_cuprof
node_cuprof -->|"launches with preload"| node_cuda_app
node_cuda_app -->|"loads profiler"| node_load_hook
node_load_hook -->|"enables profiling"| node_interface
node_interface -->|"initializes and finalizes"| node_profiler
node_profiler -->|"samples CPU stacks"| node_perf
node_profiler -->|"configures and subscribes"| node_cupti
node_cupti -->|"delivers activity records"| node_activity
node_profiler -->|"processes GPU timing"| node_activity
node_profiler -->|"processes stall records"| node_pc_sampling
node_profiler -->|"resolves sampled stacks"| node_symbolize
node_symbolize -->|"classifies frames"| node_filter
node_filter -->|"adds accepted stacks"| node_aggregate
node_aggregate -->|"prints folded counts"| node_folded
node_user -.->|"visualizes output"| node_flamegraph
node_folded -.->|"reads folded stacks"| node_flamegraph

click node_cuprof "https://github.com/gr0mila/cuda-flame-graph/blob/main/loader/loader.cc"
click node_tool_library "https://github.com/gr0mila/cuda-flame-graph/blob/main/utils/shared_library.h"
click node_options "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/interface.cpp"
click node_load_hook "https://github.com/gr0mila/cuda-flame-graph/blob/main/loader/init.cc"
click node_interface "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/interface.cpp"
click node_profiler "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp"
click node_perf "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp"
click node_activity "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp"
click node_pc_sampling "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp"
click node_symbolize "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp"
click node_filter "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp"
click node_aggregate "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp"
click node_folded "https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.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_cuprof,node_tool_library,node_options,node_load_hook,node_user toneBlue
class node_interface,node_profiler,node_perf,node_activity,node_pc_sampling toneAmber
class node_symbolize,node_filter,node_aggregate toneMint
class node_folded toneRose
class node_cuda_app,node_cupti,node_flamegraph toneIndigo
```

## Components

### Launch and configuration

- [cuprof loader](https://github.com/gr0mila/cuda-flame-graph/blob/main/loader/loader.cc): `loader/loader.cc`
- [Profiler library](https://github.com/gr0mila/cuda-flame-graph/blob/main/utils/shared_library.h): `utils/shared_library.h`
- [Options and profiles](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/interface.cpp): `src/interface.cpp`
- [Load and unload hooks](https://github.com/gr0mila/cuda-flame-graph/blob/main/loader/init.cc): `loader/init.cc`

### Sample capture

- [Profiler lifecycle](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/interface.cpp): `src/interface.cpp`
- [CUDA profiler](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp): `src/profiler.cpp`
- [Linux perf events](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp): `src/profiler.cpp`
- [Kernel activities](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp): `src/profiler.cpp`
- [PC stall sampling](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp): `src/profiler.cpp`

### Stack processing

- [Stack resolution](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp): `src/profiler.cpp`
- [Frame filtering](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp): `src/profiler.cpp`
- [Stack aggregation](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp): `src/profiler.cpp`

### Results

- [Folded stacks](https://github.com/gr0mila/cuda-flame-graph/blob/main/src/profiler.cpp): `src/profiler.cpp`

### Other components

- **Profiler user**
- **CUDA application**
- **CUPTI**
- **FlameGraph tool**

## Connections

- Profiler user → cuprof loader: runs with options
- cuprof loader → Profiler library: loads library
- cuprof loader → Options and profiles: calls parser
- Options and profiles → cuprof loader: sets environment
- cuprof loader → CUDA application: launches with preload
- CUDA application → Load and unload hooks: loads profiler
- Load and unload hooks → Profiler lifecycle: enables profiling
- Profiler lifecycle → CUDA profiler: initializes and finalizes
- CUDA profiler → Linux perf events: samples CPU stacks
- CUDA profiler → CUPTI: configures and subscribes
- CUPTI → Kernel activities: delivers activity records
- CUDA profiler → Kernel activities: processes GPU timing
- CUDA profiler → PC stall sampling: processes stall records
- CUDA profiler → Stack resolution: resolves sampled stacks
- Stack resolution → Frame filtering: classifies frames
- Frame filtering → Stack aggregation: adds accepted stacks
- Stack aggregation → Folded stacks: prints folded counts
- Profiler user → FlameGraph tool: visualizes output
- Folded stacks → FlameGraph tool: reads folded stacks