ROCTracer documentation#

ROCTracer consists of the ROCTracer and ROC-TX libraries that provide APIs to help you trace an application in the runtime. runtime-independent APIs for tracing runtime calls and asynchronous activities such as GPU kernel dispatches and memory moves.

  • ROCTracer library

    The ROCTracer library provides runtime-independent APIs for tracing runtime calls and asynchronous activities such as GPU kernel dispatches and memory moves. The tracing includes callback APIs for runtime API tracing and activity APIs for asynchronous activity records logging. You can utilize these APIs to develop a tracing tool or to implement tracing in the application.

    See ROCTracer library specification for details.

  • ROC-TX library

    In certain situations, such as debugging performance issues in large-scale GPU programs, API-level tracing may be too fine-grained to provide a big picture of the program execution. In such cases, it is helpful to define specific tasks to be traced.

    To specify the tasks for tracing, enclose the respective source code with the API calls provided by Roctx. This process is also known as instrumentation. As the scope of code for instrumentation is defined using the enclosing API calls, it is called a range. A range is a programmer-defined task that has a well-defined start and end code scope. You can also fine grain the scope specified within a range using further nested ranges.

    See ROC-TX library specification for details.

Usage#

rocTracer API#

To use the rocTracer API, link the application with ROCTracer using the API header and dynamic library as shown below:

  • API header: /opt/rocm-{version}/include/roctracer/roctracer.h

  • Dynamic library (.so): /opt/rocm-{version}/lib/libroctracer64.so.<version major>

rocTX API#

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

  • API header: /opt/rocm-{version}/roctracer/include/roctx.h

  • Dynamic library (.so): /opt/rocm-{version}/lib/libroctx64.so.<version major>

Library source tree#

  • doc: documentation

  • inc: include header files

    • roctracer.h: ROCTracer library public API header

    • roctx.h: ROC-TX library public API header

  • src: library sources

    • roctracer: ROCTracer library API sources

    • roctx: ROC-TX library API sources

    • util: library util sources

  • test: test suit

    • MatrixTranspose: test based on HIP MatrixTranspose sample.

Code examples#

Prerequisites#

  • ROCm software

  • Install packages as per your system:

    • For Ubuntu 18.04 and Ubuntu 20.04:

    apt install python3 python3-pip gcc g++ libatomic1 make \
 cmake doxygen graphviz texlive-full

    • For CentOS 8.1 and RHEL 8.1:

    yum install -y python3 python3-pip gcc gcc-g++ make \
 cmake libatomic doxygen graphviz texlive \
 texlive-xtab texlive-multirow texlive-sectsty \
 texlive-tocloft texlive-tabu texlive-adjustbox

    • For SLES 15 Service Pack 15:

    zypper in python3 python3-pip gcc gcc-g++ make \
 cmake libatomic doxygen graphviz \
 texlive-scheme-medium texlive-hanging texlive-stackengine \
 texlive-tocloft texlive-etoc texlive-tabu

  • Install CppHeaderParser and argparse for Python modules:

    pip3 install CppHeaderParser argparse

Build and test#

Follow these steps to build ROCTracer:

  1. Clone development branch of roctracer:

git clone -b amd-master https://github.com/ROCm/roctracer

  1. Build ROCTracer library:

cd <your path>/roctracer
./build.sh

  1. Build and run test:

cd <your path>/roctracer/build
make mytest
run.sh

Installation#

Install using:

make install

or

make package && dpkg -i *.deb