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,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
|
||||
);
|
||||
|
||||
|
||||
Reference in New Issue
Block a user