# rocm/roctracer architecture

> Architecture diagram of the GitHub repository rocm/roctracer, 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/roctracer
- Repository: https://github.com/rocm/roctracer

## Overview

##### Project Type and Purpose
- This is an open-source C/C++ library suite (ROC-tracer) for AMD’s ROCm stack providing:
- roctracer: generic runtime API callback and asynchronous activity tracing across HSA, HIP, HCC, etc.
- roctx: code-annotation (marker) API.
- tracer_tool and hip_stats: companion command-line tools to consume trace data.
- The library is delivered as shared objects (`libroctracer64.so`, `libroctx64.so`) and supports a plugin mechanism to export and write trace output.

##### File Structure Analysis
- Top-level build/config: CMakeLists.txt, build scripts (`build.sh`, `defaults.sh`), CI pipelines (.azuredevops, .github).
- inc/: Public headers (`roctracer.h`, `roctx.h`) and extension protocol (`prof_protocol.h`).
- src/: Core implementation:
- src/roctracer: loader, registration table, callback dispatch, async activity pool.
- src/roctx: marker implementation.
- src/tracer_tool: standalone trace consumer.
- src/hip_stats: HIP-specific summary statistics tool.
- src/util: logging, XML serialization, debugging helpers.
- plugin/: File-output plugin (implements profiler plugin interface to write trace records to disk).
- script/: Utilities to generate boilerplate (`gen_ostream_ops.py`), validate traces (`check_trace.py`), parse HSA APIs.
- test/: Unit and integration tests for each runtime and golden-trace validation.

##### Key Insights from README
- The library abstracts over multiple runtimes via a callback registry and activity record pools.
- Users link against the shared library and include public headers.
- A plugin interface allows output sinks (the provided “file” plugin writes to text files).
- Companion tools (tracer_tool, hip_stats) consume recorded trace buffers.

##### Detail without Over-Simplification
- Core sub-components (loader, registry, pools) as separate nodes.
- Plugin exportmap entry points.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    ClientApp["Client Application"]:::external

    %% Public API Layer
    subgraph "Public API (inc/)"
        RoctracerHeader["roctracer.h"]:::api
        RoctracerExtHeader["roctracer_ext.h"]:::api
        RoctxHeader["roctx.h"]:::api
        RoctracerRoctxHeader["roctracer_roctx.h"]:::api
        ProfProtocol["prof_protocol.h"]:::api
    end

    %% Core Library
    subgraph "Core Library"
        subgraph "roctracer Core"
            Loader["Loader"]:::core
            CallbackMgr["Callback Manager"]:::core
            ActivityPool["Activity Pool"]:::core
            RegTable["Registration Table"]:::core
            HsaSupport["HSA/HIP Runtime Hooks"]:::core
            ExportmapRTC["Exportmap"]:::core
        end
        subgraph "roctx Core"
            RoctxCore["roctx Marker API"]:::core
            ExportmapROCTX["Exportmap"]:::core
        end
    end

    %% Plugin System
    subgraph "Plugin System"
        FilePlugin["File Plugin"]:::plugin
        PluginExportmap["Plugin Exportmap"]:::plugin
    end

    %% Tools
    subgraph "Tools"
        TracerTool["tracer_tool"]:::tool
        HipStats["hip_stats"]:::tool
    end

    %% Utility Modules
    subgraph "Utility Modules"
        Logger["logger.h"]:::util
        UtilCpp["util.cpp"]:::util
        UtilH["util.h"]:::util
        DebugCpp["debug.cpp"]:::util
        DebugH["debug.h"]:::util
        XML["xml.h"]:::util
    end

    %% Scripts
    subgraph "Scripts"
        GenOps["gen_ostream_ops.py"]:::script
        CheckTrace["check_trace.py"]:::script
        HsaAp["hsaap.py"]:::script
    end

    %% Build & CI
    subgraph "Build & CI"
        TopCmake["CMakeLists.txt"]:::build
        SrcCmake["src/CMakeLists.txt"]:::build
        PluginCmake["plugin/CMakeLists.txt"]:::build
        BuildSh["build.sh"]:::build
        DefaultsSh["defaults.sh"]:::build
        CI[".github/workflows/rocm-ci-caller.yml"]:::build
    end

    %% External Runtimes and Storage
    HsaRuntime["HSA/HIP Runtime"]:::external
    Disk["Disk / Trace Files"]:::storage

    %% Tests
    subgraph "Tests"
        RoctxTest["roctx_test.cpp"]:::test
        ActivityCallbackTest["activity_and_callback.cpp"]:::test
        MemoryPoolTest["memory_pool.cpp"]:::test
    end

    %% Relationships
    ClientApp -->|"links/shared library"| Loader
    ClientApp -->|"includes headers"| RoctracerHeader
    ClientApp -->|"includes headers"| RoctxHeader

    Loader -->|"registers callbacks"| CallbackMgr
    Loader -->|"hooks into"| HsaRuntime
    HsaRuntime -->|"invokes hooks"| Loader

    CallbackMgr -->|"dispatches events"| ActivityPool
    CallbackMgr -->|"updates"| RegTable

    ActivityPool -->|"provides records"| FilePlugin
    RoctxCore -->|"marker calls"| FilePlugin

    FilePlugin -->|"writes binary record"| Disk

    Disk -->|"consumes trace"| TracerTool
    Disk -->|"consumes trace"| HipStats

    GenOps -->|"generates boilerplate"| Loader
    CheckTrace -->|"validates trace"| Disk
    HsaAp -->|"parses HSA APIs"| Loader

    TopCmake -->|"build orchestration"| Loader
    SrcCmake -->|"module build"| Loader
    PluginCmake -->|"plugin build"| FilePlugin
    BuildSh -->|"build script"| Loader
    DefaultsSh -->|"defaults"| Loader
    CI -->|"CI pipeline"| TopCmake

    Logger -->|"used by"| Loader
    UtilCpp -->|"used by"| ActivityPool
    DebugCpp -->|"used by"| Loader
    XML -->|"serializes"| ActivityPool

    Loader -->|"tested by"| RoctxTest
    ActivityPool -->|"tested by"| ActivityCallbackTest
    ActivityPool -->|"tested by"| MemoryPoolTest

    %% Click Events
    click Loader "https://github.com/rocm/roctracer/blob/amd-staging/src/roctracer/loader.h"
    click RegTable "https://github.com/rocm/roctracer/blob/amd-staging/src/roctracer/registration_table.h"
    click ActivityPool "https://github.com/rocm/roctracer/blob/amd-staging/src/roctracer/memory_pool.h"
    click HsaSupport "https://github.com/rocm/roctracer/blob/amd-staging/src/roctracer/hsa_support.cpp"
    click ExportmapRTC "https://github.com/rocm/roctracer/tree/amd-staging/src/roctracer/exportmap/"
    click RoctracerHeader "https://github.com/rocm/roctracer/blob/amd-staging/inc/roctracer.h"
    click RoctracerExtHeader "https://github.com/rocm/roctracer/blob/amd-staging/inc/roctracer_ext.h"

    click RoctxCore "https://github.com/rocm/roctracer/blob/amd-staging/src/roctx/roctx.cpp"
    click ExportmapROCTX "https://github.com/rocm/roctracer/tree/amd-staging/src/roctx/exportmap/"
    click RoctxHeader "https://github.com/rocm/roctracer/blob/amd-staging/inc/roctx.h"
    click RoctracerRoctxHeader "https://github.com/rocm/roctracer/blob/amd-staging/inc/roctracer_roctx.h"

    click FilePlugin "https://github.com/rocm/roctracer/blob/amd-staging/plugin/file/file.cpp"
    click PluginCmake "https://github.com/rocm/roctracer/blob/amd-staging/plugin/file/CMakeLists.txt"
    click PluginExportmap "https://github.com/rocm/roctracer/tree/amd-staging/plugin/exportmap"

    click TracerTool "https://github.com/rocm/roctracer/blob/amd-staging/src/tracer_tool/tracer_tool.cpp"
    click trace_buffer "https://github.com/rocm/roctracer/blob/amd-staging/src/tracer_tool/trace_buffer.h"
    click HipStats "https://github.com/rocm/roctracer/blob/amd-staging/src/hip_stats/hip_stats.cpp"

    click Logger "https://github.com/rocm/roctracer/blob/amd-staging/src/util/logger.h"
    click UtilCpp "https://github.com/rocm/roctracer/blob/amd-staging/src/util/util.cpp"
    click UtilH "https://github.com/rocm/roctracer/blob/amd-staging/src/util/util.h"
    click DebugCpp "https://github.com/rocm/roctracer/blob/amd-staging/src/util/debug.cpp"
    click DebugH "https://github.com/rocm/roctracer/blob/amd-staging/src/util/debug.h"
    click XML "https://github.com/rocm/roctracer/blob/amd-staging/src/util/xml.h"

    click GenOps "https://github.com/rocm/roctracer/blob/amd-staging/script/gen_ostream_ops.py"
    click CheckTrace "https://github.com/rocm/roctracer/blob/amd-staging/script/check_trace.py"
    click HsaAp "https://github.com/rocm/roctracer/blob/amd-staging/script/hsaap.py"

    click TopCmake "https://github.com/rocm/roctracer/blob/amd-staging/CMakeLists.txt"
    click SrcCmake "https://github.com/rocm/roctracer/blob/amd-staging/src/CMakeLists.txt"
    click BuildSh "https://github.com/rocm/roctracer/blob/amd-staging/build.sh"
    click DefaultsSh "https://github.com/rocm/roctracer/blob/amd-staging/defaults.sh"
    click CI "https://github.com/rocm/roctracer/blob/amd-staging/.github/workflows/rocm-ci-caller.yml"

    click RoctxTest "https://github.com/rocm/roctracer/blob/amd-staging/test/app/roctx_test.cpp"
    click ActivityCallbackTest "https://github.com/rocm/roctracer/blob/amd-staging/test/directed/activity_and_callback.cpp"
    click MemoryPoolTest "https://github.com/rocm/roctracer/blob/amd-staging/test/directed/memory_pool.cpp"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef plugin fill:#fbf,stroke:#333,stroke-width:1px
    classDef tool fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ffe,stroke:#333,stroke-width:1px
    classDef storage fill:#ffd,stroke:#333,stroke-width:1px
    classDef build fill:#ccc,stroke:#333,stroke-width:1px
    classDef script fill:#cfc,stroke:#333,stroke-width:1px
    classDef util fill:#ddf,stroke:#333,stroke-width:1px
    classDef test fill:#fdd,stroke:#333,stroke-width:1px
```
