How rocm/roctracer works
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.