Tool registration

Tool registration#

Rocprofiler SDK Developer API: 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.

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]	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*

#include <rocprofiler-sdk/registration.h>
 
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");
 
     rocprofiler_context_id_t ctx;
     rocprofiler_create_context(&ctx);
 
     if(int valid_ctx = 0;
        rocprofiler_context_is_valid(ctx, &valid_ctx) != ROCPROFILER_STATUS_SUCCESS ||
        valid_ctx != 0)
     {
         // notify rocprofiler that initialization failed
         // and all the contexts, buffers, etc. created
         // should be ignored
         return -1;
     }
 
     if(rocprofiler_start_context(ctx) != ROCPROFILER_STATUS_SUCCESS)
     {
         // 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_tool_configure_result_t*
rocprofiler_configure(uint32_t version,
                      const char* runtime_version,
                      uint32_t priority,
                      rocprofiler_client_id_t* client_id)
{
     // 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;
}

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_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

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

Tool registration

Tool registration#

Data Structures

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ rocprofiler_client_id_t

◆ rocprofiler_tool_configure_result_t

Typedef Documentation

◆ rocprofiler_client_finalize_t

◆ rocprofiler_configure_func_t

◆ rocprofiler_tool_finalize_t

◆ rocprofiler_tool_initialize_t

Function Documentation

◆ rocprofiler_configure()

◆ rocprofiler_force_configure()

◆ rocprofiler_is_finalized()

◆ rocprofiler_is_initialized()