diff --git a/source/include/rocprofiler-sdk/buffer_tracing.h b/source/include/rocprofiler-sdk/buffer_tracing.h index 800463953d..ccaaf3f9ce 100644 --- a/source/include/rocprofiler-sdk/buffer_tracing.h +++ b/source/include/rocprofiler-sdk/buffer_tracing.h @@ -37,184 +37,122 @@ ROCPROFILER_EXTERN_C_INIT /** * @brief ROCProfiler Buffer HSA API Tracer Record. - * TODO(aelwazir): Add comments against every variable */ typedef struct { - uint64_t size; - rocprofiler_buffer_tracing_kind_t kind; - rocprofiler_correlation_id_t correlation_id; - rocprofiler_tracing_operation_t operation; // rocprofiler/hsa.h - rocprofiler_timestamp_t start_timestamp; - rocprofiler_timestamp_t end_timestamp; - rocprofiler_thread_id_t thread_id; + uint64_t size; ///< size of this struct + rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_CALLBACK_TRACING_HSA_API + rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record + rocprofiler_tracing_operation_t operation; ///< ::rocprofiler_hsa_api_id_t + rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds + rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds + rocprofiler_thread_id_t thread_id; ///< id for thread generating this record } rocprofiler_buffer_tracing_hsa_api_record_t; /** * @brief ROCProfiler Buffer HIP API Tracer Record. - * TODO(aelwazir): Add comments against every variable */ typedef struct { - uint64_t size; - rocprofiler_buffer_tracing_kind_t kind; - rocprofiler_correlation_id_t correlation_id; - rocprofiler_tracing_operation_t operation; // rocprofiler/hip.h - rocprofiler_timestamp_t start_timestamp; - rocprofiler_timestamp_t end_timestamp; - rocprofiler_thread_id_t thread_id; + uint64_t size; ///< size of this struct + rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_CALLBACK_TRACING_HIP_API + rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record + rocprofiler_tracing_operation_t operation; ///< ::rocprofiler_hip_api_id_t + rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds + rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds + rocprofiler_thread_id_t thread_id; ///< id for thread generating this record } rocprofiler_buffer_tracing_hip_api_record_t; /** * @brief ROCProfiler Buffer Marker Tracer Record. - * TODO(aelwazir): Add comments against every variable */ typedef struct { - uint64_t size; - rocprofiler_buffer_tracing_kind_t kind; - rocprofiler_correlation_id_t correlation_id; - rocprofiler_tracing_operation_t operation; // rocprofiler/marker.h - rocprofiler_timestamp_t timestamp; - rocprofiler_thread_id_t thread_id; - uint64_t marker_id; // rocprofiler_marker_id_t + uint64_t size; ///< size of this struct + rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_CALLBACK_TRACING_MARKER_API + rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record + rocprofiler_tracing_operation_t operation; ///< ::rocprofiler_marker_api_id_t + rocprofiler_timestamp_t timestamp; ///< time in nanoseconds + rocprofiler_thread_id_t thread_id; ///< id for thread generating this record + uint64_t marker_id; // rocprofiler_marker_id_t // const char* message; // (Need Review?) } rocprofiler_buffer_tracing_marker_record_t; /** * @brief ROCProfiler Buffer Memory Copy Tracer Record. - * TODO(aelwazir): Add comments against every variable */ typedef struct { - uint64_t size; - rocprofiler_buffer_tracing_kind_t kind; - rocprofiler_correlation_id_t correlation_id; - rocprofiler_timestamp_t start_timestamp; - rocprofiler_timestamp_t end_timestamp; - rocprofiler_agent_id_t agent_id; - rocprofiler_queue_id_t queue_id; - rocprofiler_kernel_id_t kernel_id; + uint64_t size; ///< size of this struct + rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_BUFFER_TRACING_MEMORY_COPY + rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record + rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds + rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds + rocprofiler_agent_id_t agent_id; ///< agent identifier + rocprofiler_queue_id_t queue_id; ///< queue identifier + rocprofiler_kernel_id_t kernel_id; ///< kernel identifier } rocprofiler_buffer_tracing_memory_copy_record_t; /** * @brief ROCProfiler Buffer Kernel Dispatch Tracer Record. - * TODO(aelwazir): Add comments against every variable */ typedef struct { - uint64_t size; - rocprofiler_buffer_tracing_kind_t kind; - rocprofiler_correlation_id_t correlation_id; - rocprofiler_timestamp_t start_timestamp; - rocprofiler_timestamp_t end_timestamp; - rocprofiler_agent_id_t agent_id; - rocprofiler_queue_id_t queue_id; - rocprofiler_kernel_id_t kernel_id; - uint32_t private_segment_size; - uint32_t group_segment_size; - rocprofiler_dim3_t workgroup_size; - rocprofiler_dim3_t grid_size; + uint64_t size; ///< size of this struct + rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_BUFFER_TRACING_KERNEL_DISPATCH + rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record + rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds + rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds + rocprofiler_agent_id_t agent_id; ///< agent kernel was dispatched on + rocprofiler_queue_id_t queue_id; ///< queue kernel was dispatched on + rocprofiler_kernel_id_t kernel_id; ///< identifier for kernel + uint32_t private_segment_size; /// runtime private memory segment size + uint32_t group_segment_size; /// runtime group memory segment size + rocprofiler_dim3_t workgroup_size; /// runtime workgroup size (grid * threads) + rocprofiler_dim3_t grid_size; /// runtime grid size } rocprofiler_buffer_tracing_kernel_dispatch_record_t; /** - * @brief ROCProfiler Buffer Page Migration Tracer Record. - * TODO(aelwazir): Add comments against every variable + * @brief ROCProfiler Buffer Page Migration Tracer Record. Not implemented. */ typedef struct { - uint64_t size; - rocprofiler_buffer_tracing_kind_t kind; - rocprofiler_correlation_id_t correlation_id; - rocprofiler_timestamp_t start_timestamp; - rocprofiler_timestamp_t end_timestamp; - rocprofiler_queue_id_t queue_id; + uint64_t size; ///< size of this struct + rocprofiler_buffer_tracing_kind_t kind; ///< ROCPROFILER_BUFFER_TRACING_PAGE_MIGRATION + rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record + rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds + rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds // Not Sure What is the info needed here? } rocprofiler_buffer_tracing_page_migration_record_t; /** - * @brief ROCProfiler Buffer Scratch Memory Tracer Record. - * TODO(aelwazir): Add comments against every variable + * @brief ROCProfiler Buffer Scratch Memory Tracer Record. Not implemented. */ typedef struct { - uint64_t size; - rocprofiler_buffer_tracing_kind_t kind; - rocprofiler_correlation_id_t correlation_id; - rocprofiler_timestamp_t start_timestamp; - rocprofiler_timestamp_t end_timestamp; - rocprofiler_queue_id_t queue_id; + uint64_t size; ///< size of this struct + rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_BUFFER_TRACING_SCRATCH_MEMORY + rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record + rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds + rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds // Not Sure What is the info needed here? } rocprofiler_buffer_tracing_scratch_memory_record_t; /** - * @brief ROCProfiler Buffer Queue Scheduling Tracer Record. - * TODO(aelwazir): Add comments against every variable + * @brief ROCProfiler Buffer Queue Scheduling Tracer Record. Not implemented. */ typedef struct { - uint64_t size; - rocprofiler_buffer_tracing_kind_t kind; - rocprofiler_correlation_id_t correlation_id; - rocprofiler_timestamp_t start_timestamp; - rocprofiler_timestamp_t end_timestamp; - rocprofiler_queue_id_t queue_id; + uint64_t size; ///< size of this struct + rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_BUFFER_TRACING_SCRATCH_MEMORY + rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record + rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds + rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds // Not Sure What is the info needed here? } rocprofiler_buffer_tracing_queue_scheduling_record_t; -// TODO(aelwazir): Review with Jonathan if Code Object is in the buffer tracing /** - * @brief ROCProfiler Code Object Tracer Buffer Record. - * - * We need to guarantee that these records are in the buffer before the - * corresponding Exit Phase API calls are called. - */ -// typedef struct { -// rocprofiler_buffer_tracing_record_header_t header; -// rocprofiler_tracing_code_object_kind_id_t kind; -// } rocprofiler_buffer_tracing_code_object_header_t; - -/** - * @brief ROCProfiler Code Object Load Tracer Buffer Record. - * - */ -// typedef struct { -// rocprofiler_buffer_tracing_code_object_header_t header; -// uint64_t load_base; // code object load base -// uint64_t load_size; // code object load size -// const char *uri; // URI string (NULL terminated) -// rocprofiler_timestamp_t timestamp; -// // uint32_t storage_type; // code object storage type (Need Review?) -// // int storage_file; // origin file descriptor (Need Review?) -// // uint64_t memory_base; // origin memory base (Need Review?) -// // uint64_t memory_size; // origin memory size (Need Review?) -// // uint64_t load_delta; // code object load delta (Need Review?) -// } rocprofiler_buffer_tracing_code_object_load_record_t; - -/** - * @brief ROCProfiler Code Object UnLoad Tracer Buffer Record. - * - */ -// typedef struct { -// rocprofiler_buffer_tracing_code_object_header_t header; -// uint64_t load_base; // code object load base -// rocprofiler_timestamp_t timestamp; -// } rocprofiler_buffer_tracing_code_object_unload_record_t; - -/** - * @brief ROCProfiler Code Object Kernel Symbol Tracer Buffer Record. - * - */ -// typedef struct { -// rocprofiler_buffer_tracing_code_object_header_t header; -// const char *kernel_name; // kernel name string (NULL terminated) -// uint64_t kernel_descriptor; // kernel descriptor (Need to be changed from -// // uint64_t to ::rocprofiler_address_t) -// // rocprofiler_timestamp_t timestamp; // (Need Review?) -// } rocprofiler_buffer_tracing_code_object_kernel_symbol_record_t; - -/** - * @brief ROCProfiler Buffer External Correlation Tracer Record. + * @brief ROCProfiler Buffer External Correlation Tracer Record. Not implemented. */ typedef struct { @@ -243,20 +181,28 @@ typedef int (*rocprofiler_buffer_tracing_kind_operation_cb_t)( /** * @brief Configure Buffer Tracing Service. * - * @param [in] context_id - * @param [in] kind - * @param [in] operations - * @param [in] operations_count - * @param [in] buffer_id + * @param [in] context_id Associated context to control activation of service + * @param [in] kind Buffer tracing category + * @param [in] operations Array of specific operations (if desired) + * @param [in] operations_count Number of specific operations (if non-null set of operations) + * @param [in] buffer_id Buffer to store the records in * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED ::rocprofiler_configure initialization + * phase has passed + * @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND context is not valid + * @retval ::ROCPROFILER_STATUS_ERROR_SERVICE_ALREADY_CONFIGURED Context has already been configured + * for the ::rocprofiler_buffer_tracing_kind_t kind + * @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Invalid ::rocprofiler_buffer_tracing_kind_t + * @retval ::ROCPROFILER_STATUS_ERROR_OPERATION_NOT_FOUND Invalid operation id for + * ::rocprofiler_buffer_tracing_kind_t kind was found * */ -rocprofiler_status_t ROCPROFILER_API +rocprofiler_status_t rocprofiler_configure_buffer_tracing_service(rocprofiler_context_id_t context_id, rocprofiler_buffer_tracing_kind_t kind, rocprofiler_tracing_operation_t* operations, size_t operations_count, - rocprofiler_buffer_id_t buffer_id); + rocprofiler_buffer_id_t buffer_id) ROCPROFILER_API; /** * @brief Query the name of the buffer tracing kind. The name retrieved from this function is a @@ -307,20 +253,19 @@ rocprofiler_query_buffer_tracing_kind_operation_name(rocprofiler_buffer_tracing_ uint64_t* name_len) ROCPROFILER_API; /** - * @brief Iterate over all the mappings of the buffer tracing kinds and get a buffer with the id - * mapped to a constant string. The strings provided in the arg will be valid pointers for the - * entire duration of the program. It is recommended to call this function once and cache this data - * in the client instead of making multiple on-demand calls. + * @brief Iterate over all the buffer tracing kinds and invokes the callback for each buffer tracing + * kind. * - * TODO(aelwazir): to be modified + * This is typically used to invoke ::rocprofiler_iterate_buffer_tracing_kind_operations for each + * buffer tracing kind. * * @param [in] callback Callback function invoked for each enumeration value in @ref * rocprofiler_buffer_tracing_kind_t with the exception of the `NONE` and `LAST` values. * @param [in] data User data passed back into the callback */ -rocprofiler_status_t ROCPROFILER_API -rocprofiler_iterate_buffer_tracing_kinds(rocprofiler_buffer_tracing_kind_cb_t callback, void* data) - ROCPROFILER_NONNULL(1); +rocprofiler_status_t +rocprofiler_iterate_buffer_tracing_kinds(rocprofiler_buffer_tracing_kind_cb_t callback, + void* data) ROCPROFILER_API ROCPROFILER_NONNULL(1); /** * @brief Iterates over all the operations for a given @ref @@ -333,11 +278,11 @@ rocprofiler_iterate_buffer_tracing_kinds(rocprofiler_buffer_tracing_kind_cb_t ca * rocprofiler_buffer_tracing_kind_t with the exception of the `NONE` and `LAST` values. * @param [in] data User data passed back into the callback */ -rocprofiler_status_t ROCPROFILER_API +rocprofiler_status_t rocprofiler_iterate_buffer_tracing_kind_operations( rocprofiler_buffer_tracing_kind_t kind, rocprofiler_buffer_tracing_kind_operation_cb_t callback, - void* data) ROCPROFILER_NONNULL(2); + void* data) ROCPROFILER_API ROCPROFILER_NONNULL(2); /** @} */ diff --git a/source/include/rocprofiler-sdk/fwd.h b/source/include/rocprofiler-sdk/fwd.h index 27b6d2478b..7d66c1c0b5 100644 --- a/source/include/rocprofiler-sdk/fwd.h +++ b/source/include/rocprofiler-sdk/fwd.h @@ -121,7 +121,7 @@ typedef enum // NOLINT(performance-enum-size) } rocprofiler_callback_phase_t; /** - * @brief Service Callback Tracing Kind. + * @brief Service Callback Tracing Kind. @see rocprofiler_configure_callback_tracing_service. */ typedef enum // NOLINT(performance-enum-size) { @@ -135,7 +135,7 @@ typedef enum // NOLINT(performance-enum-size) } rocprofiler_callback_tracing_kind_t; /** - * @brief Service Buffer Tracing Kind. + * @brief Service Buffer Tracing Kind. @see rocprofiler_configure_buffer_tracing_service. */ typedef enum // NOLINT(performance-enum-size) { @@ -158,10 +158,9 @@ typedef enum // NOLINT(performance-enum-size) */ typedef enum // NOLINT(performance-enum-size) { - ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT_NONE = 0, - ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT_LOAD, - ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT_DEVICE_KERNEL_SYMBOL_REGISTER, - // next two are part of hipRegisterFunction API. + ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT_NONE = 0, ///< Unknown code object operation + ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT_LOAD, ///< Code object containing kernel symbols + ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT_DEVICE_KERNEL_SYMBOL_REGISTER, ///< Kernel symbols // ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT_HOST_KERNEL_SYMBOL_REGISTER, ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT_LAST, } rocprofiler_callback_tracing_code_object_operation_t; @@ -171,10 +170,10 @@ typedef enum // NOLINT(performance-enum-size) */ typedef enum // NOLINT(performance-enum-size) { - ROCPROFILER_BUFFER_TRACING_MEMORY_COPY_NONE = 0, - ROCPROFILER_BUFFER_TRACING_MEMORY_COPY_DEVICE_TO_HOST, - ROCPROFILER_BUFFER_TRACING_MEMORY_COPY_HOST_TO_DEVICE, - ROCPROFILER_BUFFER_TRACING_MEMORY_COPY_DEVICE_TO_DEVICE, + ROCPROFILER_BUFFER_TRACING_MEMORY_COPY_NONE = 0, ///< Unknown memory copy direction + ROCPROFILER_BUFFER_TRACING_MEMORY_COPY_DEVICE_TO_HOST, ///< Memory copy from device to host + ROCPROFILER_BUFFER_TRACING_MEMORY_COPY_HOST_TO_DEVICE, ///< Memory copy from host to device + ROCPROFILER_BUFFER_TRACING_MEMORY_COPY_DEVICE_TO_DEVICE, ///< Memory copy from device to device ROCPROFILER_BUFFER_TRACING_MEMORY_COPY_LAST, } rocprofiler_buffer_tracing_memory_copy_operation_t; @@ -183,9 +182,9 @@ typedef enum // NOLINT(performance-enum-size) */ typedef enum // NOLINT(performance-enum-size) { - ROCPROFILER_PC_SAMPLING_METHOD_NONE = 0, - ROCPROFILER_PC_SAMPLING_METHOD_STOCHASTIC, - ROCPROFILER_PC_SAMPLING_METHOD_HOST_TRAP, + ROCPROFILER_PC_SAMPLING_METHOD_NONE = 0, ///< Unknown sampling type + ROCPROFILER_PC_SAMPLING_METHOD_STOCHASTIC, ///< Stochastic sampling (MI300+) + ROCPROFILER_PC_SAMPLING_METHOD_HOST_TRAP, ///< Interval sampling (MI200+) ROCPROFILER_PC_SAMPLING_METHOD_LAST, } rocprofiler_pc_sampling_method_t; diff --git a/source/include/rocprofiler-sdk/marker/api_id.h b/source/include/rocprofiler-sdk/marker/api_id.h index 37bbd2f76b..dddd3b8cb4 100644 --- a/source/include/rocprofiler-sdk/marker/api_id.h +++ b/source/include/rocprofiler-sdk/marker/api_id.h @@ -33,5 +33,11 @@ typedef enum // NOLINT(performance-enum-size) ROCPROFILER_MARKER_API_ID_roctxRangePop, ROCPROFILER_MARKER_API_ID_roctxRangeStartA, ROCPROFILER_MARKER_API_ID_roctxRangeStop, + ROCPROFILER_MARKER_API_ID_roctxProfilerPause, + ROCPROFILER_MARKER_API_ID_roctxProfilerResume, + ROCPROFILER_MARKER_API_ID_roctxNameOsThread, + ROCPROFILER_MARKER_API_ID_roctxNameHsaDevice, + ROCPROFILER_MARKER_API_ID_roctxNameHipDevice, + ROCPROFILER_MARKER_API_ID_roctxNameHipStream, ROCPROFILER_MARKER_API_ID_LAST, } rocprofiler_marker_api_id_t; diff --git a/source/include/rocprofiler-sdk/pc_sampling.h b/source/include/rocprofiler-sdk/pc_sampling.h index 1d3492c964..ece76a792e 100644 --- a/source/include/rocprofiler-sdk/pc_sampling.h +++ b/source/include/rocprofiler-sdk/pc_sampling.h @@ -36,7 +36,7 @@ ROCPROFILER_EXTERN_C_INIT /** * @brief Function used to configure the PC sampling service on the GPU agent with @p agent_id. - * @brief Function used to configure the PC sampling service on the GPU agent with @p agent_id. + * * Prerequisites are the following: * - The user must create a context and supply its @p context_id. By using this context, * - The user must create a context and supply its @p context_id. By using this context, diff --git a/source/include/rocprofiler-sdk/registration.h b/source/include/rocprofiler-sdk/registration.h index be8890115d..48b11492a1 100644 --- a/source/include/rocprofiler-sdk/registration.h +++ b/source/include/rocprofiler-sdk/registration.h @@ -48,24 +48,51 @@ typedef struct const uint32_t handle; ///< internal handle } rocprofiler_client_id_t; -// TODO(aelwazir): Add Docs +/** + * @brief Prototype for the function pointer provided to tool in ::rocprofiler_tool_initialize_t. + * This function can be used to explicitly invoke the client tools ::rocprofiler_tool_finalize_t + * finalization function prior to the `atexit` handler which calls it. + * + * If this function pointer is invoked explicitly, rocprofiler will disable calling the + * ::rocprofiler_tool_finalize_t functioin pointer during it's `atexit` handler. + */ typedef void (*rocprofiler_client_finalize_t)(rocprofiler_client_id_t); -// TODO(aelwazir): Add Docs +/** + * @brief Prototype for the initialize function where a tool creates contexts for the set of + * rocprofiler services used by the tool. + * @param [in] finalize_func Function pointer to explicitly invoke the finalize function for the + * client + * @param [in] tool_data `tool_data` field returned from ::rocprofiler_configure in + * ::rocprofiler_tool_configure_result_t. + */ typedef int (*rocprofiler_tool_initialize_t)(rocprofiler_client_finalize_t finalize_func, void* tool_data); -// TODO(aelwazir): Add Docs +/** + * @brief Prototype for the finalize function where a tool does any cleanup or output operations + * once it has finished using rocprofiler services. + * @param [in] tool_data `tool_data` field returned from ::rocprofiler_configure in + * ::rocprofiler_tool_configure_result_t. + */ typedef void (*rocprofiler_tool_finalize_t)(void* tool_data); /** - * @brief Data structure containing a initialization, finalization, and data - * TODO(aelwazir): Add correlation with rocprofiler_configure. + * @brief Data structure containing a initialization, finalization, and data. * + * After rocprofiler has retrieved all instances of ::rocprofiler_tool_configure_result_t from the + tools -- via either ::rocprofiler_configure and/or ::rocprofiler_force_configure, + * rocprofiler will invoke all non-null `initialize` functions and provide the user a function + pointer which will explicitly invoke + * the `finalize` function pointer. Both the `initialize` and `finalize` functions will be passed + the value of the `tool_data` field. + * The `size` field is used for ABI reasons, in the event that rocprofiler changes the + ::rocprofiler_tool_configure_result_t struct + * and it should be set to `sizeof(rocprofiler_tool_configure_result_t)` */ typedef struct { - size_t size; ///< in case of future extensions + size_t size; ///< size of this struct (in case of future extensions) rocprofiler_tool_initialize_t initialize; ///< context creation rocprofiler_tool_finalize_t finalize; ///< cleanup void* tool_data; ///< data to provide to init and fini callbacks @@ -79,9 +106,10 @@ typedef struct * @param [out] status 0 indicates rocprofiler has not been initialized (i.e. configured), 1 * indicates rocprofiler has been initialized, -1 indicates rocprofiler is currently initializing. * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_SUCCESS Returned unconditionally */ rocprofiler_status_t -rocprofiler_is_initialized(int* status) ROCPROFILER_API; +rocprofiler_is_initialized(int* status) ROCPROFILER_API ROCPROFILER_NONNULL(1); /** * @brief Query rocprofiler finalization status. @@ -89,9 +117,10 @@ rocprofiler_is_initialized(int* status) ROCPROFILER_API; * @param [out] status 0 indicates rocprofiler has not been finalized, 1 indicates rocprofiler has * been finalized, -1 indicates rocprofiler is currently finalizing. * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_SUCCESS Returned unconditionally */ rocprofiler_status_t -rocprofiler_is_finalized(int* status) ROCPROFILER_API; +rocprofiler_is_finalized(int* status) ROCPROFILER_API ROCPROFILER_NONNULL(1); /** * @brief This is the special function that tools define to enable rocprofiler support. The tool @@ -213,8 +242,10 @@ typedef rocprofiler_tool_configure_result_t* (*rocprofiler_configure_func_t)( * initialize. * @param [in] configure_func Address of @ref rocprofiler_configure function. A null pointer is * acceptable if the address is not known - * @returns rocprofiler_status_t If rocprofiler has already been configured, or is currently being - * configured, this function will return @ref ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED. + * @return ::rocprofiler_status_t + * @retval ::ROCPROFILER_STATUS_SUCCESS Registration was successfully triggered. + * @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED Returned if rocprofiler has already been + * configured, or is currently being configured */ rocprofiler_status_t rocprofiler_force_configure(rocprofiler_configure_func_t configure_func) ROCPROFILER_API;