Document the ROCTX API
Change-Id: I63a04139d1640ea5d52f6143cf2e9bfc0614a894
This commit is contained in:
Laurent Morichetti
zatwierdzone przez
Laurent Morichetti
Laurent Morichetti
rodzic
7a47505744
commit
7ebae10571
@@ -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 <roctx.h>
|
||||
|
||||
#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_ */
|
||||
|
||||
+188
-41
@@ -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 <stdint.h>
|
||||
|
||||
#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_ */
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
@CMAKE_PROJECT_NAME@_4.1 {
|
||||
ROCTRACER_4.1 {
|
||||
global: OnLoad;
|
||||
OnUnload;
|
||||
roctracer_activity_pop_external_correlation_id;
|
||||
@@ -1,4 +1,4 @@
|
||||
@CMAKE_PROJECT_NAME@_4.1 {
|
||||
ROCTX_4.1 {
|
||||
global: RegisterApiCallback;
|
||||
RemoveApiCallback;
|
||||
roctxMarkA;
|
||||
+15
-65
@@ -22,113 +22,63 @@
|
||||
#include "roctracer_roctx.h"
|
||||
#include "ext/prof_protocol.h"
|
||||
|
||||
#include <cassert>
|
||||
|
||||
#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<ACTIVITY_DOMAIN_ROCTX, ROCTX_API_ID_NUMBER> 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*> 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_id_t> roctx_range_counter(1);
|
||||
roctx_range_id_t ROCTX_API roctxRangeStartA(const char* message) {
|
||||
static std::atomic<roctx_range_id_t> 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<activity_rtapi_callback_t>(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;
|
||||
|
||||
@@ -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()
|
||||
endforeach()
|
||||
|
||||
Reference in New Issue
Block a user