include: tracing: doxygen coverage and cleanup
Gets tracing API to 100% coverage as well as some wordsmithing to
improve readability.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
diff --git a/include/zephyr/tracing/tracing.h b/include/zephyr/tracing/tracing.h
index 7608e64..b9624dd 100644
--- a/include/zephyr/tracing/tracing.h
+++ b/include/zephyr/tracing/tracing.h
@@ -3,6 +3,14 @@
*
* SPDX-License-Identifier: Apache-2.0
*/
+
+/**
+ * @file
+ * @ingroup subsys_tracing
+ * @ingroup subsys_tracing_apis
+ * @brief Main header file for tracing subsystem API.
+ */
+
#ifndef ZEPHYR_INCLUDE_TRACING_TRACING_H_
#define ZEPHYR_INCLUDE_TRACING_TRACING_H_
@@ -18,9 +26,9 @@
#include "tracing_user.h"
#else
/**
- * @brief Tracing
+ * @brief Interfaces for the tracing subsystem.
*
- * The tracing subsystem provides hooks that permits you to collect data from
+ * The tracing subsystem provides that permits you to collect data from
* your application and allows tools running on a host to visualize the
* inner-working of the kernel and various other subsystems.
*
@@ -30,14 +38,18 @@
*/
/**
- * @brief Tracing APIs
- * @defgroup subsys_tracing_apis Tracing APIs
+ * @defgroup subsys_tracing_apis Tracing hooks
+ * @ingroup subsys_tracing
+ * @brief Hook points used by tracing backends.
+ *
+ * Macros invoked across kernel and subsystem code to mark entry, blocking, exit, and various
+ * lifecycle events.
* @{
*/
/**
- * @brief Thread Tracing APIs
- * @defgroup subsys_tracing_apis_thread Thread Tracing APIs
+ * @brief Tracing hooks for thread events
+ * @defgroup subsys_tracing_apis_thread Thread
* @{
*/
@@ -305,8 +317,8 @@
/** @}c*/ /* end of subsys_tracing_apis_thread */
/**
- * @brief Work Tracing APIs
- * @defgroup subsys_tracing_apis_work Work Tracing APIs
+ * @brief Tracing hooks for work item events
+ * @defgroup subsys_tracing_apis_work Work item
* @{
*/
@@ -402,8 +414,8 @@
/** @} */ /* end of subsys_tracing_apis_work */
/**
- * @brief Work Queue Tracing APIs
- * @defgroup subsys_tracing_apis_work_q Work Queue Tracing APIs
+ * @brief Tracing hooks for work queue events
+ * @defgroup subsys_tracing_apis_work_q Work queue
* @{
*/
@@ -476,8 +488,8 @@
/** @} */ /* end of subsys_tracing_apis_work_q */
/**
- * @brief Work Delayable Tracing APIs
- * @defgroup subsys_tracing_apis_work_delayable Work Delayable Tracing APIs
+ * @brief Tracing hooks for delayable work item events
+ * @defgroup subsys_tracing_apis_work_delayable Delayable work item
* @{
*/
@@ -597,8 +609,8 @@
/** @} */ /* end of subsys_tracing_apis_work_delayable */
/**
- * @brief Work Poll Tracing APIs
- * @defgroup subsys_tracing_apis_work_poll Work Poll Tracing APIs
+ * @brief Tracing hooks for triggered work item events
+ * @defgroup subsys_tracing_apis_work_poll Triggered work item
* @{
*/
@@ -670,8 +682,8 @@
/** @} */ /* end of subsys_tracing_apis_work_poll */
/**
- * @brief Poll Tracing APIs
- * @defgroup subsys_tracing_apis_poll Poll Tracing APIs
+ * @brief Tracing hooks for polling events
+ * @defgroup subsys_tracing_apis_poll Polling
* @{
*/
@@ -722,8 +734,8 @@
/** @} */ /* end of subsys_tracing_apis_poll */
/**
- * @brief Semaphore Tracing APIs
- * @defgroup subsys_tracing_apis_sem Semaphore Tracing APIs
+ * @brief Tracing hooks for semaphore events
+ * @defgroup subsys_tracing_apis_sem Semaphore
* @{
*/
@@ -777,8 +789,8 @@
/** @} */ /* end of subsys_tracing_apis_sem */
/**
- * @brief Mutex Tracing APIs
- * @defgroup subsys_tracing_apis_mutex Mutex Tracing APIs
+ * @brief Tracing hooks for mutex events
+ * @defgroup subsys_tracing_apis_mutex Mutex
* @{
*/
@@ -825,8 +837,8 @@
/** @} */ /* end of subsys_tracing_apis_mutex */
/**
- * @brief Conditional Variable Tracing APIs
- * @defgroup subsys_tracing_apis_condvar Conditional Variable Tracing APIs
+ * @brief Tracing hooks for conditional variable events
+ * @defgroup subsys_tracing_apis_condvar Conditional variable
* @{
*/
@@ -886,8 +898,8 @@
/** @} */ /* end of subsys_tracing_apis_condvar */
/**
- * @brief Queue Tracing APIs
- * @defgroup subsys_tracing_apis_queue Queue Tracing APIs
+ * @brief Tracing hooks for queue events
+ * @defgroup subsys_tracing_apis_queue Queue
* @{
*/
@@ -1087,8 +1099,8 @@
/** @} */ /* end of subsys_tracing_apis_queue */
/**
- * @brief FIFO Tracing APIs
- * @defgroup subsys_tracing_apis_fifo FIFO Tracing APIs
+ * @brief Tracing hooks for FIFO events
+ * @defgroup subsys_tracing_apis_fifo FIFO
* @{
*/
@@ -1219,8 +1231,8 @@
/** @} */ /* end of subsys_tracing_apis_fifo */
/**
- * @brief LIFO Tracing APIs
- * @defgroup subsys_tracing_apis_lifo LIFO Tracing APIs
+ * @brief Tracing hooks for LIFO events
+ * @defgroup subsys_tracing_apis_lifo LIFO
* @{
*/
@@ -1283,8 +1295,8 @@
/** @} */ /* end of subsys_tracing_apis_lifo */
/**
- * @brief Stack Tracing APIs
- * @defgroup subsys_tracing_apis_stack Stack Tracing APIs
+ * @brief Tracing hooks for stack events
+ * @defgroup subsys_tracing_apis_stack Stack
* @{
*/
@@ -1358,8 +1370,8 @@
/** @} */ /* end of subsys_tracing_apis_stack */
/**
- * @brief Message Queue Tracing APIs
- * @defgroup subsys_tracing_apis_msgq Message Queue Tracing APIs
+ * @brief Tracing hooks for message queue events
+ * @defgroup subsys_tracing_apis_msgq Message queue
* @{
*/
@@ -1477,8 +1489,8 @@
/** @} */ /* end of subsys_tracing_apis_msgq */
/**
- * @brief Mailbox Tracing APIs
- * @defgroup subsys_tracing_apis_mbox Mailbox Tracing APIs
+ * @brief Tracing hooks for mailbox events
+ * @defgroup subsys_tracing_apis_mbox Mailbox
* @{
*/
@@ -1570,8 +1582,8 @@
/** @} */ /* end of subsys_tracing_apis_mbox */
/**
- * @brief Pipe Tracing APIs
- * @defgroup subsys_tracing_apis_pipe Pipe Tracing APIs
+ * @brief Tracing hooks for pipe events
+ * @defgroup subsys_tracing_apis_pipe Pipe
* @{
*/
@@ -1656,8 +1668,8 @@
/** @} */ /* end of subsys_tracing_apis_pipe */
/**
- * @brief Heap Tracing APIs
- * @defgroup subsys_tracing_apis_heap Heap Tracing APIs
+ * @brief Tracing hooks for heap events
+ * @defgroup subsys_tracing_apis_heap Heap
* @{
*/
@@ -1815,8 +1827,8 @@
/** @} */ /* end of subsys_tracing_apis_heap */
/**
- * @brief Memory Slab Tracing APIs
- * @defgroup subsys_tracing_apis_mslab Memory Slab Tracing APIs
+ * @brief Tracing hooks for memory slab events
+ * @defgroup subsys_tracing_apis_mslab Memory slab
* @{
*/
@@ -1864,8 +1876,8 @@
/** @} */ /* end of subsys_tracing_apis_mslab */
/**
- * @brief Timer Tracing APIs
- * @defgroup subsys_tracing_apis_timer Timer Tracing APIs
+ * @brief Tracing hooks for timer events
+ * @defgroup subsys_tracing_apis_timer Timer
* @{
*/
@@ -1912,8 +1924,8 @@
/** @} */ /* end of subsys_tracing_apis_timer */
/**
- * @brief Event Tracing APIs
- * @defgroup subsys_tracing_apis_event Event Tracing APIs
+ * @brief Tracing hooks for event events
+ * @defgroup subsys_tracing_apis_event Event
* @{
*/
@@ -1968,8 +1980,8 @@
/** @} */ /* end of subsys_tracing_apis_event */
/**
- * @brief System PM Tracing APIs
- * @defgroup subsys_tracing_apis_pm_system System PM Tracing APIs
+ * @brief Tracing hooks for system power management events
+ * @defgroup subsys_tracing_apis_pm_system System PM
* @{
*/
@@ -1989,8 +2001,8 @@
/** @} */ /* end of subsys_tracing_apis_pm_system */
/**
- * @brief PM Device Runtime Tracing APIs
- * @defgroup subsys_tracing_apis_pm_device_runtime PM Device Runtime Tracing APIs
+ * @brief Tracing hooks for device runtime power management events
+ * @defgroup subsys_tracing_apis_pm_device_runtime PM Device Runtime
* @{
*/
@@ -2064,8 +2076,8 @@
/** @} */ /* end of subsys_tracing_apis_pm_device_runtime */
/**
- * @brief Network Core Tracing APIs
- * @defgroup subsys_tracing_apis_net Network Core Tracing APIs
+ * @brief Tracing hooks for network events
+ * @defgroup subsys_tracing_apis_net Network
* @{
*/
@@ -2114,8 +2126,8 @@
/** @} */ /* end of subsys_tracing_apis_net */
/**
- * @brief Network Socket Tracing APIs
- * @defgroup subsys_tracing_apis_socket Network Socket Tracing APIs
+ * @brief Tracing hooks for network socket events
+ * @defgroup subsys_tracing_apis_socket Network socket
* @{
*/
@@ -2412,12 +2424,12 @@
/** @} */ /* end of subsys_tracing_apis_socket */
/**
- * @brief Named Tracing APIs
- * @defgroup subsys_tracing_apis_named Named tracing APIs
+ * @brief Tracing hooks for user-defined named events
+ * @defgroup subsys_tracing_apis_named User-defined event
* @{
*/
-/*
+/**
* @brief Called by user to generate named events
*
* @param name name of event. Tracing subsystems may place a limit on
@@ -2430,8 +2442,8 @@
/** @} */ /* end of subsys_tracing_apis_named */
/**
- * @brief GPIO Tracing APIs
- * @defgroup subsys_tracing_apis_gpio GPIO Tracing APIs
+ * @brief Tracing hooks for GPIO events
+ * @defgroup subsys_tracing_apis_gpio GPIO
* @{
*/
diff --git a/include/zephyr/tracing/tracing_format.h b/include/zephyr/tracing/tracing_format.h
index e26634e..7caea1d 100644
--- a/include/zephyr/tracing/tracing_format.h
+++ b/include/zephyr/tracing/tracing_format.h
@@ -4,6 +4,12 @@
* SPDX-License-Identifier: Apache-2.0
*/
+/**
+ * @file
+ * @ingroup subsys_tracing_format_apis
+ * @brief Header file for tracing format API.
+ */
+
#ifndef ZEPHYR_INCLUDE_TRACING_TRACING_FORMAT_H
#define ZEPHYR_INCLUDE_TRACING_TRACING_FORMAT_H
@@ -14,15 +20,23 @@
#endif
/**
- * @brief Tracing format APIs
- * @defgroup subsys_tracing_format_apis Tracing format APIs
+ * @brief Helpers to format trace messages as strings or raw data
+ * @defgroup subsys_tracing_format_apis Tracing format
* @ingroup subsys_tracing
* @{
*/
-/** @brief A structure to represent tracing data format. */
+/**
+ * @brief A structure to represent tracing data format.
+ *
+ * This structure represents a piece of data to be emitted through the tracing subsystem.
+ * It is typically used with @ref TRACING_FORMAT_DATA and @ref TRACING_DATA to wrap raw values or
+ * memory regions in a common format that backends can consume
+ */
typedef struct tracing_data {
+ /** Pointer to the data buffer to be traced. */
uint8_t *data;
+ /** Size of the data buffer to be traced. */
uint32_t length;
} __packed tracing_data_t;
diff --git a/include/zephyr/tracing/tracing_macros.h b/include/zephyr/tracing/tracing_macros.h
index 7e6c8d7..79465c2 100644
--- a/include/zephyr/tracing/tracing_macros.h
+++ b/include/zephyr/tracing/tracing_macros.h
@@ -6,6 +6,12 @@
#ifndef ZEPHYR_INCLUDE_TRACING_TRACING_MACROS_H_
#define ZEPHYR_INCLUDE_TRACING_TRACING_MACROS_H_
+/**
+ * @file
+ * @ingroup subsys_tracing_macros
+ * @brief Header file for tracing macros.
+ */
+
#include <zephyr/sys/util_macro.h>
#if !defined(CONFIG_TRACING) && !defined(__DOXYGEN__)
@@ -25,9 +31,12 @@
#else
/**
- * @brief Tracing utility macros
+ * @brief Compile-time helpers to emit tracing events.
* @defgroup subsys_tracing_macros Tracing utility macros
* @ingroup subsys_tracing
+ *
+ * @note When @kconfig{CONFIG_TRACING} is disabled, all macros compile to no-ops, preserving call
+ * sites with zero runtime cost.
* @{
*/
diff --git a/include/zephyr/tracing/tracing_syscall.h b/include/zephyr/tracing/tracing_syscall.h
index 5782246..b72ab9f 100644
--- a/include/zephyr/tracing/tracing_syscall.h
+++ b/include/zephyr/tracing/tracing_syscall.h
@@ -4,6 +4,12 @@
* SPDX-License-Identifier: Apache-2.0
*/
+/**
+ * @file
+ * @ingroup subsys_tracing_apis_syscall
+ * @brief Header file for syscall tracing API.
+ */
+
#ifndef ZEPHYR_INCLUDE_TRACING_SYSCALL_H_
#define ZEPHYR_INCLUDE_TRACING_SYSCALL_H_
@@ -14,8 +20,8 @@
#else
/**
- * @brief Syscall Tracing APIs
- * @defgroup subsys_tracing_apis_syscall Syscall Tracing APIs
+ * @brief Tracing hooks for system calls
+ * @defgroup subsys_tracing_apis_syscall Syscall Tracing
* @ingroup subsys_tracing_apis
* @{
*/
diff --git a/include/zephyr/tracing/tracking.h b/include/zephyr/tracing/tracking.h
index d6e24ee..d812898 100644
--- a/include/zephyr/tracing/tracking.h
+++ b/include/zephyr/tracing/tracking.h
@@ -3,6 +3,13 @@
*
* SPDX-License-Identifier: Apache-2.0
*/
+
+/**
+ * @file
+ * @ingroup subsys_tracing_object_tracking
+ * @brief Header file for object tracking API.
+ */
+
#ifndef ZEPHYR_INCLUDE_TRACING_TRACKING_H_
#define ZEPHYR_INCLUDE_TRACING_TRACKING_H_
@@ -12,37 +19,51 @@
#if defined(CONFIG_TRACING_OBJECT_TRACKING) || defined(__DOXYGEN__)
/**
- * @brief Object tracking
+ * @brief Helpers for accessing object tracking lists.
*
* Object tracking provides lists to kernel objects, so their
* existence and current status can be tracked.
*
* The following global variables are the heads of available lists:
- * - _track_list_k_timer
- * - _track_list_k_mem_slab
- * - _track_list_k_sem
- * - _track_list_k_mutex
- * - _track_list_k_stack
- * - _track_list_k_msgq
- * - _track_list_k_mbox
- * - _track_list_k_pipe
- * - _track_list_k_queue
- * - _track_list_k_event
+ * - @ref _track_list_k_timer
+ * - @ref _track_list_k_mem_slab
+ * - @ref _track_list_k_sem
+ * - @ref _track_list_k_mutex
+ * - @ref _track_list_k_stack
+ * - @ref _track_list_k_msgq
+ * - @ref _track_list_k_mbox
+ * - @ref _track_list_k_pipe
+ * - @ref _track_list_k_queue
+ * - @ref _track_list_k_event
+ *
+ * @note To enable object tracking, enable @kconfig{CONFIG_TRACING_OBJECT_TRACKING}.
+ * When disabled, all macros compile to no-ops, preserving call sites with zero runtime
+ * cost.
*
* @defgroup subsys_tracing_object_tracking Object tracking
* @ingroup subsys_tracing
* @{
*/
+/** @brief Head of the tracking list for k_timer objects. */
extern struct k_timer *_track_list_k_timer;
+/** @brief Head of the tracking list for k_mem_slab objects. */
extern struct k_mem_slab *_track_list_k_mem_slab;
+/** @brief Head of the tracking list for k_sem objects. */
extern struct k_sem *_track_list_k_sem;
+/** @brief Head of the tracking list for k_mutex objects. */
extern struct k_mutex *_track_list_k_mutex;
+/** @brief Head of the tracking list for k_stack objects. */
extern struct k_stack *_track_list_k_stack;
+/** @brief Head of the tracking list for k_msgq objects. */
extern struct k_msgq *_track_list_k_msgq;
+/** @brief Head of the tracking list for k_mbox objects. */
extern struct k_mbox *_track_list_k_mbox;
+/** @brief Head of the tracking list for k_pipe objects. */
extern struct k_pipe *_track_list_k_pipe;
+/** @brief Head of the tracking list for k_queue objects. */
extern struct k_queue *_track_list_k_queue;
+/** @brief Head of the tracking list for k_event objects. */
extern struct k_event *_track_list_k_event;
/**
