Tool registration

Tool registration#

Rocprofiler SDK Developer API: Tool registration
Rocprofiler SDK Developer API 0.4.0
ROCm Profiling API and tools
Tool registration

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_trocprofiler_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.

+ Collaboration diagram for rocprofiler_client_id_t:
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.

+ Collaboration diagram for rocprofiler_tool_configure_result_t:
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.

Examples
api_buffered_tracing/client.cpp, and samples/api_callback_tracing/client.cpp.

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]versionThe version of rocprofiler: (10000 * major) + (100 * minor) + patch
[in]runtime_versionString descriptor of the rocprofiler version and other relevant info.
[in]priorityHow many client tools were initialized before this client tool
[in,out]client_idtool 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_datatool_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_funcFunction pointer to explicitly invoke the finalize function for the client
[in]tool_datatool_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]versionThe version of rocprofiler: (10000 * major) + (100 * minor) + patch
[in]runtime_versionString descriptor of the rocprofiler version and other relevant info.
[in]priorityHow many client tools were initialized before this client tool
[in,out]client_idtool identifier value.
Returns
rocprofiler_tool_configure_result_t*
static rocprofiler_client_id_t my_client_id;
static rocprofiler_client_finalize_t my_fini_func;
static int my_tool_data = 1234;
static int my_init_func(rocprofiler_client_finalize_t fini_func,
void* tool_data)
{
my_fini_func = fini_func;
assert(*static_cast<int*>(tool_data) == 1234 && "tool_data is wrong");
if(int valid_ctx = 0;
valid_ctx != 0)
{
// notify rocprofiler that initialization failed
// and all the contexts, buffers, etc. created
// should be ignored
return -1;
}
{
// notify rocprofiler that initialization failed
// and all the contexts, buffers, etc. created
// should be ignored
return -1;
}
// no errors
return 0;
}
static int my_fini_func(void* tool_data)
{
assert(*static_cast<int*>(tool_data) == 1234 && "tool_data is wrong");
}
rocprofiler_configure(uint32_t version,
const char* runtime_version,
uint32_t priority,
{
// only activate if main tool
if(priority > 0) return nullptr;
// set the client name
client_id->name = "ExampleTool";
// make a copy of client info
my_client_id = *client_id;
// compute major/minor/patch version info
uint32_t major = version / 10000;
uint32_t minor = (version % 10000) / 100;
uint32_t patch = version % 100;
// print info
printf("Configuring %s with rocprofiler-sdk (v%u.%u.%u) [%s]\n",
client_id->name, major, minor, patch, runtime_version);
// create configure data
static auto cfg = rocprofiler_tool_configure_result_t{ &my_init_func,
&my_fini_func,
&my_tool_data };
// return pointer to configure data
return &cfg;
}
@ ROCPROFILER_STATUS_SUCCESS
No error occurred.
Definition fwd.h:56
Context ID.
Definition fwd.h:502
rocprofiler_status_t rocprofiler_start_context(rocprofiler_context_id_t context_id)
Start context.
rocprofiler_status_t rocprofiler_create_context(rocprofiler_context_id_t *context_id)
Create context.
rocprofiler_status_t rocprofiler_context_is_valid(rocprofiler_context_id_t context_id, int *status)
Query whether the context is valid.
const char * name
clients should set this value for debugging
void(* rocprofiler_client_finalize_t)(rocprofiler_client_id_t)
Prototype for the function pointer provided to tool in rocprofiler_tool_initialize_t....
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 client refers to an individual or entity engaged in the configuration of ROCprofiler services....
Data structure containing a initialization, finalization, and data.
Examples
api_buffered_tracing/client.cpp, intercept_table/client.cpp, and samples/api_callback_tracing/client.cpp.

◆ 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_funcAddress of rocprofiler_configure function. A null pointer is acceptable if the address is not known
Returns
rocprofiler_status_t
Return values
ROCPROFILER_STATUS_SUCCESSRegistration was successfully triggered.
ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKEDReturned 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]status0 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_SUCCESSReturned 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]status0 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_SUCCESSReturned unconditionally
Examples
api_buffered_tracing/client.cpp, and samples/api_callback_tracing/client.cpp.