ROC-TX library specification

ROC-TX library specification#

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

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

Note

The ROC-TX library provides rocTX API version 1.

Using the rocTX API#

To use the rocTX API, link the application with ROC-TX using the API header and dynamic library:

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

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

High-level overview#

ROC-TX library contains application code instrumentation APIs to support high-level correlation of runtime API or activity events.

Here is a list of useful APIs for code instrumentation.

  • roctxMark: Inserts a marker in the code with a message. Creating marks can help you see when a line of code is executed.

roctxMark("before hipLaunchKernel");

  • roctxRangeStart: Starts a range. Different threads can start ranges.

roctx_range_id_t roctx_id = roctxRangeStartA("roctx_range with ID");

  • roctxRangePush: Starts a new nested range.

roctxRangePush("ROCTX-RANGE: hipLaunchKernel");

  • roctxRangePop: Stops the current nested range.

roctxRangePop();

  • roctxRangeStop: Stops the given range.

roctxRangeStop(roctx_id);

Sample code#

To demonstrate the use of rocTX API with various options, this document refers to the MatrixTranspose application as an example.

A version of the MatrixTranspose application instrumented using the rocTX API is available in the rocprofiler/tests-v2 folder on GitHub.