ROCTx is an AMD tools extension library, a cross platform API for annotating code with markers and ranges. The ROCTx API is written in C++.
In certain situations, such as debugging performance issues in large-scale GPU programs, API-level tracing might be too fine-grained to provide an overview 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 the ROCTx library.
-**Push and Pop:** These can be nested to form a stack. The Pop call is automatically associated with a prior Push call on the same thread.
-**Start and End:** These may overlap with other ranges arbitrarily. The Start call returns a handle that must be passed to the End call. These ranges can start and end on different threads.
-``roctxProfilerPause``: Requests any currently running profiling tool to stop data collection.
-``roctxProfilerResume``: Requests any currently running profiling tool to resume data collection.
-``roctxGetThreadId``: Retrieves the ID for the current thread identical to the ID received using ``rocprofiler_get_thread_id(rocprofiler_thread_id_t*)``.
-``roctxNameOsThread``: Labels the current CPU OS thread in the profiling tool output with the provided name.
-``roctxNameHsaAgent``: Labels the given HSA agent in the profiling tool output with the provided name.
-``roctxNameHipDevice``: Labels the HIP device ID in the profiling tool output with the provided name.
-``roctxNameHipStream``: Labels the given HIP stream in the profiling tool output with the provided name.
Running the preceding command generates a ``marker_api_trace.csv`` file prefixed with the process ID.
..code-block::shell
$ cat 210_marker_api_trace.csv
Here are the contents of ``marker_api_trace.csv`` file:
..csv-table:: Marker api trace
:file:/data/marker_api_trace.csv
:widths:10,10,10,10,10,20,20
:header-rows:1
For the description of the fields in the output file, see :ref:`output-file-fields`.
``roctxProfilerPause`` and ``roctxProfilerResume`` can be used to hide the calls between them. This is useful when you want to hide the calls that are not relevant to your profiling session.
..code-block::bash
#include <rocprofiler-sdk-roctx/roctx.h>
// Memory transfer from host to device
HIP_API_CALL(hipMemcpy(gpuMatrix, Matrix, NUM * sizeof(float), hipMemcpyHostToDevice));
auto tid= roctx_thread_id_t{};
roctxGetThreadId(&tid);
roctxProfilerPause(tid);
// Memory transfer that should be hidden by profiling tool
HIP_API_CALL(
hipMemcpy(gpuTransposeMatrix, gpuMatrix, NUM * sizeof(float), hipMemcpyDeviceToDevice));
The preceding command generates a ``hip_api_trace.csv`` file prefixed with the process ID. The file contains two ``hipMemcpy`` calls with the in-between ``hipMemcpyDeviceToHost`` call hidden .
``ROCTx`` provides APIs to rename certain resources in the output generated by the profiling tool. You can pass the desired label for a specific resource in the output as an argument to the API. Note that ROCprofiler-SDK doesn't provide any explicit support for how profiling tools handle this request. Support for this capability is tool-specific.
The following table lists the APIs available for labeling the given resources:
ROCTx APIs can be used in a python application using the ``roctx`` module. The APIs are available as functions in the module. The API names are prefixed with ``roctx`` to avoid name conflicts with other libraries.
The following sample code from the MatrixTranspose application shows the usage of ROCTx APIs in a python application:
Before using the ``roctx`` module for python application, ensure that the ``roctx`` module is built, installed and available in your python environment.
An example to build and install ``roctx`` module is as follows:
If you are using a different python version, replace ``3.10`` with the appropriate version in the above command.
Multiple python versions can be specified in the ``ROCPROFILER_PYTHON_VERSIONS`` variable. The roctx module will be built and installed for all the specified python versions.
Based on the python major.minor version and the roctx module install path ("/opt/rocm" in above example), set the ``PYTHONPATH`` environment variable to include the path to the ``roctx`` module.
