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>
このコミットが含まれているのは:
Saurabh Verma
GitHub
@@ -0,0 +1,18 @@
|
||||
# Read the Docs configuration file
|
||||
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
|
||||
|
||||
version: 2
|
||||
|
||||
sphinx:
|
||||
configuration: docs/conf.py
|
||||
|
||||
formats: [htmlzip]
|
||||
|
||||
python:
|
||||
install:
|
||||
- requirements: docs/sphinx/requirements.txt
|
||||
|
||||
build:
|
||||
os: ubuntu-22.04
|
||||
tools:
|
||||
python: "3.10"
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file only contains a selection of the most common options. For a full
|
||||
# list see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
import re
|
||||
|
||||
'''
|
||||
html_theme is usually unchanged (rocm_docs_theme).
|
||||
flavor defines the site header display, select the flavor for the corresponding portals
|
||||
flavor options: rocm, rocm-docs-home, rocm-blogs, rocm-ds, instinct, ai-developer-hub, local, generic
|
||||
'''
|
||||
html_theme = "rocm_docs_theme"
|
||||
html_theme_options = {"flavor": "rocm-docs-home"}
|
||||
|
||||
|
||||
# This section turns on/off article info
|
||||
setting_all_article_info = True
|
||||
all_article_info_os = ["linux"]
|
||||
all_article_info_author = ""
|
||||
|
||||
# Dynamically extract component version
|
||||
# with open('../CMakeLists.txt', encoding='utf-8') as f:
|
||||
# pattern = r'.*\brocm_setup_version\(VERSION\s+([0-9.]+)[^0-9.]+' # Update according to each component's CMakeLists.txt
|
||||
# match = re.search(pattern,
|
||||
# f.read())
|
||||
# if not match:
|
||||
# raise ValueError("VERSION not found!")
|
||||
version_number = "1.0"
|
||||
|
||||
# for PDF output on Read the Docs
|
||||
project = "AQLprofile"
|
||||
author = "Advanced Micro Devices, Inc."
|
||||
copyright = "Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved."
|
||||
version = version_number
|
||||
release = version_number
|
||||
|
||||
external_toc_path = "./sphinx/_toc.yml" # Defines Table of Content structure definition path
|
||||
|
||||
'''
|
||||
Doxygen Settings
|
||||
Ensure Doxyfile is located at docs/doxygen.
|
||||
If the component does not need doxygen, delete this section for optimal build time
|
||||
'''
|
||||
#doxygen_root = "doxygen"
|
||||
#doxysphinx_enabled = False
|
||||
# doxygen_project = {
|
||||
# "name": "doxygen",
|
||||
# "path": "doxygen/xml",
|
||||
#}
|
||||
|
||||
# Add more addtional package accordingly
|
||||
extensions = [
|
||||
"rocm_docs",
|
||||
# "rocm_docs.doxygen",
|
||||
]
|
||||
|
||||
html_title = f"{project} {version_number} documentation"
|
||||
|
||||
external_projects_current_project = "AQLprofile"
|
||||
@@ -0,0 +1,109 @@
|
||||
.. meta::
|
||||
:description: A typical workflow for collecting PMC data
|
||||
:keywords: AQLprofile, ROCm, API, how-to, PMC
|
||||
|
||||
**********************************************************
|
||||
Performance Monitor Control (PMC) workflow with AQLprofile
|
||||
**********************************************************
|
||||
|
||||
This page describes a typical workflow for collecting PMC data using AQLprofile (as integrated in `ROCprofiler-SDK <https://github.com/ROCm/rocprofiler-sdk>`__).
|
||||
This workflow relies on creating a profile object, generating command packets, and iterating over output buffers:
|
||||
|
||||
1. **Intercept kernel dispatch**: The SDK intercepts kernel dispatch packets submitted to the GPU queue.
|
||||
2. **Create a profile object**: A profile/session object is created, specifying the agent (GPU), events (counters), and output buffers.
|
||||
3. **Generate command packets**: Start, stop, and read command packets are generated and injected into the queue around the kernel dispatch.
|
||||
4. **Submit packets and run the kernel**: The kernel and profiling packets are submitted to the GPU queue for execution.
|
||||
5. **Collect the output buffer**: After execution, the output buffer is read back from the GPU.
|
||||
6. **Iterate and extract the results**: The SDK iterates over the output buffer to extract and report counter results.
|
||||
|
||||
The SDK abstracts queue interception and packet management so tool developers can focus on results.
|
||||
|
||||
Key API code snippets
|
||||
=====================
|
||||
|
||||
These API snippets use the legacy interfaces from ``hsa_ven_amd_aqlprofile.h``. These are provided for understanding purposes only.
|
||||
For new development, refer to the updated APIs in ``aql_profile_v2.h``.
|
||||
|
||||
.. note::
|
||||
|
||||
The ROCprofiler-SDK is migrating to these newer interfaces in ``aql_profile_v2.h``. You should use the APIs in ``aql_profile_v2.h`` to stay up-to-date.
|
||||
|
||||
Define the events and profile
|
||||
-----------------------------
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
// Select events (counters) to collect
|
||||
hsa_ven_amd_aqlprofile_event_t events[] = {
|
||||
{ HSA_VEN_AMD_AQLPROFILE_BLOCK_NAME_SQ, 0, 2 }, // Example: SQ block, instance 0, counter 2
|
||||
{ HSA_VEN_AMD_AQLPROFILE_BLOCK_NAME_SQ, 0, 3 }
|
||||
};
|
||||
|
||||
// Create profile object
|
||||
hsa_ven_amd_aqlprofile_profile_t profile = {
|
||||
.agent = agent, // hsa_agent_t
|
||||
.type = HSA_VEN_AMD_AQLPROFILE_EVENT_TYPE_PMC,
|
||||
.events = events,
|
||||
.event_count = sizeof(events)/sizeof(events[0]),
|
||||
.parameters = nullptr,
|
||||
.parameter_count = 0,
|
||||
.output_buffer = {output_ptr, output_size},
|
||||
.command_buffer = {cmd_ptr, cmd_size}
|
||||
};
|
||||
|
||||
|
||||
Validate events
|
||||
---------------
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
bool valid = false;
|
||||
hsa_ven_amd_aqlprofile_validate_event(agent, &events[0], &valid);
|
||||
if (!valid) {
|
||||
// Handle invalid event
|
||||
}
|
||||
|
||||
|
||||
Generate command packets
|
||||
-------------------------
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
hsa_ext_amd_aql_pm4_packet_t start_pkt, stop_pkt, read_pkt;
|
||||
hsa_ven_amd_aqlprofile_start(&profile, &start_pkt);
|
||||
hsa_ven_amd_aqlprofile_stop(&profile, &stop_pkt);
|
||||
hsa_ven_amd_aqlprofile_read(&profile, &read_pkt);
|
||||
|
||||
|
||||
Submit packets and run the kernel
|
||||
---------------------------------
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
// Pseudocode: inject packets into HSA queue
|
||||
queue->Submit(&start_pkt);
|
||||
queue->Submit(&kernel_pkt);
|
||||
queue->Submit(&stop_pkt);
|
||||
queue->Submit(&read_pkt);
|
||||
|
||||
|
||||
Iterate and extract results
|
||||
----------------------------
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
hsa_ven_amd_aqlprofile_iterate_data(
|
||||
&profile,
|
||||
[](hsa_ven_amd_aqlprofile_info_type_t info_type,
|
||||
hsa_ven_amd_aqlprofile_info_data_t* info_data,
|
||||
void* user_data) -> hsa_status_t {
|
||||
if (info_type == HSA_VEN_AMD_AQLPROFILE_INFO_PMC_DATA) {
|
||||
printf("Event: block %d, id %d, value: %llu\n",
|
||||
info_data->pmc_data.event.block_name,
|
||||
info_data->pmc_data.event.counter_id,
|
||||
info_data->pmc_data.result);
|
||||
}
|
||||
return HSA_STATUS_SUCCESS;
|
||||
},
|
||||
nullptr
|
||||
);
|
||||
@@ -0,0 +1,93 @@
|
||||
.. meta::
|
||||
:description: A typical workflow for collecting detailed instruction-level traces
|
||||
:keywords: AQLprofile, ROCm, API, how-to, SQTT
|
||||
|
||||
***********************************************
|
||||
SQ Thread Trace (SQTT) workflow with AQLprofile
|
||||
***********************************************
|
||||
|
||||
The SQ Thread Trace workflow focuses on collecting detailed instruction-level traces.
|
||||
This workflow relies on creating a profile object, generating command packets, and iterating over output buffers:
|
||||
|
||||
1. **Intercept the kernel dispatch**: The SDK intercepts the kernel dispatch.
|
||||
2. **Create a SQTT profile object**: A profile object is created for SQTT, specifying trace parameters and output buffers.
|
||||
3. **Generate SQTT command packets**: Start, stop, and read packets for SQTT are generated and injected into the queue.
|
||||
4. **Submit packets and run the kernel**: The kernel and SQTT packets are submitted for execution.
|
||||
5. **Collect the trace buffer**: The trace output buffer is collected after execution.
|
||||
6. **Iterate and decode trace data**: The SDK iterates over the trace buffer and decodes the SQTT data for analysis.
|
||||
|
||||
The SDK abstracts queue interception and packet management so tool developers can focus on results.
|
||||
|
||||
Key API code snippets
|
||||
=====================
|
||||
|
||||
These API snippets use the legacy interfaces from ``hsa_ven_amd_aqlprofile.h``. These are provided for understanding purposes only.
|
||||
For new development, refer to the updated APIs in ``aql_profile_v2.h``.
|
||||
|
||||
In the `ROCprofiler-SDK <https://github.com/ROCm/rocprofiler-sdk>`__ codebase, these APIs are wrapped and orchestrated in the ``aql``, ``hsa``, and ``thread_trace`` folders for queue interception, packet construction, and result iteration.
|
||||
|
||||
.. note::
|
||||
|
||||
The`ROCprofiler-SDK is migrating to these newer interfaces in ``aql_profile_v2.h``. You should use the APIs in ``aql_profile_v2.h`` to stay up-to-date.
|
||||
|
||||
Define parameters and profile
|
||||
------------------------------
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
hsa_ven_amd_aqlprofile_parameter_t params[] = {
|
||||
{ HSA_VEN_AMD_AQLPROFILE_PARAMETER_NAME_ATT_BUFFER_SIZE, 0x1000000} // 16 MB buffer
|
||||
};
|
||||
|
||||
hsa_ven_amd_aqlprofile_profile_t profile = {
|
||||
.agent = agent,
|
||||
.type = HSA_VEN_AMD_AQLPROFILE_EVENT_TYPE_TRACE,
|
||||
.events = nullptr,
|
||||
.event_count = 0,
|
||||
.parameters = params,
|
||||
.parameter_count = sizeof(params)/sizeof(params[0]),
|
||||
.output_buffer = {trace_ptr, trace_size},
|
||||
.command_buffer = {cmd_ptr, cmd_size}
|
||||
};
|
||||
|
||||
|
||||
Generate SQTT start/stop packets
|
||||
---------------------------------
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
hsa_ext_amd_aql_pm4_packet_t sqtt_start_pkt, sqtt_stop_pkt;
|
||||
hsa_ven_amd_aqlprofile_start(&profile, &sqtt_start_pkt);
|
||||
hsa_ven_amd_aqlprofile_stop(&profile, &sqtt_stop_pkt);
|
||||
|
||||
|
||||
Submit packets and run the kernel
|
||||
---------------------------------
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
queue->Submit(&sqtt_start_pkt);
|
||||
queue->Submit(&kernel_pkt);
|
||||
queue->Submit(&sqtt_stop_pkt);
|
||||
|
||||
|
||||
Iterate and decode trace data
|
||||
-----------------------------
|
||||
|
||||
.. code:: cpp
|
||||
|
||||
hsa_ven_amd_aqlprofile_iterate_data(
|
||||
&profile,
|
||||
[](hsa_ven_amd_aqlprofile_info_type_t info_type,
|
||||
hsa_ven_amd_aqlprofile_info_data_t* info_data,
|
||||
void* user_data) -> hsa_status_t {
|
||||
if (info_type == HSA_VEN_AMD_AQLPROFILE_INFO_TRACE_DATA) {
|
||||
// info_data->trace_data.ptr, info_data->trace_data.size
|
||||
decode_trace(info_data->trace_data.ptr, info_data->trace_data.size);
|
||||
}
|
||||
return HSA_STATUS_SUCCESS;
|
||||
},
|
||||
nullptr
|
||||
);
|
||||
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
.. meta::
|
||||
:description: AQLprofile is an open source library that enables advanced GPU profiling and tracing on AMD platforms.
|
||||
:keywords: AQLprofile, ROCm, tool, Instinct, accelerator, AMD
|
||||
|
||||
.. _index:
|
||||
|
||||
************************
|
||||
AQLprofile documentation
|
||||
************************
|
||||
|
||||
The Architected Queuing Language profiling library (AQLprofile) is an
|
||||
open source library that enables advanced GPU profiling and tracing on
|
||||
AMD platforms.
|
||||
|
||||
This documentation provides a comprehensive overview of the AQLprofile library.
|
||||
|
||||
If you're new to AQLprofile, see :doc:`What is AQLprofile? <what-is-aqlprofile>`.
|
||||
|
||||
AQLprofile is open source and hosted at `AQLprofile on GitHub <https://github.com/ROCm/aqlprofile>`_.
|
||||
|
||||
.. grid:: 2
|
||||
:gutter: 3
|
||||
|
||||
.. grid-item-card:: Install
|
||||
|
||||
* :doc:`Install AQLprofile <install/aqlprofile-install>`
|
||||
|
||||
.. grid-item-card:: Examples
|
||||
|
||||
* :doc:`Performance Monitor Control (PMC) workflow <examples/pmc-workflow>`
|
||||
* :doc:`SQ Thread Trace (SQTT) workflow <examples/sqtt-workflow>`
|
||||
|
||||
.. grid-item-card:: Reference
|
||||
|
||||
* :doc:`Glossary <reference/glossary>`
|
||||
* :doc:`Supported architectures and counter blocks <reference/supported-architectures>`
|
||||
* :doc:`APIs <reference/api-list>`
|
||||
|
||||
|
||||
To contribute to the documentation, refer to
|
||||
`Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
|
||||
|
||||
You can find licensing information on the
|
||||
`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.
|
||||
@@ -0,0 +1,77 @@
|
||||
.. meta::
|
||||
:description: AQLprofile installation process
|
||||
:keywords: AQLprofile, ROCm, install
|
||||
|
||||
******************
|
||||
Install AQLprofile
|
||||
******************
|
||||
|
||||
Learn how to build AQLprofile with a script or with CMake, then install the library with a command.
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
Before you begin, ensure these tools and dependencies are installed:
|
||||
|
||||
* ROCm stack
|
||||
* ``rocm-llvm-dev`` (required to build tests)
|
||||
|
||||
|
||||
Build AQLprofile
|
||||
================
|
||||
|
||||
You can build AQLprofile using either the provided build script (recommended for most users) or by manually invoking CMake for custom builds.
|
||||
|
||||
|
||||
Option 1: Use the build script (Recommended)
|
||||
--------------------------------------------
|
||||
|
||||
This configures and builds the project with the default settings:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
./build.sh
|
||||
|
||||
|
||||
Option 2: Use CMake for custom builds
|
||||
-------------------------------------
|
||||
|
||||
For more control over the build process, you can set the CMake options manually:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
# Set the CMAKE_PREFIX_PATH to point to hsa-runtime includes path and hsa-runtime library path
|
||||
export CMAKE_PREFIX_PATH=<path to hsa-runtime includes>:<path to hsa-runtime library>
|
||||
# For example, if ROCm is installed at /opt/rocm:
|
||||
# export CMAKE_PREFIX_PATH=/opt/rocm/lib:/opt/rocm/include/hsa
|
||||
|
||||
export CMAKE_BUILD_TYPE=<debug|release> # release by default
|
||||
|
||||
cd /path/to/aqlprofile
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
make -j
|
||||
|
||||
|
||||
Enable debug tracing (Optional)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To enable debug tracing, set this environment variable before running CMake:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
export CMAKE_DEBUG_TRACE=1
|
||||
|
||||
This enables verbose debug output of the command packets while this library executes.
|
||||
|
||||
|
||||
Install the AQLprofile libraries
|
||||
================================
|
||||
|
||||
Once your build is successful, install the AQLprofile libraries with:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd build
|
||||
sudo make install
|
||||
@@ -0,0 +1,29 @@
|
||||
.. meta::
|
||||
:description: The standard MIT license for AQLprofile
|
||||
:keywords: AQLprofile, ROCm, license
|
||||
|
||||
*******
|
||||
License
|
||||
*******
|
||||
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2017-2025 Advanced Micro Devices, Inc.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in
|
||||
all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
||||
THE SOFTWARE.
|
||||
@@ -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 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
|
||||
+-------------+------+--------+--------+--------+------+------+-----+
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
defaults:
|
||||
numbered: False
|
||||
maxdepth: 6
|
||||
root: index
|
||||
subtrees:
|
||||
|
||||
- entries:
|
||||
- file: what-is-aqlprofile.rst
|
||||
|
||||
- caption: Install
|
||||
entries:
|
||||
- file: install/aqlprofile-install.rst
|
||||
title: Install AQLprofile
|
||||
|
||||
- caption: Examples
|
||||
entries:
|
||||
- file: examples/pmc-workflow.rst
|
||||
title: Performance Monitor Control workflow
|
||||
- file: examples/sqtt-workflow.rst
|
||||
title: SQ Thread Trace workflow
|
||||
|
||||
- caption: Reference
|
||||
entries:
|
||||
- file: reference/glossary.rst
|
||||
title: Glossary
|
||||
- file: reference/supported-architectures.rst
|
||||
title: Supported architectures and counter blocks
|
||||
- file: reference/api-list.rst
|
||||
title: APIs
|
||||
|
||||
- caption: About
|
||||
entries:
|
||||
- file: license.rst
|
||||
title: License
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
defaults:
|
||||
numbered: False
|
||||
maxdepth: 6
|
||||
root: index
|
||||
subtrees:
|
||||
|
||||
- entries:
|
||||
- file: what-is-aqlprofile.rst
|
||||
|
||||
- caption: Install
|
||||
entries:
|
||||
- file: install/aqlprofile-install.rst
|
||||
title: Install AQLprofile
|
||||
|
||||
- caption: Examples
|
||||
entries:
|
||||
- file: examples/pmc-workflow.rst
|
||||
title: Performance Monitor Control workflow
|
||||
- file: examples/sqtt-workflow.rst
|
||||
title: SQ Thread Trace workflow
|
||||
|
||||
- caption: Reference
|
||||
entries:
|
||||
- file: reference/glossary.rst
|
||||
title: Glossary
|
||||
- file: reference/supported-architectures.rst
|
||||
title: Supported architectures and counter blocks
|
||||
- file: reference/api-list.rst
|
||||
title: APIs
|
||||
|
||||
- caption: About
|
||||
entries:
|
||||
- file: license.rst
|
||||
title: License
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
rocm-docs-core[api_reference]==1.23.0
|
||||
@@ -0,0 +1,314 @@
|
||||
#
|
||||
# This file is autogenerated by pip-compile with Python 3.10
|
||||
# by the following command:
|
||||
#
|
||||
# pip-compile requirements.in
|
||||
#
|
||||
accessible-pygments==0.0.5
|
||||
# via pydata-sphinx-theme
|
||||
alabaster==1.0.0
|
||||
# via sphinx
|
||||
asttokens==3.0.0
|
||||
# via stack-data
|
||||
attrs==25.3.0
|
||||
# via
|
||||
# jsonschema
|
||||
# jupyter-cache
|
||||
# referencing
|
||||
babel==2.17.0
|
||||
# via
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
beautifulsoup4==4.13.5
|
||||
# via pydata-sphinx-theme
|
||||
breathe==4.36.0
|
||||
# via rocm-docs-core
|
||||
certifi==2025.8.3
|
||||
# via requests
|
||||
cffi==2.0.0
|
||||
# via
|
||||
# cryptography
|
||||
# pynacl
|
||||
charset-normalizer==3.4.3
|
||||
# via requests
|
||||
click==8.2.1
|
||||
# via
|
||||
# click-log
|
||||
# doxysphinx
|
||||
# jupyter-cache
|
||||
# sphinx-external-toc
|
||||
click-log==0.4.0
|
||||
# via doxysphinx
|
||||
comm==0.2.3
|
||||
# via ipykernel
|
||||
contourpy==1.3.2
|
||||
# via matplotlib
|
||||
cryptography==45.0.7
|
||||
# via pyjwt
|
||||
cycler==0.12.1
|
||||
# via matplotlib
|
||||
debugpy==1.8.16
|
||||
# via ipykernel
|
||||
decorator==5.2.1
|
||||
# via ipython
|
||||
docutils==0.21.2
|
||||
# via
|
||||
# myst-parser
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
doxysphinx==3.3.12
|
||||
# via rocm-docs-core
|
||||
exceptiongroup==1.3.0
|
||||
# via ipython
|
||||
executing==2.2.1
|
||||
# via stack-data
|
||||
fastjsonschema==2.21.2
|
||||
# via
|
||||
# nbformat
|
||||
# rocm-docs-core
|
||||
fonttools==4.59.2
|
||||
# via matplotlib
|
||||
gitdb==4.0.12
|
||||
# via gitpython
|
||||
gitpython==3.1.45
|
||||
# via rocm-docs-core
|
||||
greenlet==3.2.4
|
||||
# via sqlalchemy
|
||||
idna==3.10
|
||||
# via requests
|
||||
imagesize==1.4.1
|
||||
# via sphinx
|
||||
importlib-metadata==8.7.0
|
||||
# via
|
||||
# jupyter-cache
|
||||
# myst-nb
|
||||
ipykernel==6.30.1
|
||||
# via myst-nb
|
||||
ipython==8.37.0
|
||||
# via
|
||||
# ipykernel
|
||||
# myst-nb
|
||||
jedi==0.19.2
|
||||
# via ipython
|
||||
jinja2==3.1.6
|
||||
# via
|
||||
# myst-parser
|
||||
# sphinx
|
||||
jsonschema==4.25.1
|
||||
# via nbformat
|
||||
jsonschema-specifications==2025.9.1
|
||||
# via jsonschema
|
||||
jupyter-cache==1.0.1
|
||||
# via myst-nb
|
||||
jupyter-client==8.6.3
|
||||
# via
|
||||
# ipykernel
|
||||
# nbclient
|
||||
jupyter-core==5.8.1
|
||||
# via
|
||||
# ipykernel
|
||||
# jupyter-client
|
||||
# nbclient
|
||||
# nbformat
|
||||
kiwisolver==1.4.9
|
||||
# via matplotlib
|
||||
libsass==0.22.0
|
||||
# via doxysphinx
|
||||
lxml==5.2.1
|
||||
# via doxysphinx
|
||||
markdown-it-py==3.0.0
|
||||
# via
|
||||
# mdit-py-plugins
|
||||
# myst-parser
|
||||
markupsafe==3.0.2
|
||||
# via jinja2
|
||||
matplotlib==3.10.6
|
||||
# via doxysphinx
|
||||
matplotlib-inline==0.1.7
|
||||
# via
|
||||
# ipykernel
|
||||
# ipython
|
||||
mdit-py-plugins==0.5.0
|
||||
# via myst-parser
|
||||
mdurl==0.1.2
|
||||
# via markdown-it-py
|
||||
mpire==2.10.2
|
||||
# via doxysphinx
|
||||
myst-nb==1.3.0
|
||||
# via rocm-docs-core
|
||||
myst-parser==4.0.1
|
||||
# via myst-nb
|
||||
nbclient==0.10.2
|
||||
# via
|
||||
# jupyter-cache
|
||||
# myst-nb
|
||||
nbformat==5.10.4
|
||||
# via
|
||||
# jupyter-cache
|
||||
# myst-nb
|
||||
# nbclient
|
||||
nest-asyncio==1.6.0
|
||||
# via ipykernel
|
||||
numpy==1.26.4
|
||||
# via
|
||||
# contourpy
|
||||
# doxysphinx
|
||||
# matplotlib
|
||||
packaging==25.0
|
||||
# via
|
||||
# ipykernel
|
||||
# matplotlib
|
||||
# sphinx
|
||||
parso==0.8.5
|
||||
# via jedi
|
||||
pexpect==4.9.0
|
||||
# via ipython
|
||||
pillow==11.3.0
|
||||
# via matplotlib
|
||||
platformdirs==4.4.0
|
||||
# via jupyter-core
|
||||
prompt-toolkit==3.0.52
|
||||
# via ipython
|
||||
psutil==7.0.0
|
||||
# via ipykernel
|
||||
ptyprocess==0.7.0
|
||||
# via pexpect
|
||||
pure-eval==0.2.3
|
||||
# via stack-data
|
||||
pycparser==2.23
|
||||
# via cffi
|
||||
pydata-sphinx-theme==0.16.1
|
||||
# via
|
||||
# rocm-docs-core
|
||||
# sphinx-book-theme
|
||||
pygithub==2.8.1
|
||||
# via rocm-docs-core
|
||||
pygments==2.19.2
|
||||
# via
|
||||
# accessible-pygments
|
||||
# ipython
|
||||
# mpire
|
||||
# pydata-sphinx-theme
|
||||
# sphinx
|
||||
pyjson5==1.6.9
|
||||
# via doxysphinx
|
||||
pyjwt[crypto]==2.10.1
|
||||
# via pygithub
|
||||
pynacl==1.6.0
|
||||
# via pygithub
|
||||
pyparsing==3.2.3
|
||||
# via
|
||||
# doxysphinx
|
||||
# matplotlib
|
||||
python-dateutil==2.9.0.post0
|
||||
# via
|
||||
# jupyter-client
|
||||
# matplotlib
|
||||
pyyaml==6.0.2
|
||||
# via
|
||||
# jupyter-cache
|
||||
# myst-nb
|
||||
# myst-parser
|
||||
# rocm-docs-core
|
||||
# sphinx-external-toc
|
||||
pyzmq==27.1.0
|
||||
# via
|
||||
# ipykernel
|
||||
# jupyter-client
|
||||
referencing==0.36.2
|
||||
# via
|
||||
# jsonschema
|
||||
# jsonschema-specifications
|
||||
requests==2.32.5
|
||||
# via
|
||||
# pygithub
|
||||
# sphinx
|
||||
rocm-docs-core[api-reference]==1.23.0
|
||||
# via -r requirements.in
|
||||
rpds-py==0.27.1
|
||||
# via
|
||||
# jsonschema
|
||||
# referencing
|
||||
six==1.17.0
|
||||
# via python-dateutil
|
||||
smmap==5.0.2
|
||||
# via gitdb
|
||||
snowballstemmer==3.0.1
|
||||
# via sphinx
|
||||
soupsieve==2.8
|
||||
# via beautifulsoup4
|
||||
sphinx==8.1.3
|
||||
# via
|
||||
# breathe
|
||||
# myst-nb
|
||||
# myst-parser
|
||||
# pydata-sphinx-theme
|
||||
# rocm-docs-core
|
||||
# sphinx-book-theme
|
||||
# sphinx-copybutton
|
||||
# sphinx-design
|
||||
# sphinx-external-toc
|
||||
# sphinx-notfound-page
|
||||
sphinx-book-theme==1.1.3
|
||||
# via rocm-docs-core
|
||||
sphinx-copybutton==0.5.2
|
||||
# via rocm-docs-core
|
||||
sphinx-design==0.6.1
|
||||
# via rocm-docs-core
|
||||
sphinx-external-toc==1.0.1
|
||||
# via rocm-docs-core
|
||||
sphinx-notfound-page==1.1.0
|
||||
# via rocm-docs-core
|
||||
sphinxcontrib-applehelp==2.0.0
|
||||
# via sphinx
|
||||
sphinxcontrib-devhelp==2.0.0
|
||||
# via sphinx
|
||||
sphinxcontrib-htmlhelp==2.1.0
|
||||
# via sphinx
|
||||
sphinxcontrib-jsmath==1.0.1
|
||||
# via sphinx
|
||||
sphinxcontrib-qthelp==2.0.0
|
||||
# via sphinx
|
||||
sphinxcontrib-serializinghtml==2.0.0
|
||||
# via sphinx
|
||||
sqlalchemy==2.0.43
|
||||
# via jupyter-cache
|
||||
stack-data==0.6.3
|
||||
# via ipython
|
||||
tabulate==0.9.0
|
||||
# via jupyter-cache
|
||||
tomli==2.2.1
|
||||
# via sphinx
|
||||
tornado==6.5.2
|
||||
# via
|
||||
# ipykernel
|
||||
# jupyter-client
|
||||
tqdm==4.67.1
|
||||
# via mpire
|
||||
traitlets==5.14.3
|
||||
# via
|
||||
# ipykernel
|
||||
# ipython
|
||||
# jupyter-client
|
||||
# jupyter-core
|
||||
# matplotlib-inline
|
||||
# nbclient
|
||||
# nbformat
|
||||
typing-extensions==4.15.0
|
||||
# via
|
||||
# beautifulsoup4
|
||||
# exceptiongroup
|
||||
# ipython
|
||||
# myst-nb
|
||||
# pydata-sphinx-theme
|
||||
# pygithub
|
||||
# referencing
|
||||
# sqlalchemy
|
||||
urllib3==2.5.0
|
||||
# via
|
||||
# pygithub
|
||||
# requests
|
||||
wcwidth==0.2.13
|
||||
# via prompt-toolkit
|
||||
zipp==3.23.0
|
||||
# via importlib-metadata
|
||||
@@ -0,0 +1,60 @@
|
||||
.. meta::
|
||||
:description: AQLprofile is an open source library that enables advanced GPU profiling and tracing on AMD platforms.
|
||||
:keywords: AQLprofile, ROCm, tool, Instinct, accelerator, AMD
|
||||
|
||||
What is AQLprofile?
|
||||
===================
|
||||
|
||||
The Architected Queuing Language profiling library (AQLprofile) is an
|
||||
open source library that enables advanced GPU profiling and tracing on
|
||||
AMD platforms. It works in conjunction with
|
||||
`ROCprofiler-SDK <https://github.com/ROCm/rocprofiler-sdk>`__ to
|
||||
support profiling methods such as `performance counters
|
||||
(PMC) <https://rocm.docs.amd.com/projects/aqlprofile/en/latest/examples/pmc-workflow.html>`__ and `SQ thread trace
|
||||
(SQTT) <https://rocm.docs.amd.com/projects/aqlprofile/en/latest/examples/sqtt-workflow.html>`__. AQLprofile provides the
|
||||
foundational mechanisms for constructing AQL packets and managing
|
||||
profiling operations across multiple AMD GPU architecture families. The
|
||||
development of AQLprofile is aligned with ROCprofiler-SDK, ensuring
|
||||
compatibility and feature support for new GPU architectures and
|
||||
profiling requirements.
|
||||
|
||||
AQLprofile builds on concepts from the Heterogeneous System Architecture
|
||||
(HSA) and the AQL, which define the foundations for GPU command
|
||||
processing and profiling on AMD platforms. For more information, see:
|
||||
|
||||
- `HSA Platform System Architecture
|
||||
Specification <http://hsafoundation.com/wp-content/uploads/2021/02/HSA-SysArch-1.2.pdf>`__
|
||||
- `HSA Runtime Programmer's Reference
|
||||
Specification <http://hsafoundation.com/wp-content/uploads/2021/02/HSA-Runtime-1.2.pdf>`__
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
- Profiling AQL packets for GPU workloads.
|
||||
- Performance counters and SQ thread traces.
|
||||
- Support for GFX9, GFX10XX, GFX11XX, and GFX12XX architecture families.
|
||||
- Verbose tracing and error logging capabilities.
|
||||
- Thread trace binary data generated by AQLprofile can be decoded using
|
||||
`rocprof-trace-decoder <https://github.com/ROCm/rocprof-trace-decoder/releases>`__.
|
||||
|
||||
Who should use this library?
|
||||
----------------------------
|
||||
|
||||
- **End users**: If you want to profile AMD GPUs, use
|
||||
`ROCprofiler-SDK <https://github.com/ROCm/rocprofiler-sdk>`__ or
|
||||
tools that depend on it. You do *not* need to use AQLprofile
|
||||
directly.
|
||||
- **Developers/integrators**: If you're building profiling tools,
|
||||
custom workflows, or need to extend profiling capabilities, you may
|
||||
use AQLprofile directly as a backend.
|
||||
|
||||
How does AQLprofile fit into the ROCm profiling stack?
|
||||
------------------------------------------------------
|
||||
|
||||
Here's the typical workflow:
|
||||
|
||||
Application → ROCprofiler-SDK ⇄ **AQLprofile** ⇄ ROCprofiler-SDK → HSA/ROCR/KFD → AMD GPU hardware
|
||||
|
||||
- **AQLprofile** generates profiling command packets (AQL/PM4) tailored to the GPU architecture. It doesn't interact with hardware or drivers directly. It only produces the packets and buffer requirements requested by ``ROCprofiler-SDK``.
|
||||
|
||||
- **ROCprofiler-SDK** provides a higher-level API and user-facing tools, using AQLprofile internally. It manages profiling sessions, submits packets to the GPU via `ROCr <https://rocm.docs.amd.com/projects/rocr_debug_agent/en/latest/index.html>`_/HSA/KFD, and collects results.
|
||||
新しいイシューから参照
ユーザーをブロックする