Saurabh Verma
946385d0ff
Reverts #1379 and properly migrates the docs --------- Co-authored-by: Matt Williams <matt.williams@amd.com>
113 baris
12 KiB
ReStructuredText
113 baris
12 KiB
ReStructuredText
.. 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. |
|
|
+---------------------------------------------------+------------------------------------------------------------------------------------------------+
|