Skip to content

roctracer

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

roctracer

README.md

ROC-tracer

Important

ROCTracer, ROCProfiler, rocprof, and rocprofv2 are deprecated. It's strongly recommended to upgrade to the latest version of the ROCprofiler-SDK library and the rocprofv3 tool to ensure continued support and access to new features. To learn about key feature improvements and benefits of ROCprofiler-SDK over the deprecated ROCProfiler and ROCTracer, see Comparing ROCprofiler-SDK to legacy ROCm profiling tools. It's anticipated that ROCTracer, ROCProfiler, rocprof, and rocprofv2 will reach end of support (EoS) by the end of 2026 Q2.

Note

The published documentation is available at ROCTracer in an organized, easy-to-read format, with search and a table of contents.

  • ROC-tracer library: Runtimes Generic Callback/Activity APIs

    The goal of the implementation is to provide a generic independent from specific runtime profiler to trace API and asynchronous activity.

    The API provides functionality for registering the runtimes API callbacks and asynchronous activity records pool support.

  • ROC-TX library: Code Annotation Events API

    Includes API for:

    • roctxMark
    • roctxRangePush
    • roctxRangePop

Usage

rocTracer API

To use the rocTracer API you need the API header and to link your application with roctracer .so library:

  • /opt/rocm/include/roctracer/roctracer.h

    API header.

  • /opt/rocm/lib/libroctracer64.so

    .so library.

rocTX API

To use the rocTX API you need the API header and to link your application with roctx .so library:

  • /opt/rocm/include/roctracer/roctx.h

    API header.

  • /opt/rocm/lib/libroctx64.so

    .so library.

Library source tree

  • doc

    Documentation.

  • inc

    Include header files.

    • roctracer.h

      rocTracer library public API header.

    • roctx.h

      rocTX library public API header.

  • src

    Library sources.

    • core

      rocTracer library API sources.

    • roctx

      rocTX library API sources.

    • util

      Library utils sources.

  • test

    Test suit.

    • MatrixTranspose

      Test based on HIP MatrixTranspose sample.

Documentation

Build and run tests

  • ROCm is required

  • Packages required:

    1. For Ubuntu 18.04 and Ubuntu 20.04 the following adds the needed packages:
    apt install python3 python3-pip gcc g++ libatomic1 make rocm-llvm-dev \
 cmake doxygen graphviz texlive-full
    1. For CentOS 8.1 and RHEL 8.1 the following adds the needed packages:
    yum install -y python3 python3-pip gcc gcc-g++ make rocm-llvm-devel \
 cmake libatomic doxygen graphviz texlive \
 texlive-xtab texlive-multirow texlive-sectsty \
 texlive-tocloft texlive-tabu texlive-adjustbox
    1. For SLES 15 Service Pack 15 the following adds the needed packages:
    zypper in python3 python3-pip gcc gcc-g++ make rocm-llvm-devel \
 cmake libatomic doxygen graphviz \
 texlive-scheme-medium texlive-hanging texlive-stackengine \
 texlive-tocloft texlive-etoc texlive-tabu

  • Python modules requirements: CppHeaderParser, argparse.

    To install:

    pip3 install CppHeaderParser argparse

  • Clone development branch of roctracer:

    git clone -b develop https://github.com/ROCm/rocm-systems.git

  • To build roctracer library:

    cd <your path>/rocm-systems/projects/roctracer
./build.sh

  • To build and run test:

    cd <your path>/rocm-systems/projects/roctracer/build
make mytest
run.sh

Installation

Install by:

make install

or:

make package && dpkg -i *.deb