// MIT License // // Copyright (c) 2023 ROCm Developer Tools // // 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 #include #include #include #include ROCPROFILER_EXTERN_C_INIT /** * @defgroup CALLBACK_TRACING_SERVICE Synchronous Tracing Services * @brief Receive immediate callbacks on the calling thread * * @{ */ /** * @brief ROCProfiler Enumeration for code object storage types (identical values to * `hsa_ven_amd_loader_code_object_storage_type_t` enumeration) */ typedef enum { ROCPROFILER_CODE_OBJECT_STORAGE_TYPE_NONE = HSA_VEN_AMD_LOADER_CODE_OBJECT_STORAGE_TYPE_NONE, ROCPROFILER_CODE_OBJECT_STORAGE_TYPE_FILE = HSA_VEN_AMD_LOADER_CODE_OBJECT_STORAGE_TYPE_FILE, ROCPROFILER_CODE_OBJECT_STORAGE_TYPE_MEMORY = HSA_VEN_AMD_LOADER_CODE_OBJECT_STORAGE_TYPE_MEMORY, ROCPROFILER_CODE_OBJECT_STORAGE_TYPE_LAST, } rocprofiler_code_object_storage_type_t; /** * @brief ROCProfiler HSA API Callback Data. */ typedef struct { uint64_t size; ///< size of this struct rocprofiler_hsa_api_args_t args; rocprofiler_hsa_api_retval_t retval; } rocprofiler_callback_tracing_hsa_api_data_t; /** * @brief ROCProfiler HIP API Tracer Callback Data. */ typedef struct { uint64_t size; ///< size of this struct rocprofiler_hip_api_args_t args; rocprofiler_hip_api_retval_t retval; } rocprofiler_callback_tracing_hip_api_data_t; /** * @brief ROCProfiler Marker Tracer Callback Data. */ typedef struct { uint64_t size; ///< size of this struct rocprofiler_marker_api_args_t args; rocprofiler_marker_api_retval_t retval; } rocprofiler_callback_tracing_marker_api_data_t; /** * @brief ROCProfiler Code Object Load Tracer Callback Record. */ typedef struct { uint64_t size; ///< size of this struct uint64_t code_object_id; ///< unique code object identifier rocprofiler_agent_id_t rocp_agent; ///< The agent on which this loaded code object is loaded hsa_agent_t hsa_agent; ///< The agent on which this loaded code object is loaded const char* uri; ///< The URI name from which the code object was loaded uint64_t load_base; ///< The base memory address at which the code object is loaded. This is ///< the base address of the allocation for the lowest addressed segment of ///< the code object that is loaded. Note that any non-loaded segments ///< before the first loaded segment are ignored. uint64_t load_size; ///< The byte size of the loaded code objects contiguous memory allocation. uint64_t load_delta; ///< The signed byte address difference of the memory address at which the ///< code object is loaded minus the virtual address specified in the code ///< object that is loaded. rocprofiler_code_object_storage_type_t storage_type; ///< storage type of the code object reader used to load the loaded code ///< object union { struct { int storage_file; ///< file descriptor of the code object that was loaded. Access this ///< field if @ref rocprofiler_code_object_storage_type_t is ///< @ref ROCPROFILER_CODE_OBJECT_STORAGE_TYPE_FILE }; struct { uint64_t memory_base; ///< The memory address of the first byte of the code object that ///< was loaded. Access this ///< field if @ref rocprofiler_code_object_storage_type_t is ///< @ref ROCPROFILER_CODE_OBJECT_STORAGE_TYPE_MEMORY uint64_t memory_size; ///< The memory size in bytes of the code object that was loaded. ///< Access this field if @ref ///< rocprofiler_code_object_storage_type_t is ///< @ref ROCPROFILER_CODE_OBJECT_STORAGE_TYPE_MEMORY }; }; } rocprofiler_callback_tracing_code_object_load_data_t; /** * @brief ROCProfiler Code Object Kernel Symbol Tracer Callback Record. * */ typedef struct { uint64_t size; ///< size of this struct uint64_t kernel_id; ///< unique symbol identifier value uint64_t code_object_id; ///< parent unique code object identifier rocprofiler_agent_id_t rocp_agent; ///< Agent associated with this symbol const char* kernel_name; ///< name of the kernel uint64_t kernel_object; ///< kernel object handle, used in the kernel dispatch packet uint32_t kernarg_segment_size; ///< size of memory (in bytes) allocated for kernel arguments. ///< Will be multiple of 16 uint32_t kernarg_segment_alignment; ///< Alignment (in bytes) of the buffer used to pass ///< arguments to the kernel uint32_t group_segment_size; ///< Size of static group segment memory required by the kernel ///< (per work-group), in bytes uint32_t private_segment_size; ///< Size of static private, spill, and arg segment memory ///< required by this kernel (per work-item), in bytes. } rocprofiler_callback_tracing_code_object_kernel_symbol_register_data_t; /** * @brief API Tracing callback function. This function is invoked twice per API function: once * before the function is invoked and once after the function is invoked. The external correlation * id value within the record is assigned the value at the top of the external correlation id stack. * It is permissible to invoke @ref rocprofiler_push_external_correlation_id within the enter phase; * when a new external correlation id is pushed during the enter phase, rocprofiler will use that * external correlation id for any async events and provide the new external correlation id during * the exit callback... In other words, pushing a new external correlation id within the enter * callback will result in that external correlation id value in the exit callback (which may or may * not be different from the external correlation id value in the enter callback). If a tool pushes * new external correlation ids in the enter phase, it is recommended to pop the external * correlation id in the exit callback. * * @param [in] record Callback record data * @param [in,out] user_data This paramter can be used to retain information in between the enter * and exit phases. * @param [in] callback_data User data provided when configuring the callback tracing service */ typedef void (*rocprofiler_callback_tracing_cb_t)(rocprofiler_callback_tracing_record_t record, rocprofiler_user_data_t* user_data, void* callback_data) ROCPROFILER_NONNULL(2); /** * @brief Callback function for mapping @ref rocprofiler_service_callback_tracing_kind_t ids to * string names. @see rocprofiler_iterate_callback_tracing_kind_names. */ typedef int (*rocprofiler_callback_tracing_kind_cb_t)( rocprofiler_service_callback_tracing_kind_t kind, void* data); /** * @brief Callback function for mapping the operations of a given @ref * rocprofiler_service_callback_tracing_kind_t to string names. @see * rocprofiler_iterate_callback_tracing_kind_operation_names. */ typedef int (*rocprofiler_callback_tracing_kind_operation_cb_t)( rocprofiler_service_callback_tracing_kind_t kind, uint32_t operation, void* data); /** * @brief Callback function for iterating over the function arguments to a traced function. * This function will be invoked for each argument. * @see rocprofiler_iterate_callback_tracing_operation_args * * @param [in] kind domain * @param [in] operation associated domain operation * @param [in] arg_number the argument number, starting at zero * @param [in] arg_name the name of the argument in the prototype (or rocprofiler union) * @param [in] arg_value_str conversion of the argument to a string, e.g. operator<< overload * @param [in] arg_value_addr the address of the argument stored by rocprofiler. * @param [in] data user data */ typedef int (*rocprofiler_callback_tracing_operation_args_cb_t)( rocprofiler_service_callback_tracing_kind_t kind, uint32_t operation, uint32_t arg_number, const char* arg_name, const char* arg_value_str, const void* const arg_value_addr, void* data); /** * @brief Configure Callback Tracing Service. The callback tracing service provides two synchronous * callbacks around an API function on the same thread as the application which is invoking the API * function. This function can only be invoked once per @ref * rocprofiler_service_callback_tracing_kind_t value, i.e. it can be invoked once for the HSA API, * once for the HIP API, and so on but it will fail if it is invoked for the HSA API twice. Please * note, the callback API does have the potentially non-trivial overhead of copying the function * arguments into the record. If you are willing to let rocprofiler record the timestamps, do not * require synchronous notifications of the API calls, and want to lowest possible overhead, use the * @see BUFFER_TRACING_SERVICE. * * @param [in] context_id Context to associate the service with * @param [in] kind The domain of the callback tracing service * @param [in] operations Array of operations in the domain (i.e. enum values which identify * specific API functions). If this is null, all API functions in the domain will be traced * @param [in] operations_count If the operations array is non-null, set this to the size of the * array. * @param [in] callback The function to invoke before and after an API function * @param [in] callback_args Data provided to every invocation of the callback function * @return ::rocprofiler_status_t * @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED Invoked outside of the initialization * function in @ref rocprofiler_tool_configure_result_t provided to rocprofiler via @ref * rocprofiler_configure function * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND The provided context is not valid/registered * @retval ::ROCPROFILER_STATUS_ERROR_SERVICE_ALREADY_CONFIGURED if the same @ref * rocprofiler_service_callback_tracing_kind_t value is provided more than once (per context) -- in * other words, we do not support overriding or combining the operations in separate function calls. * */ rocprofiler_status_t ROCPROFILER_API rocprofiler_configure_callback_tracing_service(rocprofiler_context_id_t context_id, rocprofiler_service_callback_tracing_kind_t kind, rocprofiler_tracing_operation_t* operations, size_t operations_count, rocprofiler_callback_tracing_cb_t callback, void* callback_args); /** * @brief Query the name of the callback tracing kind. The name retrieved from this function is a * string literal that is encoded in the read-only section of the binary (i.e. it is always * "allocated" and never "deallocated"). * * @param [in] kind Callback tracing domain * @param [out] name If non-null and the name is a constant string that does not require dynamic * allocation, this paramter will be set to the address of the string literal, otherwise it will * be set to nullptr * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of * the name is a constant string or requires dynamic allocation) * @return ::rocprofiler_status_t */ rocprofiler_status_t rocprofiler_query_callback_tracing_kind_name(rocprofiler_service_callback_tracing_kind_t kind, const char** name, uint64_t* name_len) ROCPROFILER_API; /** * @brief Query the name of the callback tracing kind. The name retrieved from this function is a * string literal that is encoded in the read-only section of the binary (i.e. it is always * "allocated" and never "deallocated"). * * @param [in] kind Callback tracing domain * @param [in] operation Enumeration id value which maps to a specific API function or event type * @param [out] name If non-null and the name is a constant string that does not require dynamic * allocation, this paramter will be set to the address of the string literal, otherwise it will * be set to nullptr * @param [out] name_len If non-null, this will be assigned the length of the name (regardless of * the name is a constant string or requires dynamic allocation) * @return ::rocprofiler_status_t * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Domain id is not valid * @retval ::ROCPROFILER_STATUS_SUCCESS Valid domain provided, regardless if there is a constant * string or not. */ rocprofiler_status_t rocprofiler_query_callback_tracing_kind_operation_name( rocprofiler_service_callback_tracing_kind_t kind, uint32_t operation, const char** name, uint64_t* name_len) ROCPROFILER_API; /** * @brief Iterate over all the mappings of the callback tracing kinds and get a callback for each * kind. * * @param [in] callback Callback function invoked for each enumeration value in @ref * rocprofiler_service_callback_tracing_kind_t with the exception of the `NONE` and `LAST` values. * @param [in] data User data passed back into the callback * @return ::rocprofiler_status_t */ rocprofiler_status_t ROCPROFILER_API rocprofiler_iterate_callback_tracing_kinds(rocprofiler_callback_tracing_kind_cb_t callback, void* data) ROCPROFILER_NONNULL(1); /** * @brief Iterates over all the mappings of the operations for a given @ref * rocprofiler_service_callback_tracing_kind_t and invokes the callback with the kind id, operation * id, and user-provided data. * * @param [in] kind which tracing callback kind operations to iterate over * @param [in] callback Callback function invoked for each operation associated with @ref * rocprofiler_service_callback_tracing_kind_t with the exception of the `NONE` and `LAST` values. * @param [in] data User data passed back into the callback * @return ::rocprofiler_status_t * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Invalid domain id * @retval ::ROCPROFILER_STATUS_SUCCESS Valid domain */ rocprofiler_status_t ROCPROFILER_API rocprofiler_iterate_callback_tracing_kind_operations( rocprofiler_service_callback_tracing_kind_t kind, rocprofiler_callback_tracing_kind_operation_cb_t callback, void* data) ROCPROFILER_NONNULL(2); /** * @brief Iterates over all the arguments for the traced function (when available). This is * particularly useful when tools want to annotate traces with the function arguments. See * @example samples/api_callback_tracing/client.cpp for a usage example. * * @param[in] record Record provided by service callback * @param[in] callback The callback function which will be invoked for each argument * @param[in] user_data Data to be passed to each invocation of the callback */ rocprofiler_status_t ROCPROFILER_API rocprofiler_iterate_callback_tracing_kind_operation_args( rocprofiler_callback_tracing_record_t record, rocprofiler_callback_tracing_operation_args_cb_t callback, void* user_data) ROCPROFILER_NONNULL(2); /** @} */ ROCPROFILER_EXTERN_C_FINI