rocm-systems/source/docs/how-to/using-pc-sampling.rst

.. meta::
  :description: Documentation of the usage of pc-sampling with rocprofv3 command-line tool
  :keywords: Sampling PC, Sampling program counter, rocprofv3, rocprofv3 tool usage, Using rocprofv3, ROCprofiler-SDK command line tool, PC sampling

.. _using-pc-sampling:

==================
Using PC sampling
==================

PC (Program Counter) sampling service for GPU profiling is a profiling technique to periodically sample the program counter during GPU kernel execution. PC sampling helps to understand code execution patterns and hotspots.

Here are the benefits of using PC sampling:

- Identify performance bottlenecks
- Understand kernel execution behavior
- Analyze code coverage
- Find heavily executed code paths

To try out the PC sampling feature, you can use the command-line tool ``rocprofv3`` or the ROCprofiler-SDK library on `ROCm 6.4` or later.

.. note::
  PC sampling is ONLY supported on AMD GPUs with architectures gfx90a and later.

PC sampling availability and configuration
===========================================

To check if the GPU supports PC sampling, use:

.. code-block:: bash

  rocprofv3 -L

Or

.. code-block:: bash

  rocprofv3 --list-avail

The output lists if ``rocprofv3`` supports PC sampling on the GPU and the supported configuration.

.. code-block:: bash

  List available PC Sample Configurations for node_id     11
  Method: ROCPROFILER_PC_SAMPLING_METHOD_HOST_TRAP
  Unit:   ROCPROFILER_PC_SAMPLING_UNIT_TIME
  Minimum_Interval:       1
  Maximum_Interval:       18446744073709551615

The preceding output shows that the GPU supports PC sampling with the ``ROCPROFILER_PC_SAMPLING_METHOD_HOST_TRAP`` method and the ``ROCPROFILER_PC_SAMPLING_UNIT_TIME`` unit. The minimum and maximum intervals are also displayed.

Based on the preceding configuration, you can use the following command to profile the application using PC sampling:

.. code-block:: bash

  rocprofv3 --pc-sampling-beta-enabled --pc-sampling-method host_trap --pc-sampling-unit time --pc-sampling-interval 1 -- <application_path>

The preceding command enables PC sampling with the ``host_trap`` method, ``time`` unit, and an interval of ``1`` μs (micro second). Replace ``<application_path>`` with the path to the application you want to profile.

This generates two files, ``agent_info.csv`` and ``pc_sampling_host_trap.csv``. Both files are prefixed with the process ID.

Here are the contents of ``pc_sampling_host_trap.csv`` file generated for MatrixTranspose sample application:

.. csv-table:: PC sampling host trap
   :file: /data/pc_sampling_host_trap.csv
   :widths: 20,10,10,10,10,20
   :header-rows: 1


For description of the fields in the output file, see :ref:`pc-sampling-fields`.

If you find the ``Instruction_Comment`` field in the output file to be empty, populate this field by compiling your application with debug symbols.
Enabling debug symbols while compiling the application maps back to the source line. This helps in understanding the code execution pattern and hotspots.

.. csv-table:: PC sampling host trap with debug symbols
   :file: /data/pc_sampling_host_trap_debug.csv
   :widths: 20,10,10,10,10,20
   :header-rows: 1


The preceding output shows the ``Instruction_Comment`` field populated with the source-line information.

.. _pc-sampling-fields:

PC sampling fields
===================

Here are the fields in the output file generated by PC sampling:

- ``Sample_Timestamp``: Timestamp when sample is generated
- ``Exec_Mask``: Active SIMD lanes when sampled
- ``Dispatch_Id``: Originating kernel dispatch ID
- ``Instruction``: Assembly instruction such as ``s_load_dword s8, s[1:2], 0x10``
- ``Instruction_Comment``: Instruction comment that maps back to the source-line if debug symbols were enabled when application was compiled
- ``Correlation_Id``: API launch call ID that matches dispatch ID

By default, the output file is in CSV format. To dump samples in a more comprehensive format, use JSON through ``--output-format json``:

.. code-block:: bash

  rocprofv3 --pc-sampling-beta-enabled --pc-sampling-method host_trap --pc-sampling-unit time --pc-sampling-interval 1 --output-format json -- <application_path>

The preceding command generates a JSON file with the comprehensive output. Here is a trimmed down output with multiple records:

.. code-block:: text

  {
    "pc_sample_host_trap": [
      {
        "record": {
          "hw_id": {
            "chiplet": 0,
            "wave_id": 0,
            "simd_id": 2,
            "pipe_id": 0,
            "cu_or_wgp_id": 1,
            "shader_array_id": 0,
            "shader_engine_id": 2,
            "workgroup_id": 0,
            "vm_id": 3,
            "queue_id": 2,
            "microengine_id": 1
          },
          "pc": {
            "code_object_id": 1,
            "code_object_offset": 20228
          },
          "exec_mask": 18446744073709551615,
          "timestamp": 51040126667689,
          "dispatch_id": 1,
          "corr_id": {
            "internal": 1,
            "external": 0
          },
          "wrkgrp_id": {
            "x": 182,
            "y": 0,
            "z": 0
          },
          "wave_in_grp": 1
        },
        "inst_index": 0
      },
      {
        "record": {
          "hw_id": {
            "chiplet": 0,
            "wave_id": 0,
            "simd_id": 2,
            "pipe_id": 0,
            "cu_or_wgp_id": 0,
            "shader_array_id": 0,
            "shader_engine_id": 2,
            "workgroup_id": 0,
            "vm_id": 3,
            "queue_id": 2,
            "microengine_id": 1
          },
          "pc": {
            "code_object_id": 1,
            "code_object_offset": 20236
          },
          "exec_mask": 18446744073709551615,
          "timestamp": 51040126667689,
          "dispatch_id": 1,
          "corr_id": {
            "internal": 1,
            "external": 0
          },
          "wrkgrp_id": {
            "x": 158,
            "y": 0,
            "z": 0
          },
          "wave_in_grp": 2
        },
        "inst_index": 1
      }
    ]
  }

For description of the fields in the JSON output, see :ref:`output-file-fields`.