Support Tool Intercept API Tables (#165)

* Update include/rocprofiler

- intercept_table.h header
- generic rocprofiler_runtime_library_t
- rocprofiler_internal_thread_library_t is not typedef for rocprofiler_runtime_library_t
- rocprofiler_at_runtime_api_registration

* Update lib/rocprofiler

- minor tweaks to context.cpp
  - check if none context early
  - disallow stop_context when finalizing
- add intercept_table.hpp and intercept_table.cpp
  - implement rocprofiler_at_runtime_api_registration
  - implement notify_runtime_api_registration
- update registration.cpp
  - invoke notify_runtime_api_registration
  - tweak to fini status when invoking client finalizer

* Update lib/rocprofiler/tests

- add tests for intercept table

* Add samples/intercept_table

- demonstrate how to install custom API function wrappers instead of relying on HSA callback tracing

* Update lib/rocprofiler/tests/intercept_table.cpp

- remove _SERVICE from ROCPROFILER_SERVICE_

* Update include/rocprofiler/intercept_table.h

- Update doxygen comments

* Update lib/rocprofiler/intercept_table.cpp

- return error config locked if already initialized

* Update lib/rocprofiler/intercept_table.cpp

- remove unnecessary alias

* Apply suggestions from code review

Co-authored-by: Tony Tye <Tony.Tye@amd.com>

* Update doxygen comments

- clarify when rocprofiler_at_runtime_api_registration can be invoked

* Use rocprofiler_runtime_library_t for intercept table and internal threading

- remove rocprofiler_intercept_library_t alias to rocprofiler_runtime_library_t
- remove rocprofiler_internal_thread_library_t alias to rocprofiler_runtime_library_t
- move around documentation with regard to rocprofiler_runtime_library_t enumeration
- added some extra doxygen documentation to internal threading functions

---------

Co-authored-by: Tony Tye <Tony.Tye@amd.com>
This commit is contained in:
Jonathan R. Madsen
2023-11-02 19:10:10 -05:00
committed by GitHub
parent 14373c57be
commit 4f2dc896d3
22 changed files with 1823 additions and 52 deletions
@@ -24,6 +24,7 @@ set(ROCPROFILER_HEADER_FILES
fwd.h
hip.h
hsa.h
intercept_table.h
internal_threading.h
marker.h
pc_sampling.h
+14
View File
@@ -209,6 +209,20 @@ typedef enum // NOLINT(performance-enum-size)
ROCPROFILER_BUFFER_POLICY_LAST,
} rocprofiler_buffer_policy_t;
/**
* @brief Enumeration for specifying runtime libraries supported by rocprofiler. This enumeration is
* used for intercept tables and thread creation callbacks. @see INTERCEPT_TABLE and @see
* INTERNAL_THREADING.
*/
typedef enum
{
ROCPROFILER_LIBRARY = (1 << 0),
ROCPROFILER_HSA_LIBRARY = (1 << 1),
ROCPROFILER_HIP_LIBRARY = (1 << 2),
ROCPROFILER_MARKER_LIBRARY = (1 << 3),
ROCPROFILER_LIBRARY_LAST = ROCPROFILER_MARKER_LIBRARY,
} rocprofiler_runtime_library_t;
//--------------------------------------------------------------------------------------//
//
// ALIASES
@@ -0,0 +1,223 @@
// MIT License
//
// Copyright (c) 2023 ROCm Developer Tools
//
// 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/defines.h>
#include <rocprofiler/fwd.h>
ROCPROFILER_EXTERN_C_INIT
/**
* @defgroup INTERCEPT_TABLE Intercept table for runtime libraries
* @brief Enable tools to wrap the runtime API function calls of HIP, HSA, and ROCTx before and
* after the "real" implementation is called.
*
* When an application invokes the public function from the HIP, HSA, and ROCTx libraries, these
* functions invoke a function pointer which, when properly chained, allow tools to wrap these
* function calls to collect information. When this capability is used alongside the rocprofiler API
* tracing, tools will wrap the rocprofiler wrappers of the API function, e.g. if the tool installs
* a wrapper around the `hsa_init` function called `tool_hsa_init`, and rocprofiler installs a
* wrapper around the `hsa_init` function called `rocp_hsa_init`, and within the HSA runtime
* library, the "real" implementation of the `hsa_init` invokes a function called `real_hsa_init`,
* the invocation chain (starting from within the user application) will be: `<application>` ->
* `hsa_init` -> `tool_hsa_init` -> `rocp_hsa_init` -> `real_hsa_init`. The return sequence will be
* the inverse of invocation chain: `real_hsa_init` -> `rocp_hsa_init` -> `tool_hsa_init` ->
* `<application>`. Thus, it is important for tools that use this feature to (A) call the next
* function in the chain and (B) properly handle the return value.
*
* @{
*/
/**
* @brief Callback type when a new runtime library is loaded. @see
* rocprofiler_at_runtime_api_registration
* @param [in] type Type of API table
* @param [in] lib_version Major, minor, and patch version of library encoded into single number
* similar to @ref ROCPROFILER_VERSION
* @param [in] lib_instance The number of times this runtime library has been registered previously
* @param [in] tables An array of pointers to the API tables
* @param [in] num_tables The size of the array of pointers to the API tables
* @param [in] user_data The pointer to the data provided to @ref
* rocprofiler_at_runtime_api_registration
*/
typedef void (*rocprofiler_intercept_library_cb_t)(rocprofiler_runtime_library_t type,
uint64_t lib_version,
uint64_t lib_instance,
void** tables,
uint64_t num_tables,
void* user_data);
/**
* @brief Invoke this function to receive callbacks when a ROCm library registers its API
* intercept table with rocprofiler. Use the @ref rocprofiler_runtime_library_t enumeration for
* specifying which raw API tables the tool would like to have access to. E.g. including @ref
* ROCPROFILER_HSA_LIBRARY in the @ref rocprofiler_at_runtime_api_registration function call
* communicates to rocprofiler that, when rocprofiler receives a `HsaApiTable` instance, the tool
* would like rocprofiler to provide it access too.
*
* When the HIP, HSA, and ROCTx libraries are initialized (either explicitly or on the first
* invocation of one of their public API functions), these runtimes will provide a table of function
* pointers to the rocprofiler library via the rocprofiler-register library if the
* `rocprofiler_configure` symbol is visible in the application's symbol table. The vast majority of
* tools will want to use the @ref CALLBACK_TRACING_SERVICE to trace these runtime APIs, however,
* some tools may want or require installing their own intercept functions in lieu of receiving
* these callbacks and those tools should use the @ref rocprofiler_at_runtime_api_registration to
* install their intercept functions. There are no restrictions to where or how early this function
* can be invoked but it will return ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED if it is
* invoked after rocprofiler has requested all the tool configurations. Thus, it is highly
* recommended to invoke this function within the @ref rocprofiler_configure function or the
* callback passed to the @ref rocprofiler_force_configure function -- the reason for this
* recommendation is that if @ref rocprofiler_at_runtime_api_registration is invoked in one of these
* locations, rocprofiler can guarantee that the tool will be passed the API table because, at the
* first instance of a runtime registering it's API table, rocprofiler will ensure that, in the case
* of the former, rocprofiler will invoke all of the @ref rocprofiler_configure symbols that are
* visible before checking the list of tools which want to receive the API tables and, in the case
* of the latter, @ref rocprofiler_force_configure will fail with error code @ref
* ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED if a runtime has already been registered (and,
* therefore, already scanned and invoked the visible @ref rocprofiler_configure symbols and
* completed the tool initialization). If @ref rocprofiler_at_runtime_api_registration is invoked
* outside of these recommended places, even if it is done before the `main` function starts (e.g.
* in a library init/constructor function), it is possible that another library, such as ROCm-aware
* MPI, caused the HIP and HSA runtime libraries to be initialized when that library was loaded. In
* this aforementioned scenario, if the ROCm-aware MPI library library init/constructor function
* runs before your library init/constructor function, rocprofiler will have already processed the
* API table and will not provide the API table to the tool due to the fact that the API may already
* be in use and, thus, any modifications to the table might result in thread-safety violations or
* more disastrous consequences.
*
* @param [in] callback Callback to tool invoked when a runtime registers their API table with
* rocprofiler
* @param [in] libs Bitwise-or of libraries, e.g. `ROCPROFILER_HSA_LIBRARY | ROCPROFILER_HIP_LIBRARY
* | ROCPROFILER_MARKER_LIBRARY` means the callbacks will be invoked whenever the HSA, HIP, and
* ROCTx libraries register the intercept table.
* @param [in] data Data to provide to callback(s)
* @return ::rocprofiler_status_t
* @retval ::ROCPROFILER_STATUS_SUCCESS Callback was registered for specified runtime(s)
* @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED rocprofiler has already initialized
* @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT this error code is returned if
* `ROCPROFILER_LIBRARY` is included in bitwise-or of the libs
* @retval ::ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED this error code is returned if one of the
* specified libraries does not have support for API intercept tables (which should not be the case
* by the time this code is publicly released)
*
* @code{.cpp}
* namespace
* {
* // this function generates a wrapper around the original function that
* // prints out the function name and then invokes the original function
* template <size_t Idx, typename RetT, typename... Args>
* auto
* generate_wrapper(const char* name, RetT (*func)(Args...))
* {
* using functor_type = RetT (*)(Args...);
*
* // save function name, "real function"
* static const auto* func_name = name;
* static functor_type underlying_func = func;
* static functor_type wrapped_func = [](Args... args) -> RetT {
* std::cout << "Wrapping " << func_name << "..." << std::endl;
* if(underlying_func) return underlying_func(args...);
* if constexpr(!std::is_void<RetT>::value) return RetT{};
* };
*
* return wrapped_func;
* }
*
*
* // this macro installs the wrapper in place of the original function
* #define GENERATE_WRAPPER(TABLE, FUNC) \
* TABLE->FUNC##_fn = generate_wrapper<__COUNTER__>(#FUNC, TABLE->FUNC##_fn)
*
*
* // this is the function that gets called when the HSA runtime
* // intercept table is registered with rocprofiler
* void
* api_registration_callback(rocprofiler_runtime_library_t type,
* uint64_t lib_version,
* uint64_t lib_instance,
* void** tables,
* uint64_t num_tables,
* void* user_data)
* {
* if(type != ROCPROFILER_HSA_LIBRARY)
* throw std::runtime_error{"unexpected library type: " +
* std::to_string(static_cast<int>(type))};
* if(lib_instance != 0) throw std::runtime_error{"multiple instances of HSA runtime library"};
* if(num_tables != 1) throw std::runtime_error{"expected only one table of type HsaApiTable"};
*
* auto* hsa_api_table = static_cast<HsaApiTable*>(tables[0]);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_agent_get_info);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_agent_iterate_isas);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_code_object_reader_create_from_memory);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_executable_create_alt);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_executable_freeze);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_executable_get_symbol_by_name);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_executable_iterate_symbols);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_executable_load_agent_code_object);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_executable_symbol_get_info);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_isa_get_info_alt);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_iterate_agents);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_queue_add_write_index_screlease);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_queue_create);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_queue_load_read_index_relaxed);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_queue_load_read_index_scacquire);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_signal_create);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_signal_destroy);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_signal_load_relaxed);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_signal_silent_store_relaxed);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_signal_store_screlease);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_signal_wait_scacquire);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_system_get_info);
* GENERATE_WRAPPER(hsa_api_table->core_, hsa_system_get_major_extension_table);
* }
* } // namespace
*
*
* extern "C" rocprofiler_tool_configure_result_t*
* rocprofiler_configure(uint32_t version,
* const char* runtime_version,
* uint32_t priority,
* rocprofiler_client_id_t* id)
* {
* // set the client name
* id->name = "ExampleTool";
*
* // specify that we only want to intercept the HSA library
* rocprofiler_at_runtime_api_registration(api_registration_callback,
* ROCPROFILER_HSA_LIBRARY, nullptr);
*
* return nullptr;
* }
* @endcode
*
* @example intercept_table/client.cpp
* Example demonstrating @ref rocprofiler_at_runtime_api_registration usage
*/
rocprofiler_status_t
rocprofiler_at_runtime_api_registration(rocprofiler_intercept_library_cb_t callback,
int libs,
void* data) ROCPROFILER_API;
/** @} */
ROCPROFILER_EXTERN_C_FINI
+31 -27
View File
@@ -32,44 +32,37 @@ ROCPROFILER_EXTERN_C_INIT
* @brief Callbacks before and after threads created internally by libraries
*
* @{
* @example api_buffered_tracing/client.cpp
* Example demonstrating @ref BUFFER_TRACING_SERVICE that includes usage of @ref
* rocprofiler_at_internal_thread_create, @ref rocprofiler_create_callback_thread, and @ref
* rocprofiler_assign_callback_thread.
*/
/**
* @brief Enumeration for specifying which libraries you want callbacks before and after the library
* creates an internal thread. These callbacks will be invoked on the thread that is about to create
* the new thread (not on the newly created thread). In thread-aware tools that wrap pthread_create,
* this can be used to disable the wrapper before the pthread_create invocation and re-enable the
* wrapper afterwards. In many cases, tools will want to ignore the thread(s) created by rocprofiler
* since these threads do not exist in the normal application execution, whereas the internal
* threads for HSA, HIP, etc. are created in normal application execution; however, the HIP, HSA,
* etc. internal threads are typically background threads which just monitor kernel completion and
* are unlikely to contribute to any performance issues.
*/
typedef enum
{
ROCPROFILER_LIBRARY = (1 << 0),
ROCPROFILER_HSA_LIBRARY = (1 << 1),
ROCPROFILER_HIP_LIBRARY = (1 << 2),
ROCPROFILER_MARKER_LIBRARY = (1 << 3),
ROCPROFILER_LIBRARY_LAST = ROCPROFILER_MARKER_LIBRARY,
} rocprofiler_internal_thread_library_t;
/**
* @brief Callback type before and after internal thread creation. @see
* rocprofiler_at_internal_thread_create
*
*/
typedef void (*rocprofiler_internal_thread_library_cb_t)(rocprofiler_internal_thread_library_t,
void*);
typedef void (*rocprofiler_internal_thread_library_cb_t)(rocprofiler_runtime_library_t, void*);
/**
* @brief Invoke this function to receive callbacks before and after the creation of an internal
* thread by a library which as invoked on the thread which is creating the internal thread(s).
* Please note that the postcreate callback is guaranteed to be invoked after the underlying
* system call to create a new thread but it does not guarantee that the new thread has been
* started. Please note, that once these callbacks are registered, they cannot be removed so the
* caller is responsible for ignoring these callbacks if they want to ignore them beyond a certain
* point in the application.
*
* Use the @ref rocprofiler_runtime_library_t enumeration for specifying which libraries you want
* callbacks before and after the library creates an internal thread. These callbacks will be
* invoked on the thread that is about to create the new thread (not on the newly created thread).
* In thread-aware tools that wrap pthread_create, this can be used to disable the wrapper before
* the pthread_create invocation and re-enable the wrapper afterwards. In many cases, tools will
* want to ignore the thread(s) created by rocprofiler since these threads do not exist in the
* normal application execution, whereas the internal threads for HSA, HIP, etc. are created in
* normal application execution; however, the HIP, HSA, etc. internal threads are typically
* background threads which just monitor kernel completion and are unlikely to contribute to any
* performance issues. Please note that the postcreate callback is guaranteed to be invoked after
* the underlying system call to create a new thread but it does not guarantee that the new thread
* has been started. Please note, that once these callbacks are registered, they cannot be removed
* so the caller is responsible for ignoring these callbacks if they want to ignore them beyond a
* certain point in the application.
*
* @param [in] precreate Callback invoked immediately before a new internal thread is created
* @param [in] postcreate Callback invoked immediately after a new internal thread is created
@@ -77,6 +70,9 @@ typedef void (*rocprofiler_internal_thread_library_cb_t)(rocprofiler_internal_th
* means the callbacks will be invoked whenever rocprofiler and/or the marker library create
* internal threads but not when the HSA or HIP libraries create internal threads.
* @param [in] data Data shared between callbacks
* @return ::rocprofiler_status_t
* @retval ::ROCPROFILER_STATUS_SUCCESS There are currently no conditions which result in any other
* value, even if internal threads have already been created
*/
rocprofiler_status_t ROCPROFILER_API
rocprofiler_at_internal_thread_create(rocprofiler_internal_thread_library_cb_t precreate,
@@ -100,6 +96,8 @@ typedef struct
*
* @param [in] cb_thread_id User-provided pointer to a @ref rocprofiler_callback_thread_t
* @return ::rocprofiler_status_t
* @retval ::ROCPROFILER_STATUS_SUCCESS Successful thread creation
* @retval ::ROCPROFILER_STATUS_ERROR Failed to create thread
*/
rocprofiler_status_t ROCPROFILER_API
rocprofiler_create_callback_thread(rocprofiler_callback_thread_t* cb_thread_id)
@@ -113,6 +111,12 @@ rocprofiler_create_callback_thread(rocprofiler_callback_thread_t* cb_thread_id)
* @param [in] buffer_id Buffer identifier
* @param [in] cb_thread_id Callback thread identifier via @ref rocprofiler_create_callback_thread
* @return ::rocprofiler_status_t
* @retval ::ROCPROFILER_STATUS_SUCCESS Successful assignment of the delivery thread for the given
* buffer
* @retval ::ROCPROFILER_STATUS_ERROR_THREAD_NOT_FOUND Thread identifier did not match any of the
* threads created by rocprofiler
* @retval ::ROCPROFILER_STATUS_ERROR_BUFFER_NOT_FOUND Buffer identifier did not match any of the
* buffers registered with rocprofiler
*/
rocprofiler_status_t ROCPROFILER_API
rocprofiler_assign_callback_thread(rocprofiler_buffer_id_t buffer_id,
+4 -3
View File
@@ -65,7 +65,7 @@ ROCPROFILER_EXTERN_C_FINI
/** @} */
#include "rocprofiler/agent.h"
#include "rocprofiler/agent_profile.h"
// #include "rocprofiler/agent_profile.h"
#include "rocprofiler/buffer.h"
#include "rocprofiler/buffer_tracing.h"
#include "rocprofiler/callback_tracing.h"
@@ -75,11 +75,12 @@ ROCPROFILER_EXTERN_C_FINI
#include "rocprofiler/external_correlation.h"
#include "rocprofiler/hip.h"
#include "rocprofiler/hsa.h"
#include "rocprofiler/intercept_table.h"
#include "rocprofiler/internal_threading.h"
#include "rocprofiler/marker.h"
// #include "rocprofiler/marker.h"
#include "rocprofiler/pc_sampling.h"
#include "rocprofiler/profile_config.h"
#include "rocprofiler/spm.h"
// #include "rocprofiler/spm.h"
ROCPROFILER_EXTERN_C_INIT