Reverts #1379 and properly migrates the docs --------- Co-authored-by: Matt Williams <matt.williams@amd.com>
Tento commit je obsažen v:
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. |
|
||||
+---------------------------------------------------+------------------------------------------------------------------------------------------------+
|
||||
Odkázat v novém úkolu
Zablokovat Uživatele