// MIT License // // Copyright (c) 2023-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 /** * @defgroup device_counting_service Agent Profile Counting Service * @brief needs brief description * * @{ */ ROCPROFILER_EXTERN_C_INIT /** * @brief Callback to set the profile config for the agent. * * @param [in] context_id context id * @param [in] config_id Profile config detailing the counters to collect for this kernel * @return ::rocprofiler_status_t * @retval ::ROCPROFILER_STATUS_ERROR_PROFILE_NOT_FOUND Returned if the config_id is not found * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_INVALID Returned if the ctx is not valid * @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED Returned if attempting to make this * call outside of context startup. * @retval ::ROCPROFILER_STATUS_ERROR_AGENT_MISMATCH Agent of profile does not match agent of the * context. * @retval ::ROCPROFILER_STATUS_SUCCESS Returned if succesfully configured */ typedef rocprofiler_status_t (*rocprofiler_agent_set_profile_callback_t)( rocprofiler_context_id_t context_id, rocprofiler_profile_config_id_t config_id); /** * @brief Configure Profile Counting Service for agent. Called when the context is started. * Selects the counters to be used for agent profiling. * * @param [in] context_id context id * @param [in] agent_id agent id * @param [in] set_config Function to call to set the profile config (see * rocprofiler_agent_set_profile_callback_t) * @param [in] user_data Data supplied to rocprofiler_configure_device_counting_service */ typedef void (*rocprofiler_device_counting_service_callback_t)( rocprofiler_context_id_t context_id, rocprofiler_agent_id_t agent_id, rocprofiler_agent_set_profile_callback_t set_config, void* user_data); /** * @brief Configure Device Counting Service for agent. There may only be one counting service * configured per agent in a context and can be only one active context that is profiling a single * agent at a time. Multiple agent contexts can be started at the same time if they are profiling * different agents. * * @param [in] context_id context id * @param [in] buffer_id id of the buffer to use for the counting service. When * rocprofiler_sample_device_counting_service is called, counter data will be written * to this buffer. If the input buffer id is null (i.e. `rocprofiler_buffer_id_t{.handle = 0}`), the * counter data will not be written to a buffer and will only be returned in the output_records of * rocprofiler_sample_device_counting_service * @param [in] agent_id agent to configure profiling on. * @param [in] cb Callback called when the context is started for the tool to specify what * counters to collect (rocprofiler_profile_config_id_t). * @param [in] user_data User supplied data to be passed to the callback cb when triggered * @return ::rocprofiler_status_t * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_INVALID Returned if the context does not exist. * @retval ::ROCPROFILER_STATUS_ERROR_BUFFER_NOT_FOUND Returned if the buffer is not found. * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Returned if context already has agent * profiling configured for agent_id. * @retval ::ROCPROFILER_STATUS_SUCCESS Returned if succesfully configured */ rocprofiler_status_t rocprofiler_configure_device_counting_service(rocprofiler_context_id_t context_id, rocprofiler_buffer_id_t buffer_id, rocprofiler_agent_id_t agent_id, rocprofiler_device_counting_service_callback_t cb, void* user_data) ROCPROFILER_NONNULL(4) ROCPROFILER_API; /** * @brief Trigger a read of the counter data for the agent profile. The counter data will be * written to the buffer specified in rocprofiler_configure_device_counting_service. * The data in rocprofiler_user_data_t will be written to the buffer along with the counter data. * flags can be used to specify if this call should be performed asynchronously (default is * synchronous). * * @param [in] context_id context id * @param [in] user_data User supplied data, included in records outputted to buffer. * @param [in] flags Flags to specify how the counter data should be collected (defaults to sync). * @param [in] output_records Output records collected via sampling (output is also written to * buffer). Must be allocated by caller. * @param [in] rec_count On entry, this is the maximum number of records rocprof can store in * output_records. On exit, contains the number of actual records. * @return ::rocprofiler_status_t * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_INVALID Returned if the context does not exist or * the context is not configured for agent profiling. * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_ERROR Returned if another operation is in progress ( * start/stop ctx or another read). * @retval ::ROCPROFILER_STATUS_ERROR Returned if HSA has not been initialized yet. * @retval ::ROCPROFILER_STATUS_ERROR_OUT_OF_RESOURCES Returned output_records is set but size is * too small to store results * @retval ::ROCPROFILER_STATUS_SUCCESS Returned if read request was successful. * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Returned If ASYNC is being used while * output_records is not null. */ rocprofiler_status_t rocprofiler_sample_device_counting_service(rocprofiler_context_id_t context_id, rocprofiler_user_data_t user_data, rocprofiler_counter_flag_t flags, rocprofiler_record_counter_t* output_records, size_t* rec_count) ROCPROFILER_API; /** @} */ ROCPROFILER_EXTERN_C_FINI