AI/rocm-systems
2
0
Garpu 0
Kode Masalah Tarik Permintaan Actions Packages Projects Rilis Wiki Kegiatan
Files
2d8936362e8a25d75c68c43367ef69be840b7efd
rocm-systems/source/include/rocprofiler-sdk/external_correlation.h
T
Welton, Benjamin 2c4e20b951 [SWDEV-516561][1/2] Add MARKER_RANGE_EXTENT to capture ROCTX ranges (#363) 
* [SWDEV-516561][1/2] Add MARKER_RANGE_EXTENT to capture ROCTX ranges

Range extent to capture all work between roctxpush/pop operations. Entry callback takes place during roxtxpush and exit callback takes place in roctxpop. This is primarily to allow us to keep an ancestor id on the ancestor stack such that all operations that take place within the push/pop context can be annotated as being apart of this range. With the current setup (where push and pop are two separate operations that need to be combined externally), we cannot keep an ancestor id on the stack and thus cannot tie tracing events to particular ranges.

Correlation id information is inherited from the push operation. Ancestor id needs to be added in a future commit that also outputs this ancestor to CSV.

Output:

```
[ctest] {'size': 64, 'kind': 7, 'operation': 1, 'correlation_id': {'internal': 1525, 'external': 0, 'ancestor': 1524}, 'start_timestamp': 2932551479402642, 'end_timestamp': 2932551491178449, 'thread_id': 3254861}
[ctest] {'size': 64, 'kind': 8, 'operation': 2, 'correlation_id': {'internal': 1525, 'external': 0, 'ancestor': 1524}, 'start_timestamp': 2932551479405878, 'end_timestamp': 2932551491181214, 'thread_id': 3254861}
```

Note: Kind 8 = range extent op.

* Merge fix

Revert several changes

source/lib/rocprofiler-sdk/marker/range_marker.*

- separate out range marker implementation for standard marker implementation

Update public API with marker core range

Support marker core range in sdk (source/lib/rocprofiler-sdk)

Transition rocprofiler-sdk-tool and output lib to use marker core range

Misc fixes for tests

Fix logic in lib/output/generate{CSV,Stats}.cpp

Update tests/rocprofv3/tracing-hip-in-libraries (marker validation)

Fix test_otf2_data

* Test fixes

---------

Co-authored-by: Benjamin Welton <bewelton@amd.com>
2025-07-08 23:41:22 -07:00

205 baris
11 KiB
C
Mentah Salahkan Riwayat

// MIT License
//
// Copyright (c) 2023-2025 Advanced Micro Devices, Inc. All rights reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
#pragma once
#include <rocprofiler-sdk/defines.h>
#include <rocprofiler-sdk/fwd.h>
ROCPROFILER_EXTERN_C_INIT
/**
* @defgroup EXTERNAL_CORRELATION External Correlation IDs
* @brief User-defined correlation identifiers to supplement rocprofiler generated correlation ids
*
* @{
*/
/**
* @brief (experimental) ROCProfiler External Correlation ID Operations.
*
* These kinds correspond to callback and buffered tracing kinds (@see
* ::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.
*/
// NOLINTNEXTLINE(performance-enum-size)
typedef enum ROCPROFILER_SDK_EXPERIMENTAL rocprofiler_external_correlation_id_request_kind_t
{
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;
/**
* @brief (experimental) Callback requesting a value for the external correlation id.
*
* @param [in] thread_id Id of the thread making the request
* @param [in] context_id Id of the context making the request
* @param [in] kind Origin of the external correlation id request
* @param [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.
* @param [in] internal_corr_id_value Current internal correlation ID value for the request
* @param [out] external_corr_id_value Set this value to the desired external correlation ID value
* @param [in] data The `callback_args` value passed to
* ::rocprofiler_configure_external_correlation_id_request_service.
* @returns int
* @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
*/
ROCPROFILER_SDK_EXPERIMENTAL
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);
/**
* @brief (experimental) Configure External Correlation ID Request Service.
*
* @param [in] context_id Context to associate the service with
* @param [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.
* @param [in] kinds_count If the kinds array is non-null, set this to the size of the
* array.
* @param [in] callback The function to invoke for an external correlation ID request
* @param [in] callback_args Data provided to every invocation of the callback function
* @return ::rocprofiler_status_t
* @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED Invoked outside of the initialization
* function in ::rocprofiler_tool_configure_result_t provided to rocprofiler via
* ::rocprofiler_configure function
* @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND The provided context is not valid/registered
* @retval ::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_SDK_EXPERIMENTAL
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,
size_t kinds_count,
rocprofiler_external_correlation_id_request_cb_t callback,
void* callback_args) ROCPROFILER_API ROCPROFILER_NONNULL(4);
/**
* @brief 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").
*
* @param [in] kind External correlation id request domain
* @param [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
* @param [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)
* @return ::rocprofiler_status_t
* @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Returned if the domain id is not valid
* @retval ::ROCPROFILER_STATUS_SUCCESS Returned if a valid domain, regardless if there is a
* constant string or not.
*/
ROCPROFILER_SDK_EXPERIMENTAL
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) ROCPROFILER_API;
/**
* @brief 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.
*
* @param [in] context Associated context
* @param [in] tid thread identifier. @see rocprofiler_get_thread_id
* @param [in] external_correlation_id User data to place in external field in
* ::rocprofiler_correlation_id_t
* @return ::rocprofiler_status_t
* @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND Context does not exist
* @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Thread id is not valid
*/
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)
ROCPROFILER_API;
/**
* @brief Pop default value for `external` field in ::rocprofiler_correlation_id_t off of stack.
*
* @param [in] context Associated context
* @param [in] tid thread identifier. @see rocprofiler_get_thread_id
* @param [out] external_correlation_id Correlation id data popped off the stack
* @return ::rocprofiler_status_t
* @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND Context does not exist
* @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Thread id is not valid
*/
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)
ROCPROFILER_API;
/** @} */
ROCPROFILER_EXTERN_C_FINI
Reference in New Issue View Git Blame Copy Permalink