diff --git a/projects/roctracer/inc/roctracer_roctx.h b/projects/roctracer/inc/roctracer_roctx.h index 94cdbe48ab..b333571364 100644 --- a/projects/roctracer/inc/roctracer_roctx.h +++ b/projects/roctracer/inc/roctracer_roctx.h @@ -18,36 +18,26 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -//////////////////////////////////////////////////////////////////////////////// -// -// ROC-TX API -// -// ROC-TX library, Code Annotation API. -// The goal of the implementation is to provide functionality for annotating -// events, code ranges, and resources in applications. -// -//////////////////////////////////////////////////////////////////////////////// +#ifndef ROCTRACER_ROCTX_H_ +#define ROCTRACER_ROCTX_H_ -#ifndef INC_ROCTRACER_ROCTX_H_ -#define INC_ROCTRACER_ROCTX_H_ #include -#ifdef __cplusplus -extern "C" { -#endif // __cplusplus - -// ROC-TX API ID enumeration +/** + * ROCTX API ID enumeration + */ enum roctx_api_id_t { ROCTX_API_ID_roctxMarkA = 0, ROCTX_API_ID_roctxRangePushA = 1, ROCTX_API_ID_roctxRangePop = 2, ROCTX_API_ID_roctxRangeStartA = 3, ROCTX_API_ID_roctxRangeStop = 4, - ROCTX_API_ID_NUMBER, }; -// ROCTX callbacks data type +/** + * ROCTX callbacks data type + */ typedef struct roctx_api_data_s { union { struct { @@ -74,8 +64,4 @@ typedef struct roctx_api_data_s { } args; } roctx_api_data_t; -#ifdef __cplusplus -} // extern "C" block -#endif // __cplusplus - -#endif // INC_ROCTRACER_ROCTX_H_ +#endif /* ROCTRACER_ROCTX_H_ */ diff --git a/projects/roctracer/inc/roctx.h b/projects/roctracer/inc/roctx.h index d0631e4998..79e5bf9cae 100644 --- a/projects/roctracer/inc/roctx.h +++ b/projects/roctracer/inc/roctx.h @@ -18,64 +18,211 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -//////////////////////////////////////////////////////////////////////////////// -// -// ROC-TX API -// -// ROC-TX library, Code Annotation API. -// The goal of the implementation is to provide functionality for annotating -// events, code ranges, and resources in applications. -// -//////////////////////////////////////////////////////////////////////////////// +/** \mainpage ROCTX API Specification + * + * \section introduction Introduction + * ROCTX is a library that implements the AMD code annotation API. It provides + * the support necessary to annotate events and code ranges in applications. + */ -#ifndef INC_ROCTX_H_ -#define INC_ROCTX_H_ +/** + * \file + * ROCTX API interface. + */ + +#ifndef ROCTX_H_ +#define ROCTX_H_ 1 + +/* Placeholder for calling convention and import/export macros */ +#if !defined(ROCTX_CALL) +#define ROCTX_CALL +#endif /* !defined (ROCTX_CALL) */ + +#if !defined(ROCTX_EXPORT_DECORATOR) +#if defined(__GNUC__) +#define ROCTX_EXPORT_DECORATOR __attribute__((visibility("default"))) +#elif defined(_MSC_VER) +#define ROCTX_EXPORT_DECORATOR __declspec(dllexport) +#endif /* defined (_MSC_VER) */ +#endif /* !defined (ROCTX_EXPORT_DECORATOR) */ + +#if !defined(ROCTX_IMPORT_DECORATOR) +#if defined(__GNUC__) +#define ROCTX_IMPORT_DECORATOR +#elif defined(_MSC_VER) +#define ROCTX_IMPORT_DECORATOR __declspec(dllimport) +#endif /* defined (_MSC_VER) */ +#endif /* !defined (ROCTX_IMPORT_DECORATOR) */ + +#define ROCTX_EXPORT ROCTX_EXPORT_DECORATOR ROCTX_CALL +#define ROCTX_IMPORT ROCTX_IMPORT_DECORATOR ROCTX_CALL + +#if !defined(ROCTX) +#if defined(ROCTX_EXPORTS) +#define ROCTX_API ROCTX_EXPORT +#else /* !defined (ROCTX_EXPORTS) */ +#define ROCTX_API ROCTX_IMPORT +#endif /* !defined (ROCTX_EXPORTS) */ +#endif /* !defined (ROCTX) */ #include -#define ROCTX_VERSION_MAJOR 1 -#define ROCTX_VERSION_MINOR 0 - -#ifdef __cplusplus +#if defined(__cplusplus) extern "C" { -#endif // __cplusplus +#endif /* defined(__cplusplus) */ -//////////////////////////////////////////////////////////////////////////////// -// Returning library version -uint32_t roctx_version_major(); -uint32_t roctx_version_minor(); +/** \defgroup symbol_versions_group Symbol Versions + * + * The names used for the shared library versioned symbols. + * + * Every function is annotated with one of the version macros defined in this + * section. Each macro specifies a corresponding symbol version string. After + * dynamically loading the shared library with \p dlopen, the address of each + * function can be obtained using \p dlvsym with the name of the function and + * its corresponding symbol version string. An error will be reported by \p + * dlvsym if the installed library does not support the version for the + * function specified in this version of the interface. + * + * @{ + */ -//////////////////////////////////////////////////////////////////////////////// -// Markers annotating API +/** + * The function was introduced in version 4.1 of the interface and has the + * symbol version string of ``"ROCTX_4.1"``. + */ +#define ROCTX_VERSION_4_1 -// A marker created by given ASCII massage -void roctxMarkA(const char* message); +/** @} */ + +/** \defgroup versioning_group Versioning + * + * Version information about the interface and the associated installed + * library. + * + * @{ + */ + +/** + * The semantic version of the interface following + * [semver.org][semver] rules. + * + * A client that uses this interface is only compatible with the installed + * library if the major version numbers match and the interface minor version + * number is less than or equal to the installed library minor version number. + */ + +/** + * The major version of the interface as a macro so it can be used by the + * preprocessor. + */ +#define ROCTX_VERSION_MAJOR 4 + +/** + * The minor version of the interface as a macro so it can be used by the + * preprocessor. + */ +#define ROCTX_VERSION_MINOR 1 + +/** + * Query the major version of the installed library. + * + * Return the major version of the installed library. This can be used to check + * if it is compatible with this interface version. + * + * \return Returns the major version number. + */ +uint32_t ROCTX_API roctx_version_major() ROCTX_VERSION_4_1; + +/** + * Query the minor version of the installed library. + * + * Return the minor version of the installed library. This can be used to check + * if it is compatible with this interface version. + * + * \return Returns the minor version number. + */ +uint32_t ROCTX_API roctx_version_minor() ROCTX_VERSION_4_1; + +/** @} */ + +/** \defgroup marker_group ROCTX Markers + * + * Marker annotations are used to describe events in a ROCm application. + * + * @{ + */ + +/** + * Mark an event. + * + * \param[in] message The message associated with the event. + */ +void ROCTX_API roctxMarkA(const char* message) ROCTX_VERSION_4_1; #define roctxMark(message) roctxMarkA(message) -//////////////////////////////////////////////////////////////////////////////// -// Ranges annotating API +/** @} */ -// Returns the 0 based level of a nested range being started by given message associated to this -// range. A negative value is returned on the error. -int roctxRangePushA(const char* message); +/** \defgroup range_group ROCTX Ranges + * + * Range annotations are used to describe events in a ROCm application. + * + * @{ + */ + +/** + * Start a new nested range. + * + * Nested ranges are stacked and local to the current CPU thread. + * + * \param[in] message The message associated with this range. + * + * \return Returns the level this nested range is started at. Nested range + * levels are 0 based. + */ +int ROCTX_API roctxRangePushA(const char* message) ROCTX_VERSION_4_1; #define roctxRangePush(message) roctxRangePushA(message) -// Marks the end of a nested range. -// A negative value is returned on the error. -int roctxRangePop(); +/** + * Stop the current nested range. + * + * Stop the current nested range, and pop it from the stack. If a nested range + * was active before the last one was started, it becomes again the current + * nested range. + * + * \return Returns the level the stopped nested range was started at, or a + * negative value if there was no nested range active. + */ +int ROCTX_API roctxRangePop() ROCTX_VERSION_4_1; -// ROCTX range id type +/** + * ROCTX range ID. + * + * This is the range ID used to identify start/end ranges. + */ typedef uint64_t roctx_range_id_t; -// Starts a process range -roctx_range_id_t roctxRangeStartA(const char* message); +/** + * Starts a process range. + * + * Start/stop ranges can be started and stopped in different threads. Each + * timespan is assigned a unique range ID. + * + * \param[in] message The message associated with this range. + * + * \return Returns the ID of the new range. + */ +roctx_range_id_t ROCTX_API roctxRangeStartA(const char* message) ROCTX_VERSION_4_1; #define roctxRangeStart(message) roctxRangeStartA(message) -// Stop a process range -void roctxRangeStop(roctx_range_id_t id); +/** + * Stop a process range. + */ +void ROCTX_API roctxRangeStop(roctx_range_id_t id) ROCTX_VERSION_4_1; -#ifdef __cplusplus -} // extern "C" block -#endif // __cplusplus +/** @} */ -#endif // INC_ROCTX_H_ +#if defined(__cplusplus) +} /* extern "C" */ +#endif /* defined (__cplusplus) */ + +#endif /* ROCTX_H_ */ diff --git a/projects/roctracer/src/CMakeLists.txt b/projects/roctracer/src/CMakeLists.txt index 2b1941d874..404df0b125 100644 --- a/projects/roctracer/src/CMakeLists.txt +++ b/projects/roctracer/src/CMakeLists.txt @@ -123,7 +123,8 @@ add_library(roctracer ${LIBRARY_TYPE} ${ROCTRACER_SOURCES} ${GENERATED_HEADERS}) set_target_properties(roctracer PROPERTIES CXX_VISIBILITY_PRESET hidden OUTPUT_NAME "roctracer64" - LINK_DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/roctracer.exportmap + DEFINE_SYMBOL "ROCTRACER_EXPORTS" + LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/roctracer/exportmap VERSION ${ROCTRACER_VERSION} SOVERSION ${ROCTRACER_VERSION_MAJOR}) @@ -139,8 +140,7 @@ target_include_directories(roctracer ${CMAKE_CURRENT_SOURCE_DIR}/roctracer ${CMAKE_CURRENT_SOURCE_DIR} ${PROJECT_SOURCE_DIR}/inc) -configure_file(roctracer/exportmap.in roctracer.exportmap @ONLY) -target_link_options(roctracer PRIVATE -Wl,--version-script=${CMAKE_CURRENT_BINARY_DIR}/roctracer.exportmap -Wl,--no-undefined) +target_link_options(roctracer PRIVATE -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/roctracer/exportmap -Wl,--no-undefined) target_link_libraries(roctracer PRIVATE hsa-runtime64::hsa-runtime64 Threads::Threads dl) install(TARGETS roctracer LIBRARY DESTINATION lib) @@ -152,15 +152,15 @@ add_library(roctx ${LIBRARY_TYPE} ${ROCTX_SOURCES}) set_target_properties(roctx PROPERTIES CXX_VISIBILITY_PRESET hidden OUTPUT_NAME "roctx64" - LINK_DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/roctx.exportmap + DEFINE_SYMBOL "ROCTX_EXPORTS" + LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/roctx/exportmap VERSION ${ROCTRACER_VERSION} SOVERSION ${ROCTRACER_VERSION_MAJOR}) target_include_directories(roctx PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/roctracer ${CMAKE_CURRENT_SOURCE_DIR} ${PROJECT_SOURCE_DIR}/inc) -configure_file(roctx/exportmap.in roctx.exportmap @ONLY) -target_link_options(roctx PRIVATE -Wl,--version-script=roctx.exportmap -Wl,--no-undefined) +target_link_options(roctx PRIVATE -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/roctx/exportmap -Wl,--no-undefined) install(TARGETS roctx LIBRARY DESTINATION lib) diff --git a/projects/roctracer/src/roctracer/exportmap.in b/projects/roctracer/src/roctracer/exportmap similarity index 98% rename from projects/roctracer/src/roctracer/exportmap.in rename to projects/roctracer/src/roctracer/exportmap index e6bc458db6..9571c113a0 100644 --- a/projects/roctracer/src/roctracer/exportmap.in +++ b/projects/roctracer/src/roctracer/exportmap @@ -1,4 +1,4 @@ -@CMAKE_PROJECT_NAME@_4.1 { +ROCTRACER_4.1 { global: OnLoad; OnUnload; roctracer_activity_pop_external_correlation_id; diff --git a/projects/roctracer/src/roctx/exportmap.in b/projects/roctracer/src/roctx/exportmap similarity index 90% rename from projects/roctracer/src/roctx/exportmap.in rename to projects/roctracer/src/roctx/exportmap index 0243bfdd8a..de57516313 100644 --- a/projects/roctracer/src/roctx/exportmap.in +++ b/projects/roctracer/src/roctx/exportmap @@ -1,4 +1,4 @@ -@CMAKE_PROJECT_NAME@_4.1 { +ROCTX_4.1 { global: RegisterApiCallback; RemoveApiCallback; roctxMarkA; diff --git a/projects/roctracer/src/roctx/roctx.cpp b/projects/roctracer/src/roctx/roctx.cpp index b2aa76a38b..988c2a55b9 100644 --- a/projects/roctracer/src/roctx/roctx.cpp +++ b/projects/roctracer/src/roctx/roctx.cpp @@ -22,113 +22,63 @@ #include "roctracer_roctx.h" #include "ext/prof_protocol.h" -#include - #include "callback_table.h" -#include "util/exception.h" -#include "util/logger.h" -#define PUBLIC_API __attribute__((visibility("default"))) - -#define API_METHOD_PREFIX try { -#define API_METHOD_SUFFIX_NRET \ - } \ - catch (const std::exception& e) { \ - ERR_LOGGING(__FUNCTION__ << "(), " << e.what()); \ - } - -#define API_METHOD_CATCH(X) \ - } \ - catch (const std::exception& e) { \ - ERR_LOGGING(__FUNCTION__ << "(), " << e.what()); \ - return X; \ - } \ - assert(false && "should not reach here"); - -//////////////////////////////////////////////////////////////////////////////// -// Library errors enumeration -typedef enum { - ROCTX_STATUS_SUCCESS = 0, - ROCTX_STATUS_ERROR = 1, -} roctx_status_t; - -/////////////////////////////////////////////////////////////////////////////////////////////////// -// Library implementation -// namespace { roctracer::CallbackTable callbacks; -thread_local int range_level(0); +thread_local int nested_range_level(0); } // namespace -// Logger instantiation -roctracer::util::Logger::mutex_t roctracer::util::Logger::mutex_; -std::atomic roctracer::util::Logger::instance_{}; +uint32_t ROCTX_API roctx_version_major() { return ROCTX_VERSION_MAJOR; } +uint32_t ROCTX_API roctx_version_minor() { return ROCTX_VERSION_MINOR; } -/////////////////////////////////////////////////////////////////////////////////////////////////// -// Public library methods -// - -PUBLIC_API uint32_t roctx_version_major() { return ROCTX_VERSION_MAJOR; } -PUBLIC_API uint32_t roctx_version_minor() { return ROCTX_VERSION_MINOR; } - -PUBLIC_API void roctxMarkA(const char* message) { - API_METHOD_PREFIX +void ROCTX_API roctxMarkA(const char* message) { roctx_api_data_t api_data{}; api_data.args.roctxMarkA.message = message; callbacks.Invoke(ROCTX_API_ID_roctxMarkA, &api_data); - API_METHOD_SUFFIX_NRET } -PUBLIC_API int roctxRangePushA(const char* message) { - API_METHOD_PREFIX +int ROCTX_API roctxRangePushA(const char* message) { roctx_api_data_t api_data{}; api_data.args.roctxRangePushA.message = message; callbacks.Invoke(ROCTX_API_ID_roctxRangePushA, &api_data); - return range_level++; - API_METHOD_CATCH(-1); + return nested_range_level++; } -PUBLIC_API int roctxRangePop() { - API_METHOD_PREFIX - +int ROCTX_API roctxRangePop() { roctx_api_data_t api_data{}; callbacks.Invoke(ROCTX_API_ID_roctxRangePop, &api_data); - if (range_level == 0) EXC_RAISING(ROCTX_STATUS_ERROR, "Pop from empty stack!"); - return --range_level; - API_METHOD_CATCH(-1) + if (nested_range_level == 0) return -1; + return --nested_range_level; } -PUBLIC_API roctx_range_id_t roctxRangeStartA(const char* message) { - API_METHOD_PREFIX - static std::atomic roctx_range_counter(1); +roctx_range_id_t ROCTX_API roctxRangeStartA(const char* message) { + static std::atomic start_stop_range_id(1); roctx_api_data_t api_data{}; api_data.args.roctxRangeStartA.message = message; callbacks.Invoke(ROCTX_API_ID_roctxRangeStartA, &api_data); - return roctx_range_counter++; - API_METHOD_CATCH(-1) + return start_stop_range_id++; } -PUBLIC_API void roctxRangeStop(roctx_range_id_t rangeId) { - API_METHOD_PREFIX +void ROCTX_API roctxRangeStop(roctx_range_id_t rangeId) { roctx_api_data_t api_data{}; api_data.args.roctxRangeStop.id = rangeId; callbacks.Invoke(ROCTX_API_ID_roctxRangeStop, &api_data); - API_METHOD_SUFFIX_NRET } -extern "C" PUBLIC_API bool RegisterApiCallback(uint32_t op, void* callback, void* arg) { +extern "C" bool ROCTX_EXPORT RegisterApiCallback(uint32_t op, void* callback, void* arg) { if (op >= ROCTX_API_ID_NUMBER) return false; callbacks.Set(op, reinterpret_cast(callback), arg); return true; } -extern "C" PUBLIC_API bool RemoveApiCallback(uint32_t op) { +extern "C" bool ROCTX_EXPORT RemoveApiCallback(uint32_t op) { if (op >= ROCTX_API_ID_NUMBER) return false; callbacks.Set(op, nullptr, nullptr); return true; diff --git a/projects/roctracer/test/CMakeLists.txt b/projects/roctracer/test/CMakeLists.txt index bbdcb0c7fc..daf4a97954 100644 --- a/projects/roctracer/test/CMakeLists.txt +++ b/projects/roctracer/test/CMakeLists.txt @@ -113,4 +113,4 @@ configure_file(${PROJECT_SOURCE_DIR}/script/check_trace.py ${PROJECT_BINARY_DIR} file(GLOB files RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} "golden_traces/tests_trace_cmp_levels.txt" "golden_traces/*_trace.txt") foreach(file ${files}) configure_file(${file} ${PROJECT_BINARY_DIR}/test/${file} COPYONLY) -endforeach() \ No newline at end of file +endforeach()