rocm-systems/source/include/rocprofiler-sdk/experimental/thread-trace/trace_decoder.h

// MIT License
//
// Copyright (c) 2024-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/experimental/thread-trace/trace_decoder_types.h>
#include <rocprofiler-sdk/fwd.h>

ROCPROFILER_EXTERN_C_INIT

/**
 * @defgroup THREAD_TRACE Thread Trace Decoding
 * @brief Provides API calls to decode thread trace data
 *
 * @{
 */

typedef struct rocprofiler_thread_trace_decoder_handle_t
{
    uint64_t handle;
} rocprofiler_thread_trace_decoder_handle_t;

/**
 * @brief Initializes Trace Decoder library
 * @param[out] handle Handle to created decoder instance.
 * @param[in] path Path to trace decoder library location (e.g. /opt/rocm/lib).
 * @retval ::ROCPROFILER_STATUS_ERROR_NOT_AVAILABLE Library not found
 * @retval ::ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_ABI Library found but version not supported
 * @retval ::ROCPROFILER_STATUS_SUCCESS Handle created
 */
rocprofiler_status_t
rocprofiler_thread_trace_decoder_create(rocprofiler_thread_trace_decoder_handle_t* handle,
                                        const char* path) ROCPROFILER_API ROCPROFILER_NONNULL(1, 2);

/**
 * @brief Deletes handle created by rocprofiler_thread_trace_decoder_create
 * @param[in] handle Handle to destroy
 */
void
rocprofiler_thread_trace_decoder_destroy(rocprofiler_thread_trace_decoder_handle_t handle)
    ROCPROFILER_API;

/**
 * @brief Loads a code object binary to match with Thread Trace
 * @param[in] handle Handle to decoder instance.
 * @param[in] load_id Code object load ID.
 * @param[in] load_addr Code object load address.
 * @param[in] load_size Code object load size.
 * @param[in] data Code object binary data. Must be at least load_size bytes.
 * @retval ::ROCPROFILER_STATUS_ERROR Unable to load code object.
 * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Invalid handle
 * @retval ::ROCPROFILER_STATUS_SUCCESS Code object loaded
 */
rocprofiler_status_t
rocprofiler_thread_trace_decoder_codeobj_load(rocprofiler_thread_trace_decoder_handle_t handle,
                                              uint64_t                                  load_id,
                                              uint64_t                                  load_addr,
                                              uint64_t                                  load_size,
                                              const void*                               data,
                                              uint64_t size) ROCPROFILER_API ROCPROFILER_NONNULL(5);

/**
 * @brief Unloads a code object binary
 * @param[in] handle Handle to decoder instance.
 * @param[in] load_id Code object load ID to remove.
 * @retval ::ROCPROFILER_STATUS_ERROR Code object not loaded.
 * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Invalid handle
 * @retval ::ROCPROFILER_STATUS_SUCCESS Code object unloaded
 */
rocprofiler_status_t
rocprofiler_thread_trace_decoder_codeobj_unload(rocprofiler_thread_trace_decoder_handle_t handle,
                                                uint64_t load_id) ROCPROFILER_API;

/**
 * @brief Callback for rocprofiler to return traces back to rocprofiler.
 * @param[in] trace_type_id One of rocprofiler_thread_trace_decoder_record_type_t
 * @param[in] trace_events A pointer to sequence of events, of size trace_size.
 * @param[in] trace_size The number of events in the trace.
 * @param[in] userdata Arbitrary data pointer to be sent back to the user via callback.
 */
typedef void (*rocprofiler_thread_trace_decoder_callback_t)(
    rocprofiler_thread_trace_decoder_record_type_t record_type_id,
    void*                                          trace_events,
    uint64_t                                       trace_size,
    void*                                          userdata);

/**
 * @brief Iterate over all event coordinates for a given agent_t and event_t.
 * @param[in] se_data_callback Callback to return shader engine data from.
 * @param[in] callback Decoded trace data returned to user.
 * @param[in] data Thread trace binary data.
 * @param[in] size Thread trace binary size.
 * @param[in] userdata Userdata passed back to caller via callback.
 */
rocprofiler_status_t
rocprofiler_trace_decode(rocprofiler_thread_trace_decoder_handle_t   handle,
                         rocprofiler_thread_trace_decoder_callback_t callback,
                         void*                                       data,
                         uint64_t                                    size,
                         void* userdata) ROCPROFILER_API ROCPROFILER_NONNULL(2, 3);

/**
 * @brief Returns the description of a rocprofiler_thread_trace_decoder_info_t record.
 * @param[in] info The decoder info received
 * @retval null terminated string as description of "info".
 */
const char*
rocprofiler_thread_trace_decoder_info_string(rocprofiler_thread_trace_decoder_handle_t handle,
                                             rocprofiler_thread_trace_decoder_info_t   info)
    ROCPROFILER_API;

ROCPROFILER_EXTERN_C_FINI