// MIT License
//
// Copyright (c) 2022-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.

#ifndef ROCPROFSYS_USER_H_
#define ROCPROFSYS_USER_H_

#if defined(ROCPROFSYS_USER_SOURCE) && (ROCPROFSYS_USER_SOURCE > 0)
#    if !defined(ROCPROFSYS_PUBLIC_API)
#        define ROCPROFSYS_PUBLIC_API __attribute__((visibility("default")))
#    endif
#else
#    if !defined(ROCPROFSYS_PUBLIC_API)
#        define ROCPROFSYS_PUBLIC_API
#    endif
#endif

#include "rocprofiler-systems/categories.h"
#include "rocprofiler-systems/types.h"

#if defined(__cplusplus)
extern "C"
{
#endif

    /// @fn int rocprofsys_user_start_trace(void)
    /// @return rocprofsys_user_error_t value
    /// @brief Enable tracing on this thread and all subsequently created threads
    extern int rocprofsys_user_start_trace(void) ROCPROFSYS_PUBLIC_API;

    /// @fn int rocprofsys_user_stop_trace(void)
    /// @return rocprofsys_user_error_t value
    /// @brief Disable tracing on this thread and all subsequently created threads
    extern int rocprofsys_user_stop_trace(void) ROCPROFSYS_PUBLIC_API;

    /// @fn int rocprofsys_user_start_thread_trace(void)
    /// @return rocprofsys_user_error_t value
    /// @brief Enable tracing on this specific thread. Does not apply to subsequently
    /// created threads
    extern int rocprofsys_user_start_thread_trace(void) ROCPROFSYS_PUBLIC_API;

    /// @fn int rocprofsys_user_stop_thread_trace(void)
    /// @return rocprofsys_user_error_t value
    /// @brief Disable tracing on this specific thread. Does not apply to subsequently
    /// created threads
    extern int rocprofsys_user_stop_thread_trace(void) ROCPROFSYS_PUBLIC_API;

    /// @fn int rocprofsys_user_push_region(const char* id)
    /// @param id The string identifier for the region
    /// @return rocprofsys_user_error_t value
    /// @brief Start a user defined region.
    extern int rocprofsys_user_push_region(const char*) ROCPROFSYS_PUBLIC_API;

    /// @fn int rocprofsys_user_pop_region(const char* id)
    /// @param id The string identifier for the region
    /// @return rocprofsys_user_error_t value
    /// @brief End a user defined region. In general, user regions should be popped in
    /// the inverse order that they were pushed, i.e. first-in, last-out (FILO). The
    /// timemory backend was designed to accommodate asynchronous tasking, where FILO may
    /// be violated, and will thus compenstate for out-of-order popping, however, the
    /// perfetto backend will not; thus, out-of-order popping will result in different
    /// results in timemory vs. perfetto.
    extern int rocprofsys_user_pop_region(const char*) ROCPROFSYS_PUBLIC_API;

    /// @typedef rocprofsys_annotation rocprofsys_annotation_t
    ///
    /// @fn int rocprofsys_user_push_annotated_region(const char* id,
    ///                                              rocprofsys_annotation_t* annotations,
    ///                                              size_t num_annotations)
    /// @param id The string identifier for the region
    /// @param annotations Array of @ref rocprofsys_annotation instances
    /// @param num_annotations Number of annotations
    /// @return rocprofsys_user_error_t value
    /// @brief Start a user defined region and adds the annotations to the perfetto trace.
    extern int rocprofsys_user_push_annotated_region(const char*,
                                                     rocprofsys_annotation_t*,
                                                     size_t) ROCPROFSYS_PUBLIC_API;

    /// @fn int rocprofsys_user_pop_annotated_region(const char* id,
    ///                                             rocprofsys_annotation_t* annotations,
    ///                                             size_t num_annotations)
    /// @param id The string identifier for the region
    /// @param annotations Array of @ref rocprofsys_annotation instances
    /// @param num_annotations Number of annotations
    /// @return rocprofsys_user_error_t value
    /// @brief Stop a user defined region and adds the annotations to the perfetto trace.
    extern int rocprofsys_user_pop_annotated_region(const char*, rocprofsys_annotation_t*,
                                                    size_t) ROCPROFSYS_PUBLIC_API;

    /// mark causal progress
    extern int rocprofsys_user_progress(const char*) ROCPROFSYS_PUBLIC_API;

    /// mark causal progress with annotations
    extern int rocprofsys_user_annotated_progress(const char*, rocprofsys_annotation_t*,
                                                  size_t) ROCPROFSYS_PUBLIC_API;

    /// @fn int rocprofsys_user_configure(rocprofsys_user_configure_mode_t mode,
    ///                                  rocprofsys_user_callbacks_t inp,
    ///                                  rocprofsys_user_callbacks_t* out)
    /// @param[in] mode Specifies how the new callbacks are merged with the old
    /// callbacks
    /// @param[in] inp An @ref rocprofsys_user_callbacks instance specifying
    ///            the callbacks which should be invoked by the user API.
    /// @param[out] out Pointer to @ref rocprofsys_user_callbacks which,
    ///             when non-NULL, will be assigned the former callbacks.
    /// @return rocprofsys_user_error_t value
    /// @brief Configure the function pointers invoked by the rocprof-sys user API.
    /// The initial callbacks are set via the rocprof-sys-dl library when it is loaded but
    /// the user can user this feature to turn on/off the user API or customize how the
    /// the user callbacks occur. For example, the user could maintain one set of
    /// callbacks which discard any annotation data or redirect all unannotated user
    /// regions to the annotated user regions with annotations about some global state.
    /// Changing the callbacks is thread-safe but not thread-local.
    extern int rocprofsys_user_configure(
        rocprofsys_user_configure_mode_t mode, rocprofsys_user_callbacks_t inp,
        rocprofsys_user_callbacks_t* out) ROCPROFSYS_PUBLIC_API;

    /// @fn int rocprofsys_user_get_callbacks(int category, void** begin_func, void**
    /// end_func)
    /// @param[in] category An @ref ROCPROFSYS_USER_BINDINGS value
    /// @param[out] begin_func The pointer to the function which corresponds to "starting"
    /// the category, e.g. rocprofsys_user_start_trace or rocprofsys_user_push_region
    /// @param[out] end_func The pointer to the function which corresponds to "ending" the
    /// category, e.g. rocprofsys_user_stop_trace or rocprofsys_user_pop_region
    /// @return rocprofsys_user_error_t value
    /// @brief Get the current function pointers for a given category. The initial values
    /// are assigned by rocprof-sys-dl at start up.
    extern int rocprofsys_user_get_callbacks(rocprofsys_user_callbacks_t*)
        ROCPROFSYS_PUBLIC_API;

    /// @fn const char* rocprofsys_user_error_string(int error_category)
    /// @param error_category ROCPROFSYS_USER_ERROR value
    /// @return String descripting the error code
    /// @brief Return a descriptor for the provided error code
    extern const char* rocprofsys_user_error_string(int) ROCPROFSYS_PUBLIC_API;

#if defined(__cplusplus)
}
#endif

#endif  // ROCPROFSYS_USER_H_