Fix release docs workflow + update documentation (#216)
* Fix release-docs workflow
* Documentation updates
- warning as errors when building docs
- fixed warnings when building docs
- fixed doxygen comments
* Miscellaneous fixes
* Fix doxygen comments
[ROCm/rocprofiler-systems commit: 7ecc037d17]
이 커밋은 다음에 포함됨:
Jonathan R. Madsen
GitHub
@@ -87,10 +87,11 @@ extern "C"
|
||||
// be the last enumerated id
|
||||
} omnitrace_category_t;
|
||||
|
||||
/// @typedef omnitrace_annotation_type_t
|
||||
/// @enum OMNITRACE_ANNOTATION_TYPE
|
||||
/// @brief Identifier for the data type of the annotation.
|
||||
/// if the data type is not a pointer, pass the address of
|
||||
/// data.
|
||||
/// @typedef OMNITRACE_ANNOTATION_TYPE omnitrace_annotation_type_t
|
||||
typedef enum OMNITRACE_ANNOTATION_TYPE
|
||||
{
|
||||
// Do not use first enum value
|
||||
@@ -134,15 +135,13 @@ extern "C"
|
||||
OMNITRACE_VALUE_LAST
|
||||
} omnitrace_annotation_type_t;
|
||||
|
||||
/// @typedef omnitrace_annotation
|
||||
/// @struct omnitrace_annotation
|
||||
/// @brief A struct containing annotation data to be included in the perfetto trace.
|
||||
///
|
||||
/// @code{.cpp}
|
||||
/// #include <cstddef>
|
||||
/// #include <cstdint>
|
||||
///
|
||||
/// #include <omnitrace/user.h>
|
||||
///
|
||||
/// double
|
||||
/// compute_residual(size_t n, double* data);
|
||||
///
|
||||
@@ -173,12 +172,15 @@ extern "C"
|
||||
/// return residual;
|
||||
/// }
|
||||
/// @endcode
|
||||
///
|
||||
/// @typedef omnitrace_annotation omnitrace_annotation_t
|
||||
typedef struct omnitrace_annotation
|
||||
{
|
||||
/// label for annotation
|
||||
const char* name;
|
||||
uintptr_t type;
|
||||
void* value;
|
||||
/// omnitrace_annotation_type_t
|
||||
uintptr_t type;
|
||||
/// data to annotate
|
||||
void* value;
|
||||
} omnitrace_annotation_t;
|
||||
|
||||
#if defined(__cplusplus)
|
||||
|
||||
@@ -37,45 +37,10 @@ extern "C"
|
||||
typedef int (*omnitrace_annotated_region_func_t)(const char*, omnitrace_annotation*,
|
||||
size_t);
|
||||
|
||||
/// @typedef omnitrace_user_callbacks_t
|
||||
/// @struct omnitrace_user_callbacks
|
||||
/// @brief Struct containing the callbacks for the user API
|
||||
/// @code{.cpp}
|
||||
///
|
||||
/// #include <cerrno>
|
||||
/// #include <cstring>
|
||||
///
|
||||
/// omnitrace_user_callbacks_t custom_callbacks = OMNITRACE_USER_CALLBACKS_INIT;
|
||||
/// omnitrace_user_callbacks_t original_callbacks = OMNITRACE_USER_CALLBACKS_INIT;
|
||||
///
|
||||
/// // in our custom push region, we are going to redirect the unannotated user push
|
||||
/// // region to annotate the trace entries with the global errno and if errno is
|
||||
/// // non-zero, store the message
|
||||
/// int
|
||||
/// custom_push_region(const char* name)
|
||||
/// {
|
||||
/// if(!original_callbacks.push_annotated_region)
|
||||
/// return OMNITRACE_USER_ERROR_NO_BINDING;
|
||||
///
|
||||
/// int32_t _err = errno;
|
||||
/// const char* _msg = nullptr;
|
||||
/// char _buff[1024];
|
||||
/// if(_err != 0) _msg = strerror_r(_err, _buff, sizeof(_buff));
|
||||
///
|
||||
/// omnitrace_annotation_t _annotates[] = { { "errno", OMNITRACE_INT32, &_err },
|
||||
/// { "msg", OMNITRACE_STRING, _msg } };
|
||||
/// return (*original_callbacks.push_annotated_region)(name, &_annotations, 2);
|
||||
/// }
|
||||
///
|
||||
/// int
|
||||
/// main(int argc, char** argv)
|
||||
/// {
|
||||
/// custom_callbacks.push_region = &custom_push_region;
|
||||
/// omnitrace_user_configure(OMNITRACE_USER_UNION_CONFIG, custom_callbacks,
|
||||
/// &original_callbacks);
|
||||
/// // ...
|
||||
/// }
|
||||
///
|
||||
/// @endcode
|
||||
/// @typedef omnitrace_user_callbacks omnitrace_user_callbacks_t
|
||||
typedef struct omnitrace_user_callbacks
|
||||
{
|
||||
omnitrace_trace_func_t start_trace;
|
||||
@@ -86,11 +51,28 @@ extern "C"
|
||||
omnitrace_region_func_t pop_region;
|
||||
omnitrace_annotated_region_func_t push_annotated_region;
|
||||
omnitrace_annotated_region_func_t pop_annotated_region;
|
||||
|
||||
/// @var start_trace
|
||||
/// @brief callback for enabling tracing globally
|
||||
/// @var stop_trace
|
||||
/// @brief callback for disabling tracing globally
|
||||
/// @var start_thread_trace
|
||||
/// @brief callback for enabling tracing on current thread
|
||||
/// @var stop_thread_trace
|
||||
/// @brief callback for disabling tracing on current thread
|
||||
/// @var push_region
|
||||
/// @brief callback for starting a trace region
|
||||
/// @var pop_region
|
||||
/// @brief callback for ending a trace region
|
||||
/// @var push_annotated_region
|
||||
/// @brief callback for starting a trace region + annotations
|
||||
/// @var pop_annotated_region
|
||||
/// @brief callback for ending a trace region + annotations
|
||||
} omnitrace_user_callbacks_t;
|
||||
|
||||
/// @typedef omnitrace_user_configure_mode_t
|
||||
/// @enum OMNITRACE_USER_CONFIGURE_MODE
|
||||
/// @brief Identifier for errors
|
||||
///
|
||||
/// @typedef OMNITRACE_USER_CONFIGURE_MODE omnitrace_user_configure_mode_t
|
||||
typedef enum OMNITRACE_USER_CONFIGURE_MODE
|
||||
{
|
||||
// clang-format off
|
||||
@@ -101,8 +83,9 @@ extern "C"
|
||||
// clang-format on
|
||||
} omnitrace_user_configure_mode_t;
|
||||
|
||||
/// @typedef omnitrace_user_error_t
|
||||
/// @enum OMNITRACE_USER_ERROR
|
||||
/// @brief Identifier for errors
|
||||
/// @typedef OMNITRACE_USER_ERROR omnitrace_user_error_t
|
||||
///
|
||||
typedef enum OMNITRACE_USER_ERROR
|
||||
{
|
||||
|
||||
@@ -42,36 +42,36 @@ extern "C"
|
||||
#endif
|
||||
|
||||
/// @fn int omnitrace_user_start_trace(void)
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return omnitrace_user_error_t value
|
||||
/// @brief Enable tracing on this thread and all subsequently created threads
|
||||
extern int omnitrace_user_start_trace(void) OMNITRACE_PUBLIC_API;
|
||||
|
||||
/// @fn int omnitrace_user_stop_trace(void)
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return omnitrace_user_error_t value
|
||||
/// @brief Disable tracing on this thread and all subsequently created threads
|
||||
extern int omnitrace_user_stop_trace(void) OMNITRACE_PUBLIC_API;
|
||||
|
||||
/// @fn int omnitrace_user_start_thread_trace(void)
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return omnitrace_user_error_t value
|
||||
/// @brief Enable tracing on this specific thread. Does not apply to subsequently
|
||||
/// created threads
|
||||
extern int omnitrace_user_start_thread_trace(void) OMNITRACE_PUBLIC_API;
|
||||
|
||||
/// @fn int omnitrace_user_stop_thread_trace(void)
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return omnitrace_user_error_t value
|
||||
/// @brief Disable tracing on this specific thread. Does not apply to subsequently
|
||||
/// created threads
|
||||
extern int omnitrace_user_stop_thread_trace(void) OMNITRACE_PUBLIC_API;
|
||||
|
||||
/// @fn int omnitrace_user_push_region(const char* id)
|
||||
/// @param id The string identifier for the region
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return omnitrace_user_error_t value
|
||||
/// @brief Start a user defined region.
|
||||
extern int omnitrace_user_push_region(const char*) OMNITRACE_PUBLIC_API;
|
||||
|
||||
/// @fn int omnitrace_user_pop_region(const char* id)
|
||||
/// @param id The string identifier for the region
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return omnitrace_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
|
||||
@@ -80,13 +80,15 @@ extern "C"
|
||||
/// results in timemory vs. perfetto.
|
||||
extern int omnitrace_user_pop_region(const char*) OMNITRACE_PUBLIC_API;
|
||||
|
||||
/// @typedef omnitrace_annotation omnitrace_annotation_t
|
||||
///
|
||||
/// @fn int omnitrace_user_push_annotated_region(const char* id,
|
||||
/// omnitrace_annotation_t* annotations,
|
||||
/// size_t num_annotations)
|
||||
/// @param id The string identifier for the region
|
||||
/// @param annotations Array of @ref omnitrace_annotation_t instances
|
||||
/// @param annotations Array of @ref omnitrace_annotation instances
|
||||
/// @param num_annotations Number of annotations
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return omnitrace_user_error_t value
|
||||
/// @brief Start a user defined region and adds the annotations to the perfetto trace.
|
||||
extern int omnitrace_user_push_annotated_region(const char*, omnitrace_annotation_t*,
|
||||
size_t) OMNITRACE_PUBLIC_API;
|
||||
@@ -95,23 +97,23 @@ extern "C"
|
||||
/// omnitrace_annotation_t* annotations,
|
||||
/// size_t num_annotations)
|
||||
/// @param id The string identifier for the region
|
||||
/// @param annotations Array of @ref omnitrace_annotation_t instances
|
||||
/// @param annotations Array of @ref omnitrace_annotation instances
|
||||
/// @param num_annotations Number of annotations
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return omnitrace_user_error_t value
|
||||
/// @brief Stop a user defined region and adds the annotations to the perfetto trace.
|
||||
extern int omnitrace_user_pop_annotated_region(const char*, omnitrace_annotation_t*,
|
||||
size_t) OMNITRACE_PUBLIC_API;
|
||||
|
||||
/// @fn int omnitrace_user_configure(omnitrace_user_configure_mode_t cfg,
|
||||
/// omnitrace_user_callbacks_t new_callbacks,
|
||||
/// omnitrace_user_callbacks_t* old_callbacks)
|
||||
/// @param[in] config Specifies how the new callbacks are merged with the old
|
||||
/// @fn int omnitrace_user_configure(omnitrace_user_configure_mode_t mode,
|
||||
/// omnitrace_user_callbacks_t inp,
|
||||
/// omnitrace_user_callbacks_t* out)
|
||||
/// @param[in] mode Specifies how the new callbacks are merged with the old
|
||||
/// callbacks
|
||||
/// @param[in] new_callbacks An @ref omnitrace_user_callbacks_t instance specifying
|
||||
/// @param[in] inp An @ref omnitrace_user_callbacks instance specifying
|
||||
/// the callbacks which should be invoked by the user API.
|
||||
/// @param[out] old_callbacks Pointer to @ref omnitrace_user_callbacks_t which,
|
||||
/// @param[out] out Pointer to @ref omnitrace_user_callbacks which,
|
||||
/// when non-NULL, will be assigned the former callbacks.
|
||||
/// @return @ref omnitrace_user_error_t value
|
||||
/// @return omnitrace_user_error_t value
|
||||
/// @brief Configure the function pointers invoked by the omnitrace user API.
|
||||
/// The initial callbacks are set via the omnitrace-dl library when it is loaded but
|
||||
/// the user can user this feature to turn on/off the user API or customize how the
|
||||
@@ -120,8 +122,8 @@ extern "C"
|
||||
/// regions to the annotated user regions with annotations about some global state.
|
||||
/// Changing the callbacks is thread-safe but not thread-local.
|
||||
extern int omnitrace_user_configure(
|
||||
omnitrace_user_configure_mode_t, omnitrace_user_callbacks_t new_callbacks,
|
||||
omnitrace_user_callbacks_t* old_callbacks) OMNITRACE_PUBLIC_API;
|
||||
omnitrace_user_configure_mode_t mode, omnitrace_user_callbacks_t inp,
|
||||
omnitrace_user_callbacks_t* out) OMNITRACE_PUBLIC_API;
|
||||
|
||||
/// @fn int omnitrace_user_get_callbacks(int category, void** begin_func, void**
|
||||
/// end_func)
|
||||
@@ -130,7 +132,7 @@ extern "C"
|
||||
/// the category, e.g. omnitrace_user_start_trace or omnitrace_user_push_region
|
||||
/// @param[out] end_func The pointer to the function which corresponds to "ending" the
|
||||
/// category, e.g. omnitrace_user_stop_trace or omnitrace_user_pop_region
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return omnitrace_user_error_t value
|
||||
/// @brief Get the current function pointers for a given category. The initial values
|
||||
/// are assigned by omnitrace-dl at start up.
|
||||
extern int omnitrace_user_get_callbacks(omnitrace_user_callbacks_t*)
|
||||
@@ -138,7 +140,7 @@ extern "C"
|
||||
|
||||
/// @fn const char* omnitrace_user_error_string(int error_category)
|
||||
/// @param error_category OMNITRACE_USER_ERROR value
|
||||
/// @return @ref OMNITRACE_USER_ERROR value
|
||||
/// @return String descripting the error code
|
||||
/// @brief Return a descriptor for the provided error code
|
||||
extern const char* omnitrace_user_error_string(int) OMNITRACE_PUBLIC_API;
|
||||
|
||||
|
||||
@@ -94,17 +94,17 @@ extern "C"
|
||||
_annotation_count);
|
||||
}
|
||||
|
||||
int omnitrace_user_configure(omnitrace_user_configure_mode_t _mode,
|
||||
omnitrace_user_callbacks_t _inp,
|
||||
omnitrace_user_callbacks_t* _out)
|
||||
int omnitrace_user_configure(omnitrace_user_configure_mode_t mode,
|
||||
omnitrace_user_callbacks_t inp,
|
||||
omnitrace_user_callbacks_t* out)
|
||||
{
|
||||
auto _former = _callbacks;
|
||||
|
||||
switch(_mode)
|
||||
switch(mode)
|
||||
{
|
||||
case OMNITRACE_USER_REPLACE_CONFIG:
|
||||
{
|
||||
_callbacks = _inp;
|
||||
_callbacks = inp;
|
||||
break;
|
||||
}
|
||||
case OMNITRACE_USER_UNION_CONFIG:
|
||||
@@ -115,14 +115,14 @@ extern "C"
|
||||
|
||||
user_callbacks_t _v = _callbacks;
|
||||
|
||||
_update(_v.start_trace, _inp.start_trace);
|
||||
_update(_v.stop_trace, _inp.stop_trace);
|
||||
_update(_v.start_thread_trace, _inp.start_thread_trace);
|
||||
_update(_v.stop_thread_trace, _inp.stop_thread_trace);
|
||||
_update(_v.push_region, _inp.push_region);
|
||||
_update(_v.pop_region, _inp.pop_region);
|
||||
_update(_v.push_annotated_region, _inp.push_annotated_region);
|
||||
_update(_v.pop_annotated_region, _inp.pop_annotated_region);
|
||||
_update(_v.start_trace, inp.start_trace);
|
||||
_update(_v.stop_trace, inp.stop_trace);
|
||||
_update(_v.start_thread_trace, inp.start_thread_trace);
|
||||
_update(_v.stop_thread_trace, inp.stop_thread_trace);
|
||||
_update(_v.push_region, inp.push_region);
|
||||
_update(_v.pop_region, inp.pop_region);
|
||||
_update(_v.push_annotated_region, inp.push_annotated_region);
|
||||
_update(_v.pop_annotated_region, inp.pop_annotated_region);
|
||||
|
||||
_callbacks = _v;
|
||||
break;
|
||||
@@ -135,26 +135,26 @@ extern "C"
|
||||
|
||||
user_callbacks_t _v = _callbacks;
|
||||
|
||||
_update(_v.start_trace, _inp.start_trace);
|
||||
_update(_v.stop_trace, _inp.stop_trace);
|
||||
_update(_v.start_thread_trace, _inp.start_thread_trace);
|
||||
_update(_v.stop_thread_trace, _inp.stop_thread_trace);
|
||||
_update(_v.push_region, _inp.push_region);
|
||||
_update(_v.pop_region, _inp.pop_region);
|
||||
_update(_v.push_annotated_region, _inp.push_annotated_region);
|
||||
_update(_v.pop_annotated_region, _inp.pop_annotated_region);
|
||||
_update(_v.start_trace, inp.start_trace);
|
||||
_update(_v.stop_trace, inp.stop_trace);
|
||||
_update(_v.start_thread_trace, inp.start_thread_trace);
|
||||
_update(_v.stop_thread_trace, inp.stop_thread_trace);
|
||||
_update(_v.push_region, inp.push_region);
|
||||
_update(_v.pop_region, inp.pop_region);
|
||||
_update(_v.push_annotated_region, inp.push_annotated_region);
|
||||
_update(_v.pop_annotated_region, inp.pop_annotated_region);
|
||||
|
||||
_callbacks = _v;
|
||||
break;
|
||||
}
|
||||
default:
|
||||
{
|
||||
if(_out) *_out = _former;
|
||||
if(out) *out = _former;
|
||||
return OMNITRACE_USER_ERROR_INVALID_CATEGORY;
|
||||
}
|
||||
}
|
||||
|
||||
if(_out) *_out = _former;
|
||||
if(out) *out = _former;
|
||||
|
||||
return OMNITRACE_USER_SUCCESS;
|
||||
}
|
||||
|
||||
새 이슈에서 참조
사용자 차단