External Correlation IDs#
|
Rocprofiler SDK Developer API 0.4.0
ROCm Profiling API and tools
|
External Correlation IDs
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, uint32_t operation, uint64_t internal_corr_id_value, rocprofiler_user_data_t *external_corr_id_value, void *data) |
| Callback requesting a value for the external correlation id. | |
Functions | |
| rocprofiler_status_t | rocprofiler_configure_external_correlation_id_request_service (rocprofiler_context_id_t context_id, rocprofiler_external_correlation_id_request_kind_t *kinds, unsigned long kinds_count, rocprofiler_external_correlation_id_request_cb_t callback, void *callback_args) |
| Configure External Correlation ID Request Service. | |
| 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, uint32_t operation, uint64_t internal_corr_id_value, rocprofiler_user_data_t *external_corr_id_value, void *data) |
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_initwill 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_argsvalue 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 93 of file external_correlation.h.
Enumeration Type Documentation
◆ rocprofiler_external_correlation_id_request_kind_t
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.
Definition at line 54 of file external_correlation.h.
55{
rocprofiler_external_correlation_id_request_kind_t
ROCProfiler External Correlation ID Operations.
Definition external_correlation.h:55
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_LAST
Definition external_correlation.h:69
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_SCRATCH_MEMORY
Definition external_correlation.h:68
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_NAME_API
Definition external_correlation.h:65
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_FINALIZE_EXT_API
Definition external_correlation.h:60
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HIP_RUNTIME_API
Definition external_correlation.h:61
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MEMORY_COPY
Definition external_correlation.h:66
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CORE_API
Definition external_correlation.h:63
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_KERNEL_DISPATCH
Definition external_correlation.h:67
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_IMAGE_EXT_API
Definition external_correlation.h:59
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_MARKER_CONTROL_API
Definition external_correlation.h:64
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_CORE_API
Definition external_correlation.h:57
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HIP_COMPILER_API
Definition external_correlation.h:62
@ ROCPROFILER_EXTERNAL_CORRELATION_REQUEST_HSA_AMD_EXT_API
Definition external_correlation.h:58
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, |
| rocprofiler_external_correlation_id_request_kind_t * | kinds, | ||
| unsigned long | kinds_count, | ||
| rocprofiler_external_correlation_id_request_cb_t | callback, | ||
| void * | callback_args | ||
| ) |
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 | ||
| ) |
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 | ||
| ) |
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.
Generated by
1.9.8