# rocm/rocprofiler-systems architecture

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

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

## Overview

##### Main Components

a. Core Components:
- Instrumentation Engine (Binary/Runtime)
- Sampling Engine
- Process Monitor
- Data Collection System
- Visualization Pipeline
- Python Integration Layer
- Configuration Management

b. External Interfaces:
- ROCm Platform Integration
- Hardware Counter Interface
- MPI Support
- GPU Metrics Collection
- CPU Metrics Collection

##### Architectural Layers

**User Interface Layer:**
- Command-line tools (rocprof-sys-*)
- Python API
- Configuration Interface

**Core Processing Layer:**
- Binary Instrumentation Engine
- Sampling Engine
- Process Monitor
- Data Collection Controllers

**Integration Layer:**
- ROCm Integration
- Hardware Counter Interface
- MPI Support
- Threading Support (Pthreads, OpenMP)

**Data Management Layer:**
- Perfetto Integration
- Timemory Integration
- Trace Collection
- Profile Storage

**Hardware Interface Layer:**
- CPU Metrics Collection
- GPU Metrics Collection
- System Metrics Collection

##### Key Design Elements

- Blue: User interface components
- Green: Core processing components
- Yellow: Integration components
- Orange: Data management components
- Red: Hardware interface components

b. Connection Types:
- Double lines: API boundaries

##### Specific Implementation Details

- Binary instrumentation flow (both runtime and rewrite modes)
- Sampling architecture with frequency control
- Process monitoring system
- Data collection pipeline
- Integration points with ROCm
- Python profiling mechanism
- Trace visualization pipeline

##### Component Relationships

Clear relationships between:
- Configuration system and all components
- Data collection and storage systems
- Hardware interfaces and metric collection
- User interfaces and core processing
- Integration layers and external systems

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Style Definitions
    classDef ui fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef integration fill:#f1c40f,stroke:#f39c12,color:black
    classDef data fill:#e67e22,stroke:#d35400,color:white
    classDef hardware fill:#e74c3c,stroke:#c0392b,color:white

    %% User Interface Layer
    subgraph UI[User Interface Layer]
        CLI[Command-line Tools]:::ui
        PythonAPI[Python API]:::ui
        Config[Configuration Interface]:::ui
    end

    %% Core Processing Layer
    subgraph Core[Core Processing Layer]
        InstEngine[Instrumentation Engine]:::core
        SampEngine[Sampling Engine]:::core
        ProcMon[Process Monitor]:::core
        DataCol[Data Collection Controllers]:::core
        BinAnalysis[Binary Analysis]:::core
        Runtime[Runtime System]:::core
        Causal[Causal Profiling]:::core
    end

    %% Integration Layer
    subgraph Integration[Integration Layer]
        ROCm[ROCm Integration]:::integration
        HWCounter[Hardware Counter Interface]:::integration
        MPISupport[MPI Support]:::integration
        Threading[Threading Support]:::integration
    end

    %% Data Management Layer
    subgraph Data[Data Management Layer]
        Perfetto[Perfetto Integration]:::data
        Timemory[Timemory Integration]:::data
        TraceCol[Trace Collection]:::data
        ProfStore[Profile Storage]:::data
    end

    %% Hardware Interface Layer
    subgraph Hardware[Hardware Interface Layer]
        CPUMetrics[CPU Metrics Collection]:::hardware
        GPUMetrics[GPU Metrics Collection]:::hardware
        SysMetrics[System Metrics Collection]:::hardware
    end

    %% Relationships
    CLI --> InstEngine
    CLI --> SampEngine
    PythonAPI --> DataCol
    Config --> InstEngine
    Config --> SampEngine
    Config --> ProcMon
    
    InstEngine --> ROCm
    SampEngine --> ROCm
    ProcMon --> DataCol
    
    ROCm --> HWCounter
    ROCm --> MPISupport
    
    DataCol --> Perfetto
    DataCol --> Timemory
    
    HWCounter --> CPUMetrics
    HWCounter --> GPUMetrics
    
    %% Click Events
    click InstEngine "https://github.com/ROCm/rocprofiler-systems/tree/amd-staging/source/bin/rocprof-sys-instrument/"
    click SampEngine "https://github.com/ROCm/rocprofiler-systems/tree/amd-staging/source/bin/rocprof-sys-sample/"
    click ProcMon "https://github.com/ROCm/rocprofiler-systems/blob/amd-staging/source/lib/rocprof-sys/library/process_sampler.cpp"
    click DataCol "https://github.com/ROCm/rocprofiler-systems/tree/amd-staging/source/lib/rocprof-sys/library/components/"
    click PythonAPI "https://github.com/ROCm/rocprofiler-systems/tree/amd-staging/source/python/rocprofsys/"
    click Config "https://github.com/ROCm/rocprofiler-systems/blob/amd-staging/source/lib/core/config.hpp"
    click ROCm "https://github.com/ROCm/rocprofiler-systems/blob/amd-staging/source/lib/rocprof-sys/library/rocm.hpp"
    click HWCounter "https://github.com/ROCm/rocprofiler-systems/tree/amd-staging/source/lib/rocprof-sys/library/rocprofiler-sdk/"
    click MPISupport "https://github.com/ROCm/rocprofiler-systems/blob/amd-staging/source/lib/rocprof-sys/library/components/mpi_gotcha.hpp"
    click GPUMetrics "https://github.com/ROCm/rocprofiler-systems/blob/amd-staging/source/lib/rocprof-sys/library/rocprofiler-sdk/counters.hpp"
    click CPUMetrics "https://github.com/ROCm/rocprofiler-systems/blob/amd-staging/source/lib/rocprof-sys/library/components/cpu_freq.hpp"
    click BinAnalysis "https://github.com/ROCm/rocprofiler-systems/tree/amd-staging/source/lib/binary/"
    click Runtime "https://github.com/ROCm/rocprofiler-systems/blob/amd-staging/source/lib/rocprof-sys/library/runtime.hpp"
    click Causal "https://github.com/ROCm/rocprofiler-systems/tree/amd-staging/source/lib/rocprof-sys/library/causal/"

    %% Legend
    subgraph Legend
        UI_L[User Interface]:::ui
        Core_L[Core Processing]:::core
        Int_L[Integration]:::integration
        Data_L[Data Management]:::data
        HW_L[Hardware Interface]:::hardware
    end
```
