// MIT License // // Copyright (c) 2024-2025 Advanced Micro Devices, Inc. All rights reserved. // // 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. #pragma once #include #include #ifdef __cplusplus extern "C" { #endif typedef struct { uint64_t handle; } aqlprofile_handle_t; typedef enum { AQLPROFILE_MEMORY_HINT_NONE = 0, AQLPROFILE_MEMORY_HINT_HOST = 1, AQLPROFILE_MEMORY_HINT_DEVICE_UNCACHED = 2, AQLPROFILE_MEMORY_HINT_DEVICE_COHERENT = 3, AQLPROFILE_MEMORY_HINT_DEVICE_NONCOHERENT = 4, AQLPROFILE_MEMORY_HINT_LAST } aqlprofile_memory_hint_t; /** * @brief Flags to describe which agents can access given buffer. */ typedef union { uint32_t raw; struct { uint32_t device_access : 1; uint32_t host_access : 1; uint32_t memory_hint : 6; // One of aqlprofile_memory_hint_t uint32_t _reserved : 24; }; } aqlprofile_buffer_desc_flags_t; /** * @brief Callback to request a memory buffer, which will be tied to a profile. * The user is responsible for clearing up memory after the profile is no longer needed. * @param[out] ptr The pointer containing memory. * @param[in] size Minimum requested buffer size. * @param[in] flags Access flags, requesting which agents need to read/write to the buffer. * @param[in] userdata Data to be passed back to user. * @retval HSA_STATUS_SUCCESS if successful * @retval HSA_STATUS_ERROR if memory could not be allocated */ typedef hsa_status_t (*aqlprofile_memory_alloc_callback_t)(void** ptr, uint64_t size, aqlprofile_buffer_desc_flags_t flags, void* userdata); /** * @brief Callback to dealloc memory requested via aqlprofile_memory_alloc_callback_t * @param[in] ptr The pointer containing memory. * @param[in] userdata Data to be passed back to user. * @retval HSA_STATUS_SUCCESS if successful * @retval HSA_STATUS_ERROR if memory could not be allocated */ typedef void (*aqlprofile_memory_dealloc_callback_t)(void* ptr, void* userdata); typedef enum { AQLPROFILE_ACCUMULATION_NONE = 0, /** Do not accumulate event */ AQLPROFILE_ACCUMULATION_LO_RES, /**< The event should be integrated over quad-cycles */ AQLPROFILE_ACCUMULATION_HI_RES, /**< The event should be integrated every cycle */ AQLPROFILE_ACCUMULATION_LAST, } aqlprofile_accumulation_type_t; /** * @brief Special flags indicating additional properties to a counter. E.g. Accumulation metrics */ typedef union { uint32_t raw; struct { uint32_t accum : 3; /**< One of aqlprofile_accumulation_type_t */ uint32_t _reserved : 29; } sq_flags; } aqlprofile_pmc_event_flags_t; /** * @brief Struct containing all necessary information of an event (counter). */ typedef struct { uint32_t block_index; /**< Block channel. */ uint32_t event_id; /**< Event ID as fined by XML */ aqlprofile_pmc_event_flags_t flags; /**< Special event flags e.g. accumulation */ hsa_ven_amd_aqlprofile_block_name_t block_name; /**< Block name as defined by block indexes */ } aqlprofile_pmc_event_t; /** * @brief Struct containing information about the agent. User code sets these values * to the describe the agent to profile. Information can be obtained either from HSA * (if loaded) or the KFD topology. */ typedef struct { const char* agent_gfxip; /**< Agent GFXIP (HSA_AGENT_INFO_NAME or KFD.product_name) */ uint32_t xcc_num; /**< XCC's on the agent (HSA_AMD_AGENT_INFO_NUM_XCC or KFD.num_xcc) */ uint32_t se_num; /**< SE's on the agent (HSA_AMD_AGENT_INFO_NUM_SHADER_ENGINES or KFD.num_shader_banks) */ uint32_t cu_num; /**< CU's on the agent (HSA_AMD_AGENT_INFO_COMPUTE_UNIT_COUNT or KFD.cu_count) */ uint32_t shader_arrays_per_se; /**< Shader arrays per SE of agent (HSA_AMD_AGENT_INFO_NUM_SHADER_ARRAYS_PER_SE or KFD.simd_arrays_per_engine)*/ } aqlprofile_agent_info_t; /** * @brief Struct containing a handle to a registered agent * */ typedef struct { uint64_t handle; } aqlprofile_agent_handle_t; /** * @brief Registers an agent to be used with AQL profile. * @param[out] agent_id Handle to newly registered agent * @param[in] agent_info Info to register a new agent with AQL Profiler * @retval HSA_STATUS_SUCCESS registration ok * @retval HSA_STATUS_ERROR registration failed */ hsa_status_t aqlprofile_register_agent(aqlprofile_agent_handle_t* agent_id, const aqlprofile_agent_info_t* agent_info); /** * @brief AQLprofile struct containing information for perfmon events */ typedef struct { aqlprofile_agent_handle_t agent; const aqlprofile_pmc_event_t* events; uint32_t event_count; } aqlprofile_pmc_profile_t; // Profile attributes typedef enum { AQLPROFILE_INFO_COMMAND_BUFFER_SIZE = 0, // get_info returns uint32_t value AQLPROFILE_INFO_PMC_DATA_SIZE = 1, // get_info returns uint32_t value AQLPROFILE_INFO_PMC_DATA = 2, // get_info returns PMC uint64_t value // in info_data object AQLPROFILE_INFO_BLOCK_COUNTERS = 4, // get_info returns number of block counter AQLPROFILE_INFO_BLOCK_ID = 5, // get_info returns block id, instances // by name string using _id_query_t AQLPROFILE_INFO_ENABLE_CMD = 6, // get_info returns size/pointer for // counters enable command buffer AQLPROFILE_INFO_DISABLE_CMD = 7, // get_info returns size/pointer for // counters disable command buffer } aqlprofile_pmc_info_type_t; hsa_status_t aqlprofile_get_pmc_info(const aqlprofile_pmc_profile_t* profile, aqlprofile_pmc_info_type_t attribute, void* value); // Profile parameter object typedef struct { hsa_ven_amd_aqlprofile_parameter_name_t parameter_name; union { uint32_t value; struct { uint32_t counter_id : 28; uint32_t simd_mask : 4; }; }; } aqlprofile_att_parameter_t; /** * @brief AQLprofile struct containing information for Advanced Thread Trace */ typedef struct { hsa_agent_t agent; const aqlprofile_att_parameter_t* parameters; uint32_t parameter_count; } aqlprofile_att_profile_t; /** * @brief Data callback for perfmon events. Each event will call this once per coordinate * @param[in] event The event information passed in from aqlprofile_pmc_profile_t * @param[in] counter_id Internal ID of the counter * @param[in] counter_value The event value, as incremented from start() to stop() * @param[in] userdata Data returned to user * @retval HSA_STATUS_SUCCESS to continue iteration * @retval HSA_STATUS_ERROR to stop callback iteration */ typedef hsa_status_t (*aqlprofile_pmc_data_callback_t)(aqlprofile_pmc_event_t event, uint64_t counter_id, uint64_t counter_value, void* userdata); /** * @brief Data callback for thread trace. This will be called at least once per shader engine * @param[in] shader Shader Engine ID * @param[in] buffer Pointer containing the data * @param[in] size Amount of bytes used by thread trace * @param[in] callback_data Data returned to user * @retval HSA_STATUS_SUCCESS to continue iteration * @retval HSA_STATUS_ERROR to stop callback iteration */ typedef hsa_status_t (*aqlprofile_att_data_callback_t)(uint32_t shader, void* buffer, uint64_t size, void* callback_data); /** * @brief Memory copy fn for aqlprofile to copy data. * @param[in] dst Destination pointer to copy data to. * @param[in] src Source pointer where data is to be copied from. * @param[in] size Amount of bytes to be copied. * @param[in] userdata Data returned to user * @retval HSA_STATUS_SUCCESS on success * @retval HSA_STATUS_ERROR on failure */ typedef hsa_status_t (*aqlprofile_memory_copy_t)(void* dst, const void* src, size_t size, void* userdata); /** * @brief Validates the event for the agent. * @param[in] agent The agent to validate the event for. * @param[in] event The event to validate. * @param[out] result True if the event is valid for the agent, false otherwise. * @retval HSA_STATUS_SUCCESS if the event was validated. * @retval HSA_STATUS_ERROR if the event was not validated. */ hsa_status_t aqlprofile_validate_pmc_event(aqlprofile_agent_handle_t agent, const aqlprofile_pmc_event_t* event, bool* result); /** * @brief Iterate_data() will parse the event data and call @callback with the resulting event data * @param[in] handle The handle returned from aqlprofile_pmc_create_packets() * @param[in] callback CB where the resulting event values are going to be returned * @param[in] userdata Data sent back to user * @retval HSA_STATUS_SUCCESS all operations exited succesfully * @retval HSA_STATUS_ERROR if some callback returns an error * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT if invalid handle is given */ hsa_status_t aqlprofile_pmc_iterate_data(aqlprofile_handle_t handle, aqlprofile_pmc_data_callback_t callback, void* userdata); /** * @brief Struct to be returned by aqlprofile_pmc_create_packets */ typedef struct { hsa_ext_amd_aql_pm4_packet_t start_packet; /**< Reset counters and start incrementing */ hsa_ext_amd_aql_pm4_packet_t stop_packet; /**< Pause counters from incrementing */ hsa_ext_amd_aql_pm4_packet_t read_packet; /**< Retrieve results from device */ } aqlprofile_pmc_aql_packets_t; /** * @brief Function to create AQL packets to be inserted into the queue. * @param[out] handle To be passed to iterate_data() * @param[out] packets Pointer to where the start, stop and read packets will be written to * @param[in] profile Agent and events information * @param[in] alloc_cb Memory allocation, which may request cpu or gpu memory for internal use * @param[in] dealloc_cb Function to free memory allocated by alloc_cb * @param[in] userdata Data passed back to user via memory alloc callback */ hsa_status_t aqlprofile_pmc_create_packets(aqlprofile_handle_t* handle, aqlprofile_pmc_aql_packets_t* packets, aqlprofile_pmc_profile_t profile, aqlprofile_memory_alloc_callback_t alloc_cb, aqlprofile_memory_dealloc_callback_t dealloc_cb, aqlprofile_memory_copy_t memcpy_cb, void* userdata); /** * @brief Function to delete AQL packets after creation by aqlprofile_pmc_create_packets * @param[in] handle Returned by aqlprofile_pmc_create_packets() */ void aqlprofile_pmc_delete_packets(aqlprofile_handle_t handle); /** * @brief Iterates over thread trace data and the data to user * @param[in] handle The handle returned from aqlprofile_att_create_packets() * @param[in] callback CB where the resulting data is going to be returned * @param[in] userdata Data sent back to user * @retval HSA_STATUS_SUCCESS all operations exited succesfully * @retval HSA_STATUS_ERROR if some callback returns an error * @retval HSA_STATUS_ERROR_INVALID_ARGUMENT if invalid handle is given */ hsa_status_t aqlprofile_att_iterate_data(aqlprofile_handle_t handle, aqlprofile_att_data_callback_t callback, void* userdata); /** * @brief Struct containing AQLpackets to start and stop thread trace */ typedef struct { hsa_ext_amd_aql_pm4_packet_t start_packet; /**< Packet to start thread trace */ hsa_ext_amd_aql_pm4_packet_t stop_packet; /**< Packet to stop thread trace and flush data */ } aqlprofile_att_control_aql_packets_t; /** * @brief Fn to create start and stop thread trace packets * @param[out] handle To be passed to iterate_data() * @param[out] packets Packets returned by this function to start and stop thread trace * @param[in] profile Agent information and extra parameters for thread trace * @param[in] callback Memory allocation fn which may request cpu or gpu memory * @retval HSA_STATUS_SUCCESS if all packets created succesfully * @retval HSA_STATUS_ERROR otherwise */ hsa_status_t aqlprofile_att_create_packets(aqlprofile_handle_t* handle, aqlprofile_att_control_aql_packets_t* packets, aqlprofile_att_profile_t profile, aqlprofile_memory_alloc_callback_t alloc_cb, aqlprofile_memory_dealloc_callback_t dealloc_cb, aqlprofile_memory_copy_t memcpy_cb, void* userdata); void aqlprofile_att_delete_packets(aqlprofile_handle_t handle); /** * @brief Callback for iteration of all possible event coordinate IDs and coordinate names. * @param [in] id Integer identifying the dimension. * @param [in] name Name of the dimension * @param [in] data User data supplied to @ref aqlprofile_iterate_event_ids * @retval HSA_STATUS_SUCCESS Continues iteration * @retval OTHERS Any other HSA return values stops iteration, passing back this value through * @ref aqlprofile_iterate_event_ids */ typedef hsa_status_t (*aqlprofile_eventname_callback_t)(int id, const char* name, void* data); /** * @brief Iterate over all possible event coordinate IDs and their names. * @param [in] callback Callback to use for iteration of dimensions * @param [in] user_data Data to supply to callback @ref aqlprofile_eventname_callback_t * @retval HSA_STATUS_SUCCESS if successful * @retval HSA_STATUS_ERROR if error on interation * @retval OTHERS If @ref aqlprofile_eventname_callback_t returns non-HSA_STATUS_SUCCESS, * that value is returned. */ hsa_status_t aqlprofile_iterate_event_ids(aqlprofile_eventname_callback_t callback, void* user_data); /** * @brief Iterate over all event coordinates for a given agent_t and event_t. * @param position A counting sequence indicating callback number. * @param id Coordinate ID as in _iterate_event_ids. * @param extent Coordinate extent indicating maximum allowed instances. * @param coordinate The coordinate, in the range [0,extent-1]. * @param name Coordinate name as in _iterate_event_ids. * @param userdata Userdata returned from _iterate_event_coord function. */ typedef hsa_status_t (*aqlprofile_coordinate_callback_t)(int position, int id, int extent, int coordinate, const char* name, void* userdata); /** * @brief Iterate over all event coordinates for a given agent_t and event_t. * @param[in] agent HSA agent. * @param[in] event The event ID and block ID to iterate for. * @param[in] sample_id aqlprofile_info_data_t.sample_id returned from _aqlprofile_iterate_data. * @param[in] callback Callback function to return the coordinates. * @param[in] userdata Arbitrary data pointer to be sent back to the user via callback. */ hsa_status_t aqlprofile_iterate_event_coord(aqlprofile_agent_handle_t agent, aqlprofile_pmc_event_t event, uint64_t sample_id, aqlprofile_coordinate_callback_t callback, void* userdata); typedef struct { uint64_t id; uint64_t addr; uint64_t size; hsa_agent_t agent; uint32_t isUnload : 1; uint32_t fromStart : 1; } aqlprofile_att_codeobj_data_t; /** * @brief Creates an AQL packet for marking code objects * @param[out] packet Returned packet * @param[out] handle The handle created from aqlprofile_att_create_packets() * @param[in] data Code object information * @param[in] alloc_cb Callback to return both CPU and GPU accessible memory on demand * @param[in] dealloc_cb Callback to free data allocated by alloc_cb() * @param[in] userdata Userdata to be passed back to memory callbacks */ hsa_status_t aqlprofile_att_codeobj_marker(hsa_ext_amd_aql_pm4_packet_t* packet, aqlprofile_handle_t* handle, aqlprofile_att_codeobj_data_t data, aqlprofile_memory_alloc_callback_t alloc_cb, aqlprofile_memory_dealloc_callback_t dealloc_cb, void* userdata); #ifdef __cplusplus } #endif