Tool registration#
Rocprofiler SDK Developer API 0.4.0
ROCm Profiling API and tools
|
Data Structures | |
struct | rocprofiler_client_id_t |
A client refers to an individual or entity engaged in the configuration of ROCprofiler services. e.g: any third party tool like PAPI or any internal tool (Omnitrace). A pointer to this data structure is provided to the client tool initialization function. The name member can be set by the client to assist with debugging (e.g. rocprofiler cannot start your context because there is a conflicting context started by <name> – at least that is the plan). The handle member is a unique identifer assigned by rocprofiler for the client and the client can store it and pass it to the rocprofiler_client_finalize_t function to force finalization (i.e. deactivate all of it's contexts) for the client. More... | |
struct | rocprofiler_tool_configure_result_t |
Data structure containing a initialization, finalization, and data. More... | |
Typedefs | |
typedef void(* | rocprofiler_client_finalize_t) (rocprofiler_client_id_t) |
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. | |
typedef int(* | rocprofiler_tool_initialize_t) (rocprofiler_client_finalize_t finalize_func, void *tool_data) |
Prototype for the initialize function where a tool creates contexts for the set of rocprofiler services used by the tool. | |
typedef void(* | rocprofiler_tool_finalize_t) (void *tool_data) |
Prototype for the finalize function where a tool does any cleanup or output operations once it has finished using rocprofiler services. | |
typedef rocprofiler_tool_configure_result_t *(* | rocprofiler_configure_func_t) (uint32_t version, const char *runtime_version, uint32_t priority, rocprofiler_client_id_t *client_id) |
Function pointer typedef for rocprofiler_configure function. | |
Functions | |
rocprofiler_status_t | rocprofiler_is_initialized (int *status) |
Query whether rocprofiler has already scanned the binary for all the instances of rocprofiler_configure (or is currently scanning). If rocprofiler has completed it's scan, clients can directly register themselves with rocprofiler. | |
rocprofiler_status_t | rocprofiler_is_finalized (int *status) |
Query rocprofiler finalization status. | |
rocprofiler_tool_configure_result_t * | rocprofiler_configure (uint32_t version, const char *runtime_version, uint32_t priority, rocprofiler_client_id_t *client_id) |
This is the special function that tools define to enable rocprofiler support. The tool should return a pointer to rocprofiler_tool_configure_result_t which will contain a function pointer to (1) an initialization function where all the contexts are created, (2) a finalization function (if necessary) which will be invoked when rocprofiler shutdown and, (3) a pointer to any data that the tool wants communicated between the rocprofiler_tool_configure_result_t::initialize and rocprofiler_tool_configure_result_t::finalize functions. If the user. | |
rocprofiler_status_t | rocprofiler_force_configure (rocprofiler_configure_func_t configure_func) |
Function for explicitly registering a configuration with rocprofiler. This can be invoked before any ROCm runtimes (lazily) initialize and context(s) can be started before the runtimes initialize. | |
Detailed Description
Data types and functions for tool registration with rocprofiler
Data Structure Documentation
◆ rocprofiler_client_id_t
struct rocprofiler_client_id_t |
A client refers to an individual or entity engaged in the configuration of ROCprofiler services. e.g: any third party tool like PAPI or any internal tool (Omnitrace). A pointer to this data structure is provided to the client tool initialization function. The name member can be set by the client to assist with debugging (e.g. rocprofiler cannot start your context because there is a conflicting context started by <name>
– at least that is the plan). The handle member is a unique identifer assigned by rocprofiler for the client and the client can store it and pass it to the rocprofiler_client_finalize_t function to force finalization (i.e. deactivate all of it's contexts) for the client.
- Examples
- api_buffered_tracing/client.cpp, intercept_table/client.cpp, and samples/api_callback_tracing/client.cpp.
Definition at line 47 of file registration.h.
Data Fields | ||
---|---|---|
const uint32_t | handle | internal handle |
const char * | name | clients should set this value for debugging |
◆ rocprofiler_tool_configure_result_t
struct rocprofiler_tool_configure_result_t |
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)
- Examples
- api_buffered_tracing/client.cpp, intercept_table/client.cpp, and samples/api_callback_tracing/client.cpp.
Definition at line 95 of file registration.h.
Data Fields | ||
---|---|---|
rocprofiler_tool_finalize_t | finalize | cleanup |
rocprofiler_tool_initialize_t | initialize | context creation |
unsigned long | size | size of this struct (in case of future extensions) |
void * | tool_data | data to provide to init and fini callbacks |
Typedef Documentation
◆ rocprofiler_client_finalize_t
typedef void(* rocprofiler_client_finalize_t) (rocprofiler_client_id_t) |
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.
Definition at line 61 of file registration.h.
◆ rocprofiler_configure_func_t
typedef rocprofiler_tool_configure_result_t *(* rocprofiler_configure_func_t) (uint32_t version, const char *runtime_version, uint32_t priority, rocprofiler_client_id_t *client_id) |
Function pointer typedef for rocprofiler_configure function.
- Parameters
-
[in] version The version of rocprofiler: (10000 * major) + (100 * minor) + patch
[in] runtime_version String descriptor of the rocprofiler version and other relevant info. [in] priority How many client tools were initialized before this client tool [in,out] client_id tool identifier value.
Definition at line 236 of file registration.h.
◆ rocprofiler_tool_finalize_t
typedef void(* rocprofiler_tool_finalize_t) (void *tool_data) |
Prototype for the finalize function where a tool does any cleanup or output operations once it has finished using rocprofiler services.
- Parameters
-
[in] tool_data tool_data
field returned from rocprofiler_configure in rocprofiler_tool_configure_result_t.
Definition at line 80 of file registration.h.
◆ rocprofiler_tool_initialize_t
typedef int(* rocprofiler_tool_initialize_t) (rocprofiler_client_finalize_t finalize_func, void *tool_data) |
Prototype for the initialize function where a tool creates contexts for the set of rocprofiler services used by the tool.
- Parameters
-
[in] finalize_func Function pointer to explicitly invoke the finalize function for the client [in] tool_data tool_data
field returned from rocprofiler_configure in rocprofiler_tool_configure_result_t.
Definition at line 71 of file registration.h.
Function Documentation
◆ rocprofiler_configure()
rocprofiler_tool_configure_result_t * rocprofiler_configure | ( | uint32_t | version, |
const char * | runtime_version, | ||
uint32_t | priority, | ||
rocprofiler_client_id_t * | client_id | ||
) |
This is the special function that tools define to enable rocprofiler support. The tool should return a pointer to rocprofiler_tool_configure_result_t which will contain a function pointer to (1) an initialization function where all the contexts are created, (2) a finalization function (if necessary) which will be invoked when rocprofiler shutdown and, (3) a pointer to any data that the tool wants communicated between the rocprofiler_tool_configure_result_t::initialize and rocprofiler_tool_configure_result_t::finalize functions. If the user.
- Parameters
-
[in] version The version of rocprofiler: (10000 * major) + (100 * minor) + patch
[in] runtime_version String descriptor of the rocprofiler version and other relevant info. [in] priority How many client tools were initialized before this client tool [in,out] client_id tool identifier value.
- Returns
- rocprofiler_tool_configure_result_t*
◆ rocprofiler_force_configure()
rocprofiler_status_t rocprofiler_force_configure | ( | rocprofiler_configure_func_t | configure_func | ) |
Function for explicitly registering a configuration with rocprofiler. This can be invoked before any ROCm runtimes (lazily) initialize and context(s) can be started before the runtimes initialize.
- Parameters
-
[in] configure_func Address of rocprofiler_configure function. A null pointer is acceptable if the address is not known
- Returns
- rocprofiler_status_t
- Return values
-
ROCPROFILER_STATUS_SUCCESS Registration was successfully triggered. ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED Returned if rocprofiler has already been configured, or is currently being configured
- Examples
- api_buffered_tracing/client.cpp.
◆ rocprofiler_is_finalized()
rocprofiler_status_t rocprofiler_is_finalized | ( | int * | status | ) |
Query rocprofiler finalization status.
- Parameters
-
[out] status 0 indicates rocprofiler has not been finalized, 1 indicates rocprofiler has been finalized, -1 indicates rocprofiler is currently finalizing.
- Returns
- rocprofiler_status_t
- Return values
-
ROCPROFILER_STATUS_SUCCESS Returned unconditionally
◆ rocprofiler_is_initialized()
rocprofiler_status_t rocprofiler_is_initialized | ( | int * | status | ) |
Query whether rocprofiler has already scanned the binary for all the instances of rocprofiler_configure (or is currently scanning). If rocprofiler has completed it's scan, clients can directly register themselves with rocprofiler.
- Parameters
-
[out] status 0 indicates rocprofiler has not been initialized (i.e. configured), 1 indicates rocprofiler has been initialized, -1 indicates rocprofiler is currently initializing.
- Returns
- rocprofiler_status_t
- Return values
-
ROCPROFILER_STATUS_SUCCESS Returned unconditionally
Generated by 1.9.8