migrate aqlprofile docs 7.0.1 from standalone repo (#1379)
This PR migrates the aqlprofile/docs folder from standalone repo to monorepo Link to the docs branch: https://github.com/ROCm/aqlprofile/commits/docs/7.0.1 --------- Co-authored-by: Matt Williams <matt.williams@amd.com> Co-authored-by: pbhandar-amd <138039281+pbhandar-amd@users.noreply.github.com>
This commit is contained in:
Saurabh Verma
GitHub
@@ -0,0 +1,112 @@
|
||||
.. meta::
|
||||
:description: A description of the APIs used with AQLprofile
|
||||
:keywords: AQLprofile, ROCm, APIs
|
||||
|
||||
AQLprofile APIs
|
||||
===============
|
||||
|
||||
Learn about the typical APIs used in AQLprofile.
|
||||
|
||||
The APIs in ``aqlprofile_v2.h`` are designed for use with `ROCprofiler-SDK <https://github.com/ROCm/rocprofiler-sdk>`__, and are actively maintained and recommended for all new development.
|
||||
|
||||
.. note::
|
||||
|
||||
The APIs in ``hsa_ven_amd_aqlprofile.h`` are used by legacy tools such as ``rocprof`` and ``rocprofv2``. You should use the new ``aqlprofile_v2.h`` APIs instead.
|
||||
|
||||
From header ``aql_profile_v2.h``
|
||||
--------------------------------
|
||||
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| API Name | Purpose |
|
||||
+====================================+==========================================================================================+
|
||||
| ``aqlprofile_register_agent`` | Registers an agent for profiling using basic agent info. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_register_agent_info`` | Registers an agent for profiling using extended agent info and versioning. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_get_pmc_info`` | Retrieves information about PMC profiles (for example, buffer sizes, counter data). |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_validate_pmc_event`` | Checks if a given PMC event is valid for the specified agent. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_pmc_create_packets`` | Creates AQL packets (start, stop, read) for PMC profiling and returns a handle. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_pmc_delete_packets`` | Deletes PMC profiling packets and releases associated resources. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_pmc_iterate_data`` | Iterates over PMC profiling results using a callback. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_att_create_packets`` | Creates AQL packets (start, stop) for Advanced Thread Trace (SQTT) and returns a handle. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_att_delete_packets`` | Deletes ATT profiling packets and releases associated resources. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_att_iterate_data`` | Iterates over thread trace (SQTT) results using a callback. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_iterate_event_ids`` | Iterates over all possible event coordinate IDs and names using a callback. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_iterate_event_coord`` | Iterates over all event coordinates for a given agent and event using a callback. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_att_codeobj_marker`` | Creates a marker packet for code object events in thread trace workflows. |
|
||||
+------------------------------------+------------------------------------------------------------------------------------------+
|
||||
|
||||
Callback Typedefs
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
+------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| Callback Typedef Name | Purpose |
|
||||
+==========================================+==========================================================================================+
|
||||
| ``aqlprofile_memory_alloc_callback_t`` | Callback for allocating memory buffers for profiles (PMC/ATT). |
|
||||
+------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_memory_dealloc_callback_t`` | Callback for deallocating memory buffers allocated for profiles. |
|
||||
+------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_memory_copy_t`` | Callback for copying memory (used internally by the profiler). |
|
||||
+------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_pmc_data_callback_t`` | Used with ``aqlprofile_pmc_iterate_data`` to process each PMC profiling result. |
|
||||
+------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_att_data_callback_t`` | Used with ``aqlprofile_att_iterate_data`` to process each thread trace (SQTT) result. |
|
||||
+------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_eventname_callback_t`` | Used with ``aqlprofile_iterate_event_ids`` to process event coordinate IDs and names. |
|
||||
+------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``aqlprofile_coordinate_callback_t`` | Used with ``aqlprofile_iterate_event_coord`` to process event coordinate information. |
|
||||
+------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
|
||||
From header ``hsa_ven_amd_aqlprofile.h`` (Legacy)
|
||||
-------------------------------------------------
|
||||
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| API Name | Purpose |
|
||||
+==================================================+==========================================================================================+
|
||||
| ``hsa_ven_amd_aqlprofile_validate_event`` | Checks if a given event (counter) is valid for the specified GPU agent. |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_start`` | Populates an AQL packet with commands to start profiling (PMC or SQTT). |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_stop`` | Populates an AQL packet with commands to stop profiling. |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_read`` | Populates an AQL packet with commands to read profiling results from the GPU. |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_legacy_get_pm4`` | Converts an AQL packet to a PM4 packet blob (for legacy devices). |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_att_marker`` | Inserts a marker (correlation ID) into the ATT (thread trace) buffer. |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_get_info`` | Retrieves various profile information, such as buffer sizes or collected data. |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_iterate_data`` | Iterates over the profiling output data (PMC results or SQTT trace) using a callback. |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_error_string`` | Returns a human-readable error string for the last error. |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_iterate_event_ids`` | Iterates over all possible event IDs and names for the agent. |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_iterate_event_coord`` | Iterates over all event coordinates for a given agent and event. |
|
||||
+--------------------------------------------------+------------------------------------------------------------------------------------------+
|
||||
|
||||
.. _callback-typedefs-1:
|
||||
|
||||
Callback Typedefs
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
+---------------------------------------------------+------------------------------------------------------------------------------------------------+
|
||||
| Callback Typedef Name | Purpose |
|
||||
+===================================================+================================================================================================+
|
||||
| ``hsa_ven_amd_aqlprofile_data_callback_t`` | Used with ``hsa_ven_amd_aqlprofile_iterate_data`` to process each profiling result (PMC/SQTT). |
|
||||
+---------------------------------------------------+------------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_eventname_callback_t`` | Used with ``hsa_ven_amd_aqlprofile_iterate_event_ids`` to process event IDs and names. |
|
||||
+---------------------------------------------------+------------------------------------------------------------------------------------------------+
|
||||
| ``hsa_ven_amd_aqlprofile_coordinate_callback_t`` | Used with ``hsa_ven_amd_aqlprofile_iterate_event_coord`` to process event coordinate info. |
|
||||
+---------------------------------------------------+------------------------------------------------------------------------------------------------+
|
||||
@@ -0,0 +1,109 @@
|
||||
.. meta::
|
||||
:description: Defined concepts commonly used in AQLprofile
|
||||
:keywords: AQLprofile, ROCm
|
||||
|
||||
AQLprofile glossary
|
||||
===================
|
||||
|
||||
Learn the definitions of concepts commonly used in AQLprofile.
|
||||
|
||||
Agents
|
||||
------
|
||||
|
||||
Agents represent computational devices (CPUs, GPUs) in the Heterogeneous
|
||||
System Architecture (HSA) runtime. In AQLprofile, agents are discovered
|
||||
via HSA APIs and encapsulated in the ``AgentInfo`` structure. Each agent
|
||||
contains metadata including device type, name, compute unit count, and
|
||||
memory pools.
|
||||
|
||||
Agents are enumerated using HSA API ``hsa_iterate_agents``, and their
|
||||
properties are queried via another HSA API, ``hsa_agent_get_info``.
|
||||
Agents are used to target specific GPUs for profiling, and to allocate
|
||||
resources such as command buffers and memory pools.
|
||||
|
||||
Counters and events
|
||||
-------------------
|
||||
|
||||
Performance counters are special circuits on the hardware that count
|
||||
specific GPU events (for example, cycles, instructions, cache hits). Events
|
||||
specify which counters to collect, identified by block name, block
|
||||
index, and counter ID.
|
||||
|
||||
- Events are described using ``hsa_ven_amd_aqlprofile_event_t``
|
||||
structures.
|
||||
- Events are grouped into profiles and collected during profiling
|
||||
sessions.
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
const hsa_ven_amd_aqlprofile_event_t events_arr1[] = {
|
||||
{HSA_VEN_AMD_AQLPROFILE_BLOCK_NAME_SQ, 0, 2 /*CYCLES*/},
|
||||
{HSA_VEN_AMD_AQLPROFILE_BLOCK_NAME_SQ, 0, 3 /*BUSY_CYCLES*/},
|
||||
// ...
|
||||
};
|
||||
|
||||
Counter blocks
|
||||
--------------
|
||||
|
||||
Counter blocks correspond to hardware units on the GPU (for example, SQ, TCC,
|
||||
TCP). Each block exposes a set of counters/events.
|
||||
|
||||
- Block names (for example, ``HSA_VEN_AMD_AQLPROFILE_BLOCK_NAME_SQ``) map to
|
||||
specific hardware blocks.
|
||||
- Events specify both the block and the counter within that block.
|
||||
|
||||
Command buffers
|
||||
---------------
|
||||
|
||||
Command buffers are memory regions that store AQL packets and PM4
|
||||
commands, which control GPU profiling operations. They're allocated per
|
||||
agent, and must meet alignment and size requirements dictated by the
|
||||
hardware.
|
||||
|
||||
Command packets
|
||||
---------------
|
||||
|
||||
Command packets are AQL or PM4 packets that encode profiling commands
|
||||
for the GPU. They're constructed and written into command buffers.
|
||||
|
||||
They're built using AQLprofile APIs or helper functions and submitted to
|
||||
the GPU via HSA queues.
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
bool Queue::Submit(hsa_ext_amd_aql_pm4_packet_t* packet) {
|
||||
// Write packet to queue and signal doorbell
|
||||
}
|
||||
|
||||
Output buffer
|
||||
-------------
|
||||
|
||||
Output buffers are memory regions that store outputs such as counter
|
||||
values and thread trace tokens. They're allocated using HSA memory pools
|
||||
associated with the agent.
|
||||
|
||||
Profile object
|
||||
--------------
|
||||
|
||||
The profile object encapsulates all information required to perform a
|
||||
profiling session. It's represented by the
|
||||
``hsa_ven_amd_aqlprofile_profile_t`` struct, which includes the agent,
|
||||
event type, list of events, command buffer, and additional parameters.
|
||||
|
||||
Profile objects are constructed by specifying the agent, event type
|
||||
(PMC, SQTT), events to collect, and associated buffers. They're passed
|
||||
to AQLprofile APIs to start, stop, and read profiling data.
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
hsa_ven_amd_aqlprofile_profile_t *profile =
|
||||
new hsa_ven_amd_aqlprofile_profile_t{
|
||||
agent_info->dev_id,
|
||||
HSA_VEN_AMD_AQLPROFILE_EVENT_TYPE_PMC,
|
||||
events,
|
||||
num_events,
|
||||
NULL,
|
||||
0,
|
||||
0,
|
||||
0};
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
.. meta::
|
||||
:description: A list of the supported architectures and counter blocks used with AQLprofile
|
||||
:keywords: AQLprofile, ROCm, architectures, GFX
|
||||
|
||||
Supported architectures and counter blocks in AQLprofile
|
||||
========================================================
|
||||
|
||||
The AQLprofile library supports profiling and tracing GPU workloads
|
||||
across multiple architectures.
|
||||
|
||||
.. note::
|
||||
|
||||
The GFX versions (GFX9XX, GFX10XX, GFX11XX, GFX12XX) refer to the architecture families of the hardware for that version. See `System requirements (Linux) <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html>`__ for more info.
|
||||
|
||||
Here's a summary of the counter blocks supported for each architecture:
|
||||
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| Counter | GFX9 | GFX908 | GFX90A | GFX942 | GFX10| GFX11|GFX12|
|
||||
| Block Name | | | | | | | |
|
||||
+=============+======+========+========+========+======+======+=====+
|
||||
| ATC | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| ATC_L2 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| CHA | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| CHC | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| CPC | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| CPF | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| CPG | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GCEA | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GCR | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GDS | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GL1A | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GL1C | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GL2A | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GL2C | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GRBM | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GRBMH | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GRBM_SE | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| GUS | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| MC_VM_L2 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| RPB | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| SDMA | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| SPI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| SQ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| SQ_CS | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| TA | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| TCA | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| TCC | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| TCP | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
| TD | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
|
||||
Reference in New Issue
Block a user