External correlation

External correlation#

enum rocprofiler_external_correlation_id_request_kind_t#

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

Values:

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_NONE#: Unknown kind.

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_CORE_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_AMD_EXT_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_IMAGE_EXT_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_FINALIZE_EXT_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HIP_RUNTIME_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HIP_COMPILER_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CORE_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CONTROL_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_NAME_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MEMORY_COPY#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_KERNEL_DISPATCH#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_SCRATCH_MEMORY#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_RCCL_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_OMPT#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MEMORY_ALLOCATION#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_ROCDECODE_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_ROCJPEG_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CORE_RANGE_API#

enumerator ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_LAST#

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.

Param thread_id:: [in] Id of the thread making the request
Param context_id:: [in] Id of the context making the request
Param kind:: [in] Origin of the external correlation id request
Param operation:: [in] 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.
Param internal_corr_id_value:: [in] Current internal correlation ID value for the request
Param external_corr_id_value:: [out] Set this value to the desired external correlation ID value
Param data:: [in] The callback_args value passed to rocprofiler_configure_external_correlation_id_request_service.
Retval 0:: Used to indicate the tool had zero issues setting the external correlation ID field
Retval 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
Return:: int

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.

Parameters:

context_id – [in] Context to associate the service with
kinds – [in] 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.
kinds_count – [in] If the kinds array is non-null, set this to the size of the array.
callback – [in] The function to invoke for an external correlation ID request
callback_args – [in] Data provided to every invocation of the callback function

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.

Returns:

rocprofiler_status_t

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”).

Parameters:

kind – [in] External correlation id request domain
name – [out] 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
name_len – [out] If non-null, this will be assigned the length of the name (regardless of the name is a constant string or requires dynamic allocation)

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.

Returns:

rocprofiler_status_t

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.

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.

External correlation

Contents

External correlation#