diff --git a/tracetools/.gitignore b/tracetools/.gitignore new file mode 100644 index 0000000..90b0816 --- /dev/null +++ b/tracetools/.gitignore @@ -0,0 +1 @@ +doc_output/ diff --git a/tracetools/Doxyfile b/tracetools/Doxyfile new file mode 100644 index 0000000..8ba3973 --- /dev/null +++ b/tracetools/Doxyfile @@ -0,0 +1,32 @@ +# All settings not listed here will use the Doxygen default values. +# To use, see: https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing-api + +PROJECT_NAME = "tracetools" +PROJECT_NUMBER = $(PROJECT_NUMBER) +PROJECT_BRIEF = "Tracing tools and instrumentation for ROS 2" + +INPUT = ./include + +RECURSIVE = YES +OUTPUT_DIRECTORY = doc_output + +EXTRACT_ALL = YES +SORT_MEMBER_DOCS = NO + +GENERATE_LATEX = NO + +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = NO +PREDEFINED = \ + "TRACETOOLS_PUBLIC=" + +EXCLUDE_SYMBOLS = \ + "DECLARE_TRACEPOINT" \ + "_demangle_symbol" \ + "_get_symbol_funcptr" + +# Tag files that do not exist will produce a warning and cross-project linking will not work. +TAGFILES += "../../../data/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/" +# Uncomment to generate tag files for cross-project linking. +GENERATE_TAGFILE = "../../../data/tracetools.tag" diff --git a/tracetools/include/tracetools/tracetools.h b/tracetools/include/tracetools/tracetools.h index 79b60e5..79dabb4 100644 --- a/tracetools/include/tracetools/tracetools.h +++ b/tracetools/include/tracetools/tracetools.h @@ -12,6 +12,17 @@ // See the License for the specific language governing permissions and // limitations under the License. +/** \mainpage tracetools: tracing tools and instrumentation for ROS 2 + * + * `tracetools` provides utilities to instrument ROS. + * It provides two main headers: + * + * - tracetools/tracetools.h + * - instrumentation functions + * - tracetools/utils.hpp + * - utility functions + */ + #ifndef TRACETOOLS__TRACETOOLS_H_ #define TRACETOOLS__TRACETOOLS_H_ @@ -22,10 +33,14 @@ #include "tracetools/visibility_control.hpp" #ifndef TRACETOOLS_DISABLED +/// Call a tracepoint. +/** + * This is the preferred method over calling the actual function directly. + */ # define TRACEPOINT(event_name, ...) \ (ros_trace_ ## event_name)(__VA_ARGS__) # define DECLARE_TRACEPOINT(event_name, ...) \ - TRACETOOLS_PUBLIC void(ros_trace_ ## event_name)(__VA_ARGS__); + TRACETOOLS_PUBLIC void ros_trace_ ## event_name(__VA_ARGS__); #else # define TRACEPOINT(event_name, ...) ((void) (0)) # define DECLARE_TRACEPOINT(event_name, ...) @@ -36,20 +51,32 @@ extern "C" { #endif +/// Get tracing compilation status. /** - * Report whether tracing is compiled in + * \return `true` if tracing is enabled, `false` otherwise */ TRACETOOLS_PUBLIC bool ros_trace_compile_status(); +/// `rcl_init` /** - * tp: rcl_init + * Initialisation for the whole process. + * Notes the `tracetools` version automatically. + * + * \param[in] context_handle pointer to the `rcl_context_t` handle */ DECLARE_TRACEPOINT( rcl_init, const void * context_handle) +/// `rcl_node_init` /** - * tp: rcl_node_init + * Node initialisation. + * Links a `rcl_node_t` handle to its `rmw_node_t` handle. + * + * \param[in] node_handle pointer to the node's `rcl_node_t` handle + * \param[in] rmw_handle pointer to the node's `rmw_node_t` handle + * \param[in] node_name node name + * \param[in] node_namespace node namespace */ DECLARE_TRACEPOINT( rcl_node_init, @@ -58,8 +85,17 @@ DECLARE_TRACEPOINT( const char * node_name, const char * node_namespace) +/// `rcl_publisher_init` /** - * tp: rcl_publisher_init + * Publisher initialisation. + * Links a `rcl_publisher_t` handle to its `rcl_node_t` handle + * and its `rmw_publisher_t` handle, and links it to a topic name. + * + * \param[in] publisher_handle pointer to the publisher's `rcl_publisher_t` handle + * \param[in] node_handle pointer to the `rcl_node_t` handle of the node the publisher belongs to + * \param[in] rmw_publisher_handle pointer to the publisher's `rmw_publisher_t` handle + * \param[in] topic_name full topic name + * \param[in] queue_depth publisher history depth */ DECLARE_TRACEPOINT( rcl_publisher_init, @@ -69,8 +105,18 @@ DECLARE_TRACEPOINT( const char * topic_name, const size_t queue_depth) +/// `rcl_subscription_init` /** - * tp: rcl_subscription_init + * Subscription initialisation. + * Links a `rcl_subscription_t` handle to its `rcl_node_t` handle + * and its `rmw_subscription_t` handle, and links it to a topic name. + * + * \param[in] subscription_handle pointer to the subscription's `rcl_subscription_t` handle + * \param[in] node_handle + * pointer to the `rcl_node_t` handle of the node the subscription belongs to + * \param[in] rmw_subscription_handle pointer to the subscription's `rmw_subscription_t` handle + * \param[in] topic_name full topic name + * \param[in] queue_depth subscription history depth */ DECLARE_TRACEPOINT( rcl_subscription_init, @@ -80,24 +126,44 @@ DECLARE_TRACEPOINT( const char * topic_name, const size_t queue_depth) +/// `rclcpp_subscription_init` /** - * tp: rclcpp_subscription_init + * Subscription object initialisation. + * Links the `rclcpp::*Subscription*` object to a `rcl_subscription_t` handle. + * Needed since there could be more than 1 `rclcpp::*Subscription*` object + * for one `rcl` subscription (e.g. when using intra-process). + * + * \param[in] subscription_handle + * pointer to the `rcl_subscription_t` handle of the subscription this object belongs to + * \param[in] subscription pointer to this subscription object (e.g. `rclcpp::*Subscription*`) */ DECLARE_TRACEPOINT( rclcpp_subscription_init, const void * subscription_handle, const void * subscription) +/// `rclcpp_subscription_callback_added` /** - * tp: rclcpp_subscription_callback_added + * Link a subscription callback object to a subscription object. + * + * \param[in] subscription pointer to the subscription object this callback belongs to + * \param[in] callback pointer to this callback object (e.g. `rclcpp::AnySubscriptionCallback`) */ DECLARE_TRACEPOINT( rclcpp_subscription_callback_added, const void * subscription, const void * callback) +/// `rcl_service_init` /** - * tp: rcl_service_init + * Service initialisation. + * Links a `rcl_service_t` handle to its `rcl_node_t` handle + * and its `rmw_service_t` handle, and links it to a service name. + * + * \param[in] service_handle pointer to the service's `rcl_service_t` handle + * \param[in] node_handle pointer to the `rcl_node_t` handle of the node the service belongs to + * \param[in] rmw_service_handle pointer to the service's `rmw_service_t` handle + * \param[in] service_name full service name */ DECLARE_TRACEPOINT( rcl_service_init, @@ -106,16 +172,29 @@ DECLARE_TRACEPOINT( const void * rmw_service_handle, const char * service_name) +/// `rclcpp_service_callback_added` /** - * tp: rclcpp_service_callback_added + * Link a service callback object to a service. + * + * \param[in] service_handle + * pointer to the `rcl_service_t` handle of the service this callback belongs to + * \param[in] callback pointer to this callback object (e.g. `rclcpp::AnyServiceCallback`) */ DECLARE_TRACEPOINT( rclcpp_service_callback_added, const void * service_handle, const void * callback) +/// `rcl_client_init` /** - * tp: rcl_client_init + * Client initialisation. + * Links a `rcl_client_t` handle to its `rcl_node_t` handle + * and its `rmw_client_t` handle, and links it to a client name. + * + * \param[in] client_handle pointer to the client's `rcl_client_t` handle + * \param[in] node_handle pointer to the `rcl_node_t` handle of the node the client belongs to + * \param[in] rmw_client_handle pointer to the client's `rmw_client_t` handle + * \param[in] service_name full client name */ DECLARE_TRACEPOINT( rcl_client_init, @@ -124,40 +203,68 @@ DECLARE_TRACEPOINT( const void * rmw_client_handle, const char * service_name) +/// `rcl_timer_init` /** - * tp: rcl_timer_init + * Timer initialisation. + * Notes the timer's period. + * + * \param[in] timer_handle pointer to the timer's `rcl_timer_t` handle + * \param[in] period period in nanoseconds */ DECLARE_TRACEPOINT( rcl_timer_init, const void * timer_handle, int64_t period) +/// `rclcpp_timer_callback_added` /** - * tp: rclcpp_timer_callback_added + * Link a timer callback object to its `rcl_timer_t` handle. + * + * \param[in] timer_handle + * pointer to the `rcl_timer_t` handle of the timer this callback belongs to + * \param[in] callback pointer to the callback object (`std::function`) */ DECLARE_TRACEPOINT( rclcpp_timer_callback_added, const void * timer_handle, const void * callback) +/// `rclcpp_callback_register` /** - * tp: rclcpp_callback_register + * Register a demangled function symbol with a callback. + * + * \param[in] callback pointer to the callback object + * (e.g. `rclcpp::AnySubscriptionCallback`, + * `rclcpp::AnyServiceCallback`, timer `std::function`, etc.) + * \param[in] function_symbol demangled symbol of the callback function/lambda, + * see \ref get_symbol() */ DECLARE_TRACEPOINT( rclcpp_callback_register, const void * callback, const char * function_symbol) +/// `callback_start` /** - * tp: callback_start + * Start of a callback. + * + * \param[in] callback pointer to this callback object + * (e.g. `rclcpp::AnySubscriptionCallback`, + * `rclcpp::AnyServiceCallback`, timer `std::function`, etc.) + * \param[in] is_intra_process whether this callback is done via intra-process or not */ DECLARE_TRACEPOINT( callback_start, const void * callback, const bool is_intra_process) +/// `callback_end` /** - * tp: callback_end + * End of a callback. + * + * \param[in] callback pointer to this callback object + * (e.g. `rclcpp::AnySubscriptionCallback`, + * `rclcpp::AnyServiceCallback`, timer `std::function`, etc.) */ DECLARE_TRACEPOINT( callback_end, diff --git a/tracetools/include/tracetools/utils.hpp b/tracetools/include/tracetools/utils.hpp index 77f4811..e3c934d 100644 --- a/tracetools/include/tracetools/utils.hpp +++ b/tracetools/include/tracetools/utils.hpp @@ -20,12 +20,21 @@ #include "tracetools/visibility_control.hpp" +/// Default symbol, used when address resolution fails. #define SYMBOL_UNKNOWN "UNKNOWN" TRACETOOLS_PUBLIC const char * _demangle_symbol(const char * mangled); TRACETOOLS_PUBLIC const char * _get_symbol_funcptr(void * funcptr); +/// Get symbol from an std::function object. +/** + * If function address resolution or symbol demangling fails, + * this will return a string that starts with \ref SYMBOL_UNKNOWN. + * + * \param[in] f the std::function object + * \return the symbol, or a placeholder + */ template const char * get_symbol(std::function f) { @@ -40,7 +49,13 @@ const char * get_symbol(std::function f) return _demangle_symbol(f.target_type().name()); } -// Fallback meant for lambdas with captures +/// Get symbol from a function-related object. +/** + * Fallback meant for lambdas with captures. + * + * \param[in] l a generic object + * \return the symbol + */ template const char * get_symbol(L && l) {