Intercept table for runtime libraries

Intercept table for runtime libraries#

ROCprofiler-SDK developer API: Intercept table for runtime libraries

ROCprofiler-SDK developer API 1.0.0

ROCm Profiling API and tools

Enable tools to wrap the runtime API function calls of HIP, HSA, and ROCTx before and after the "real" implementation is called. More...

Typedefs
typedef void(*	rocprofiler_intercept_library_cb_t) (rocprofiler_intercept_table_t type, uint64_t lib_version, uint64_t lib_instance, void *tables, uint64_t num_tables, void user_data)
	(experimental) Callback type when a new runtime library is loaded.

Functions
rocprofiler_status_t	rocprofiler_query_intercept_table_name (rocprofiler_intercept_table_t kind, const char *name, uint64_t name_len)
	(experimental) Query the name of the intercept table. 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").

rocprofiler_status_t	rocprofiler_at_intercept_table_registration (rocprofiler_intercept_library_cb_t callback, int libs, void *data)

Detailed Description

Enable tools to wrap the runtime API function calls of HIP, HSA, and ROCTx before and after the "real" implementation is called.

When an application invokes the public function from the HIP, HSA, and ROCTx libraries, these functions invoke a function pointer which, when properly chained, allow tools to wrap these function calls to collect information. When this capability is used alongside the rocprofiler API tracing, tools will wrap the rocprofiler wrappers of the API function, e.g. if the tool installs a wrapper around the hsa_init function called tool_hsa_init, and rocprofiler installs a wrapper around the hsa_init function called rocp_hsa_init, and within the HSA runtime library, the "real" implementation of the hsa_init invokes a function called real_hsa_init, the invocation chain (starting from within the user application) will be: <application> -> hsa_init -> tool_hsa_init -> rocp_hsa_init -> real_hsa_init. The return sequence will be the inverse of invocation chain: real_hsa_init -> rocp_hsa_init -> tool_hsa_init -> <application>. Thus, it is important for tools that use this feature to (A) call the next function in the chain and (B) properly handle the return value.

Typedef Documentation

◆ rocprofiler_intercept_library_cb_t

typedef void(* rocprofiler_intercept_library_cb_t) (rocprofiler_intercept_table_t type, uint64_t lib_version, uint64_t lib_instance, void **tables, uint64_t num_tables, void *user_data)

#include <rocprofiler-sdk/intercept_table.h>

(experimental) Callback type when a new runtime library is loaded.

See also: rocprofiler_at_intercept_table_registration

Parameters

[in]	type	Type of API table
[in]	lib_version	Major, minor, and patch version of library encoded into single number similar to ROCPROFILER_VERSION
[in]	lib_instance	The number of times this runtime library has been registered previously
[in]	tables	An array of pointers to the API tables
[in]	num_tables	The size of the array of pointers to the API tables
[in]	user_data	The pointer to the data provided to rocprofiler_at_intercept_table_registration

Definition at line 64 of file intercept_table.h.

Function Documentation

◆ rocprofiler_query_intercept_table_name()

rocprofiler_status_t rocprofiler_query_intercept_table_name	(	rocprofiler_intercept_table_t	kind,
		const char **	name,
		uint64_t *	name_len
	)

#include <rocprofiler-sdk/intercept_table.h>

(experimental) Query the name of the intercept table. 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").

Parameters

[in]	kind	Intercept table kind
[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
[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)

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND	Returned if the domain id is not valid
ROCPROFILER_STATUS_SUCCESS	Returned if a valid domain, regardless if there is a constant string or not.