From 3ee393047c995c18cc6beb3821557732317d9ff3 Mon Sep 17 00:00:00 2001 From: Milan Radosavljevic Date: Tue, 18 Nov 2025 19:48:27 +0100 Subject: [PATCH] Add user_api_active flag to enable/disable user-defined regions (#312) * Add user start/stop bool * Update documentation for user-api * Update projects/rocprofiler-systems/source/lib/rocprof-sys-dl/dl.cpp Co-authored-by: Aleksandar Djordjevic * Format fix --------- Co-authored-by: Aleksandar Djordjevic --- .../docs/conceptual/data-collection-modes.rst | 4 ++-- .../how-to/general-tips-using-rocprof-sys.rst | 2 +- .../docs/how-to/using-rocprof-sys-api.rst | 3 --- .../source/lib/rocprof-sys-dl/dl.cpp | 17 ++++++++++++---- .../rocprofiler-systems/types.h | 20 +++++++++---------- .../rocprofiler-systems/user.h | 14 +++++++------ 6 files changed, 34 insertions(+), 26 deletions(-) diff --git a/projects/rocprofiler-systems/docs/conceptual/data-collection-modes.rst b/projects/rocprofiler-systems/docs/conceptual/data-collection-modes.rst index 42ef5c8365..205c6622c7 100644 --- a/projects/rocprofiler-systems/docs/conceptual/data-collection-modes.rst +++ b/projects/rocprofiler-systems/docs/conceptual/data-collection-modes.rst @@ -30,8 +30,8 @@ ROCm Systems Profiler supports several modes of recording trace and profiling da | | dynamic library/executable, like ``pthread_mutex_lock`` | | | in ``libpthread.so`` or ``MPI_Init`` in the MPI library | +-----------------------------+---------------------------------------------------------+ -| User API | User-defined regions and controls for ROCm Systems | -| | Profiler | +| User API | User-defined regions and controls for User API ROCm | +| | Systems Profiler | +-----------------------------+---------------------------------------------------------+ The two most generic and important modes are binary instrumentation and statistical sampling. diff --git a/projects/rocprofiler-systems/docs/how-to/general-tips-using-rocprof-sys.rst b/projects/rocprofiler-systems/docs/how-to/general-tips-using-rocprof-sys.rst index bf0aee9d10..eb365a9090 100644 --- a/projects/rocprofiler-systems/docs/how-to/general-tips-using-rocprof-sys.rst +++ b/projects/rocprofiler-systems/docs/how-to/general-tips-using-rocprof-sys.rst @@ -24,7 +24,7 @@ the :doc:`ROCm Systems Profiler glossary <../reference/rocprof-sys-glossary>`. * **Use binary instrumentation for characterizing the performance of every invocation of specific functions** * **Use statistical sampling to characterize the performance of the entire application while minimizing overhead** * Enable statistical sampling after binary instrumentation to help "fill in the gaps" between instrumented regions -* Use the user API to create custom regions and enable/disable ROCm Systems Profiler for specific processes, threads, and regions +* Use the user API to create custom regions and enable/disable User API ROCm Systems Profiler for specific processes, threads, and regions * Dynamic symbol interception, callback APIs, and the user API are always available with binary instrumentation and sampling * Dynamic symbol interception and callback APIs are (generally) controlled through ``ROCPROFSYS_USE_`` diff --git a/projects/rocprofiler-systems/docs/how-to/using-rocprof-sys-api.rst b/projects/rocprofiler-systems/docs/how-to/using-rocprof-sys-api.rst index 94874acd08..639f87cd78 100644 --- a/projects/rocprofiler-systems/docs/how-to/using-rocprof-sys-api.rst +++ b/projects/rocprofiler-systems/docs/how-to/using-rocprof-sys-api.rst @@ -24,9 +24,6 @@ ROCm Systems Profiler API, such as ``rocprofsys_user_push_region`` and is disabled at start up, which means ``rocprofsys_user_stop_trace()`` is not required at the beginning of ``main``. This behavior can be manually controlled by using the ``ROCPROFSYS_INIT_ENABLED`` environment variable. - User-defined regions are always - recorded, regardless of whether ``rocprofsys_user_start_*`` or - ``rocprofsys_user_stop_*`` has been called. .. code-block:: shell diff --git a/projects/rocprofiler-systems/source/lib/rocprof-sys-dl/dl.cpp b/projects/rocprofiler-systems/source/lib/rocprof-sys-dl/dl.cpp index fb4d709616..9854403e08 100644 --- a/projects/rocprofiler-systems/source/lib/rocprof-sys-dl/dl.cpp +++ b/projects/rocprofiler-systems/source/lib/rocprof-sys-dl/dl.cpp @@ -511,6 +511,13 @@ get_active() return *_v; } +auto& +get_user_api_active() +{ + static bool _v{ false }; + return _v; +} + auto& get_enabled() { @@ -797,12 +804,14 @@ extern "C" int rocprofsys_user_start_trace_dl(void) { dl::get_enabled().store(true); + dl::get_user_api_active() = true; return rocprofsys_user_start_thread_trace_dl(); } int rocprofsys_user_stop_trace_dl(void) { dl::get_enabled().store(false); + dl::get_user_api_active() = false; return rocprofsys_user_stop_thread_trace_dl(); } @@ -820,13 +829,13 @@ extern "C" int rocprofsys_user_push_region_dl(const char* name) { - if(!dl::get_active()) return 0; + if(!dl::get_active() && !dl::get_user_api_active()) return 0; return ROCPROFSYS_DL_INVOKE(get_indirect().rocprofsys_push_region_f, name); } int rocprofsys_user_pop_region_dl(const char* name) { - if(!dl::get_active()) return 0; + if(!dl::get_active() && !dl::get_user_api_active()) return 0; return ROCPROFSYS_DL_INVOKE(get_indirect().rocprofsys_pop_region_f, name); } @@ -840,7 +849,7 @@ extern "C" rocprofsys_annotation_t* _annotations, size_t _annotation_count) { - if(!dl::get_active()) return 0; + if(!dl::get_active() && !dl::get_user_api_active()) return 0; return ROCPROFSYS_DL_INVOKE(get_indirect().rocprofsys_push_category_region_f, ROCPROFSYS_CATEGORY_USER, name, _annotations, _annotation_count); @@ -850,7 +859,7 @@ extern "C" rocprofsys_annotation_t* _annotations, size_t _annotation_count) { - if(!dl::get_active()) return 0; + if(!dl::get_active() && !dl::get_user_api_active()) return 0; return ROCPROFSYS_DL_INVOKE(get_indirect().rocprofsys_pop_category_region_f, ROCPROFSYS_CATEGORY_USER, name, _annotations, _annotation_count); diff --git a/projects/rocprofiler-systems/source/lib/rocprof-sys-user/rocprofiler-systems/types.h b/projects/rocprofiler-systems/source/lib/rocprof-sys-user/rocprofiler-systems/types.h index ea1277c653..4dfa738a8f 100644 --- a/projects/rocprofiler-systems/source/lib/rocprof-sys-user/rocprofiler-systems/types.h +++ b/projects/rocprofiler-systems/source/lib/rocprof-sys-user/rocprofiler-systems/types.h @@ -55,25 +55,25 @@ extern "C" rocprofsys_annotated_region_func_t annotated_progress; /// @var start_trace - /// @brief callback for enabling tracing globally + /// @brief Callback for enabling user defined tracing globally. /// @var stop_trace - /// @brief callback for disabling tracing globally + /// @brief Callback for disabling user defined tracing globally. /// @var start_thread_trace - /// @brief callback for enabling tracing on current thread + /// @brief Callback for enabling user defined tracing on the current thread. /// @var stop_thread_trace - /// @brief callback for disabling tracing on current thread + /// @brief Callback for disabling user defined tracing on the current thread. /// @var push_region - /// @brief callback for starting a trace region + /// @brief Callback for starting a user defined trace region. /// @var pop_region - /// @brief callback for ending a trace region + /// @brief Callback for ending a user defined trace region. /// @var progress - /// @brief callback for marking an causal profiling event + /// @brief Callback for marking a causal profiling event. /// @var push_annotated_region - /// @brief callback for starting a trace region + annotations + /// @brief Callback for starting a user defined trace region with annotations. /// @var pop_annotated_region - /// @brief callback for ending a trace region + annotations + /// @brief Callback for ending a user defined trace region with annotations. /// @var annotated_progress - /// @brief callback for marking an causal profiling event + annotations + /// @brief Callback for marking a causal profiling event with annotations. } rocprofsys_user_callbacks_t; /// @enum ROCPROFSYS_USER_CONFIGURE_MODE diff --git a/projects/rocprofiler-systems/source/lib/rocprof-sys-user/rocprofiler-systems/user.h b/projects/rocprofiler-systems/source/lib/rocprof-sys-user/rocprofiler-systems/user.h index 02a65085b8..c5ef8fe857 100644 --- a/projects/rocprofiler-systems/source/lib/rocprof-sys-user/rocprofiler-systems/user.h +++ b/projects/rocprofiler-systems/source/lib/rocprof-sys-user/rocprofiler-systems/user.h @@ -43,24 +43,26 @@ extern "C" /// @fn int rocprofsys_user_start_trace(void) /// @return rocprofsys_user_error_t value - /// @brief Enable tracing on this thread and all subsequently created threads + /// @brief Enable user defined tracing on this thread and on 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 + /// @brief Disable user defined tracing on this thread and on 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 + /// @brief Enable user defined 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 + /// @brief Disable user defined 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)