External Correlation IDs

External Correlation IDs#

ROCprofiler-SDK developer API: External Correlation IDs

ROCprofiler-SDK developer API 1.0.0

ROCm Profiling API and tools

User-defined correlation identifiers to supplement rocprofiler generated correlation ids. More...

Typedefs
typedef int(*	rocprofiler_external_correlation_id_request_cb_t) (rocprofiler_thread_id_t thread_id, rocprofiler_context_id_t context_id, rocprofiler_external_correlation_id_request_kind_t kind, rocprofiler_tracing_operation_t operation, uint64_t internal_corr_id_value, rocprofiler_user_data_t external_corr_id_value, void data)
	(experimental) Callback requesting a value for the external correlation id.

Enumerations
enum	rocprofiler_external_correlation_id_request_kind_t { ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_NONE = 0 , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_CORE_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_AMD_EXT_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_IMAGE_EXT_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_FINALIZE_EXT_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HIP_RUNTIME_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HIP_COMPILER_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CORE_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CONTROL_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_NAME_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MEMORY_COPY , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_KERNEL_DISPATCH , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_SCRATCH_MEMORY , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_RCCL_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_OMPT , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MEMORY_ALLOCATION , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_ROCDECODE_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_ROCJPEG_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CORE_RANGE_API , ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_LAST }
	(experimental) ROCProfiler External Correlation ID Operations. More...

Functions
rocprofiler_status_t	rocprofiler_configure_external_correlation_id_request_service (rocprofiler_context_id_t context_id, const rocprofiler_external_correlation_id_request_kind_t kinds, unsigned long kinds_count, rocprofiler_external_correlation_id_request_cb_t callback, void callback_args)
	(experimental) Configure External Correlation ID Request Service.

rocprofiler_status_t	rocprofiler_query_external_correlation_id_request_kind_name (rocprofiler_external_correlation_id_request_kind_t kind, const char *name, uint64_t name_len)
	Query the name of the external correlation request kind. 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_push_external_correlation_id (rocprofiler_context_id_t context, rocprofiler_thread_id_t tid, rocprofiler_user_data_t external_correlation_id)
	Push default value for `external` field in rocprofiler_correlation_id_t onto stack.

rocprofiler_status_t	rocprofiler_pop_external_correlation_id (rocprofiler_context_id_t context, rocprofiler_thread_id_t tid, rocprofiler_user_data_t *external_correlation_id)
	Pop default value for `external` field in rocprofiler_correlation_id_t off of stack.

Detailed Description

User-defined correlation identifiers to supplement rocprofiler generated correlation ids.

Typedef Documentation

◆ rocprofiler_external_correlation_id_request_cb_t

typedef int(* rocprofiler_external_correlation_id_request_cb_t) (rocprofiler_thread_id_t thread_id, rocprofiler_context_id_t context_id, rocprofiler_external_correlation_id_request_kind_t kind, rocprofiler_tracing_operation_t operation, uint64_t internal_corr_id_value, rocprofiler_user_data_t *external_corr_id_value, void *data)

#include <rocprofiler-sdk/external_correlation.h>

(experimental) Callback requesting a value for the external correlation id.

Parameters

[in]	thread_id	Id of the thread making the request
[in]	context_id	Id of the context making the request
[in]	kind	Origin of the external correlation id request
[in]	operation	Regardless of whether callback or buffer tracing is being used, the operation value will be the same, i.e., regardless of whether callback kind is ROCPROFILER_CALLBACK_TRACING_HSA_CORE_API or the buffer record kind is ROCPROFILER_BUFFER_TRACING_HSA_CORE_API, the data/record for `hsa_init` will have an operation value of ROCPROFILER_HSA_CORE_API_ID_hsa_init.
[in]	internal_corr_id_value	Current internal correlation ID value for the request
[out]	external_corr_id_value	Set this value to the desired external correlation ID value
[in]	data	The `callback_args` value passed to rocprofiler_configure_external_correlation_id_request_service.

Returns: int

Return values

0	Used to indicate the tool had zero issues setting the external correlation ID field
1	(or any other non-zero number) Used to indicate the callback did not set an external correlation ID value and the thread-local value for the most recently pushed external correlation ID should be used instead

Definition at line 101 of file external_correlation.h.

Enumeration Type Documentation

◆ rocprofiler_external_correlation_id_request_kind_t

enum rocprofiler_external_correlation_id_request_kind_t

#include <rocprofiler-sdk/external_correlation.h>

(experimental) ROCProfiler External Correlation ID Operations.

These kinds correspond to callback and buffered tracing kinds (

See also: rocprofiler_callback_tracing_kind_t and rocprofiler_buffer_tracing_kind_t) which generate correlation IDs. Typically, rocprofiler-sdk uses the most recent external correlation ID on the current thread set via rocprofiler_push_external_correlation_id; however, this approach can be problematic if a new external correlation ID should be set before the ROCPROFILER_CALLBACK_PHASE_ENTER callback or if relevant external correlation IDs are desired when the buffered tracing is used. Thus, rocprofiler-sdk provides a way for tools to get a callback whenever an external correlation ID is needed. However, this can add significant overhead for those who only need these callbacks for, say, kernel dispatches while the HSA API is being traced (i.e. lots of callbacks for HSA API functions). The enumeration below is provided to ensure that tools can default to using the external correlation IDs set via the push/pop methods where the external correlation ID value is not important while also getting a request for an external correlation ID for other tracing kinds.

Enumerator
ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_NONE	Unknown kind.

Definition at line 55 of file external_correlation.h.

{
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_NONE = 0,               ///< Unknown kind
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_CORE_API,           ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_AMD_EXT_API,        ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_IMAGE_EXT_API,      ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_FINALIZE_EXT_API,   ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HIP_RUNTIME_API,        ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HIP_COMPILER_API,       ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CORE_API,        ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CONTROL_API,     ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_NAME_API,        ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MEMORY_COPY,            ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_KERNEL_DISPATCH,        ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_SCRATCH_MEMORY,         ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_RCCL_API,               ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_OMPT,                   ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MEMORY_ALLOCATION,      ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_ROCDECODE_API,          ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_ROCJPEG_API,            ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CORE_RANGE_API,  ///<
    ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_LAST,
} rocprofiler_external_correlation_id_request_kind_t;

Function Documentation

◆ rocprofiler_configure_external_correlation_id_request_service()

rocprofiler_status_t rocprofiler_configure_external_correlation_id_request_service	(	rocprofiler_context_id_t	context_id,
		const rocprofiler_external_correlation_id_request_kind_t *	kinds,
		unsigned long	kinds_count,
		rocprofiler_external_correlation_id_request_cb_t	callback,
		void *	callback_args
	)

#include <rocprofiler-sdk/external_correlation.h>

(experimental) Configure External Correlation ID Request Service.

Parameters

[in]	context_id	Context to associate the service with
[in]	kinds	Array of rocprofiler_external_correlation_id_request_kind_t values. If this parameter is null, all tracing operations will invoke the callback to request an external correlation ID.
[in]	kinds_count	If the kinds array is non-null, set this to the size of the array.
[in]	callback	The function to invoke for an external correlation ID request
[in]	callback_args	Data provided to every invocation of the callback function

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED	Invoked outside of the initialization function in rocprofiler_tool_configure_result_t provided to rocprofiler via rocprofiler_configure function
ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND	The provided context is not valid/registered
ROCPROFILER_STATUS_ERROR_SERVICE_ALREADY_CONFIGURED	if the same rocprofiler_callback_tracing_kind_t value is provided more than once (per context) – in other words, we do not support overriding or combining the kinds in separate function calls.

◆ rocprofiler_pop_external_correlation_id()

rocprofiler_status_t rocprofiler_pop_external_correlation_id	(	rocprofiler_context_id_t	context,
		rocprofiler_thread_id_t	tid,
		rocprofiler_user_data_t *	external_correlation_id
	)

#include <rocprofiler-sdk/external_correlation.h>

Pop default value for external field in rocprofiler_correlation_id_t off of stack.

Parameters

[in]	context	Associated context
[in]	tid	thread identifier.

See also: rocprofiler_get_thread_id

Parameters

[out] external_correlation_id Correlation id data popped off the stack

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND	Context does not exist
ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT	Thread id is not valid

◆ rocprofiler_push_external_correlation_id()

rocprofiler_status_t rocprofiler_push_external_correlation_id	(	rocprofiler_context_id_t	context,
		rocprofiler_thread_id_t	tid,
		rocprofiler_user_data_t	external_correlation_id
	)

#include <rocprofiler-sdk/external_correlation.h>

Push default value for external field in rocprofiler_correlation_id_t onto stack.

External correlation ids are thread-local values. However, if rocprofiler internally requests an external correlation id on a non-main thread and an external correlation id has not been pushed for this thread, the external correlation ID will default to the latest external correlation id on the main thread – this allows tools to push an external correlation id once on the main thread for, say, the MPI rank or process-wide UUID and this value will be used by all subsequent child threads.

Parameters

[in]	context	Associated context
[in]	tid	thread identifier.

See also: rocprofiler_get_thread_id

Parameters

[in] external_correlation_id User data to place in external field in rocprofiler_correlation_id_t

Returns: rocprofiler_status_t

Return values

ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND	Context does not exist
ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT	Thread id is not valid

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

◆ rocprofiler_query_external_correlation_id_request_kind_name()

rocprofiler_status_t rocprofiler_query_external_correlation_id_request_kind_name	(	rocprofiler_external_correlation_id_request_kind_t	kind,
		const char **	name,
		uint64_t *	name_len
	)

#include <rocprofiler-sdk/external_correlation.h>

Query the name of the external correlation request kind. 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	External correlation id request domain
[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.

External Correlation IDs

External Correlation IDs#

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ rocprofiler_external_correlation_id_request_cb_t

Enumeration Type Documentation

◆ rocprofiler_external_correlation_id_request_kind_t

Function Documentation

◆ rocprofiler_configure_external_correlation_id_request_service()

◆ rocprofiler_pop_external_correlation_id()

◆ rocprofiler_push_external_correlation_id()

◆ rocprofiler_query_external_correlation_id_request_kind_name()