# rocm/rocprofiler-sdk architecture

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

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

## Overview

##### Overall Project Type and Purpose
- Recognize that this is a performance analysis and GPU profiling toolkit. The SDK offers direct interfaces to GPU counters, API tracing (HIP, HSA, etc.), and various tracing modes (like PC sampling beta and marker/ROCTx).
- That the README highlights integration with GPU hardware, build/installation using CMake, and a strong emphasis on documentation (doxygen and Sphinx).

##### And Break Down Main Architectural Components
a. Command-Line Tool & User Interface:
- The “source/bin” directory shows the rocprofv3 tool (and related scripts like rocprofv3_avail.py) that users invoke. This constitutes the entry point of the profiling system.
b. Core SDK Libraries and APIs:
- The bulk of the functionality is implemented in “source/lib” and “source/include” directories. These contain modules for:
- API/Call Tracing: Modules handling HIP API, HSA API, and marker tracing.
- Counter Collection & PC Sampling: Separate modules specific to hardware counters and experimental PC sampling (see “source/lib/rocprofiler-sdk/counters”, “source/lib/rocprofiler-sdk/pc_sampling”).
- Code Object and Kernel Dispatch: Handle deeper runtime integration (under “source/lib/rocprofiler-sdk/code_object” and “source/lib/rocprofiler-sdk/kernel_dispatch”).
- Context, Registration, and Internal Utilities: Modules that facilitate call interception, memory management, and thread tracking.
c. Output and Data Formatting:
- Components in “source/lib/output” deal with producing reports in CSV, JSON, Perfetto, etc., and handle metadata and statistical analysis.
- A node titled “Data Output & Reporting” that shows how profiling data is formatted for logs, statistics, and external consumption.
d. Build/Configuration and External Dependencies:
- CMake configurations are present throughout (CMakeLists.txt files in many directories, plus custom cmake/Modules and Templates).
- External dependencies (e.g., libraries like glog, fmt, json, cereal, etc.) are placed in the “external” directory.
e. Documentation Subsystem:
- The “source/docs” folder houses doxygen and Sphinx documentation sources.
- This as “API Documentation & Guides” interacting with the main SDK.

- From core libraries, indicate calls that branch into counter collection, API tracing, and kernel dispatch routines.
- That the output modules receive data results from the core components and produce various report formats.
- Optionally, illustrate dependency links to external libraries (e.g., glog, fmt) to remind viewers of integration points.

##### Architectural Patterns and Design Principles
- Modular Separation: The file structure naturally segregates components (e.g., tracing, counters, documentation, samples, tests). Emphasize that the design is modular.
- Layered Design: The system is layered from user CLI down to low-level hardware interfacing, following abstraction principles.
- Use of CMake for Cross-Platform Build and Integration, which shows a separation between configuration and implementation.

- Use a tool that lets you arrange these nodes clearly – ensuring the data flow and dependencies are evident.
- Avoid overcomplicating areas where the same module may be repeated; group similar components when appropriate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interface Layer
    subgraph "Interface Layer"
        CLI_ROC["CLI Application (rocprofv3)"]
        CLI_AVAIL["CLI Script (rocprofv3_avail)"]
    end

    %% Core ROCprofiler SDK
    subgraph "Core ROCprofiler SDK"
        subgraph "Tracing & Profiling"
            HIP["HIP API Tracing"]
            HSA["HSA API Tracing"]
            Marker["Marker Tracing"]
            OMPT["OMPT Tracing"]
        end
        subgraph "Counters & Sampling"
            Counters["Counter Collection"]
            PCSampling["PC Sampling"]
            PCSamplingHdr["PC Sampling Header"]
        end
        CodeObj["Code Object Handling"]
        KernelDispatch["Kernel Dispatch"]
    end

    %% Data Output & Reporting Engine
    Output["Data Output & Reporting Engine"]

    %% Build & Integration Layer
    subgraph "Build & Integration Layer"
        CMakeBuild["CMake Build Config"]
        External["External Dependencies"]
    end

    %% Documentation & API Guides
    Docs["API Documentation & Guides"]

    %% Connections
    %% CLI invokes the core SDK
    CLI_ROC --> HIP
    CLI_AVAIL --> HIP

    %% Core modules report profiling data
    HIP -->|"reports"| Output
    Counters -->|"reports"| Output
    CodeObj -->|"reports"| Output
    KernelDispatch -->|"reports"| Output

    %% Build system configures core components
    CMakeBuild --> HIP
    External --> HIP

    %% Core APIs are documented
    KernelDispatch -->|"documentedIn"| Docs

    %% Styles
    classDef cli fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef sdk fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef output fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef build fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef docs fill:#E1BEE7,stroke:#4A148C,stroke-width:2px;

    class CLI_ROC,CLI_AVAIL cli;
    class HIP,HSA,Marker,OMPT,Counters,PCSampling,PCSamplingHdr,CodeObj,KernelDispatch sdk;
    class Output output;
    class CMakeBuild,External build;
    class Docs docs;

    %% Click Events
    click CLI_ROC "https://github.com/rocm/rocprofiler-sdk/blob/amd-staging/source/bin/rocprofv3.py"
    click CLI_AVAIL "https://github.com/rocm/rocprofiler-sdk/blob/amd-staging/source/bin/rocprofv3_avail.py"
    click HIP "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/lib/rocprofiler-sdk/hip"
    click HSA "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/lib/rocprofiler-sdk/hsa"
    click Marker "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/lib/rocprofiler-sdk/marker"
    click OMPT "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/lib/rocprofiler-sdk/ompt"
    click Counters "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/lib/rocprofiler-sdk/counters"
    click PCSampling "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/lib/rocprofiler-sdk/pc_sampling"
    click PCSamplingHdr "https://github.com/rocm/rocprofiler-sdk/blob/amd-staging/source/include/rocprofiler-sdk/pc_sampling.h"
    click CodeObj "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/lib/rocprofiler-sdk/code_object"
    click KernelDispatch "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/lib/rocprofiler-sdk/kernel_dispatch"
    click Output "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/lib/output"
    click CMakeBuild "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/cmake/"
    click External "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/external/"
    click Docs "https://github.com/rocm/rocprofiler-sdk/tree/amd-staging/source/docs"
```
