Skip to content

Commit 2d153c8

Browse files
kartbenjhedberg
kartben
authored and
jhedberg
committed
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é <[email protected]>
1 parent d2fc338 commit 2d153c8

File tree

5 files changed

+136
-74
lines changed

5 files changed

+136
-74
lines changed

‎include/zephyr/tracing/tracing.h‎

Lines changed: 69 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,14 @@
33
*
44
* SPDX-License-Identifier: Apache-2.0
55
*/
6+
7+
/**
8+
* @file
9+
* @ingroup subsys_tracing
10+
* @ingroup subsys_tracing_apis
11+
* @brief Main header file for tracing subsystem API.
12+
*/
13+
614
#ifndef ZEPHYR_INCLUDE_TRACING_TRACING_H_
715
#define ZEPHYR_INCLUDE_TRACING_TRACING_H_
816

@@ -18,9 +26,9 @@
1826
#include "tracing_user.h"
1927
#else
2028
/**
21-
* @brief Tracing
29+
* @brief Interfaces for the tracing subsystem.
2230
*
23-
* The tracing subsystem provides hooks that permits you to collect data from
31+
* The tracing subsystem provides that permits you to collect data from
2432
* your application and allows tools running on a host to visualize the
2533
* inner-working of the kernel and various other subsystems.
2634
*
@@ -30,14 +38,18 @@
3038
*/
3139

3240
/**
33-
* @brief Tracing APIs
34-
* @defgroup subsys_tracing_apis Tracing APIs
41+
* @defgroup subsys_tracing_apis Tracing hooks
42+
* @ingroup subsys_tracing
43+
* @brief Hook points used by tracing backends.
44+
*
45+
* Macros invoked across kernel and subsystem code to mark entry, blocking, exit, and various
46+
* lifecycle events.
3547
* @{
3648
*/
3749

3850
/**
39-
* @brief Thread Tracing APIs
40-
* @defgroup subsys_tracing_apis_thread Thread Tracing APIs
51+
* @brief Tracing hooks for thread events
52+
* @defgroup subsys_tracing_apis_thread Thread
4153
* @{
4254
*/
4355

@@ -305,8 +317,8 @@
305317
/** @}c*/ /* end of subsys_tracing_apis_thread */
306318

307319
/**
308-
* @brief Work Tracing APIs
309-
* @defgroup subsys_tracing_apis_work Work Tracing APIs
320+
* @brief Tracing hooks for work item events
321+
* @defgroup subsys_tracing_apis_work Work item
310322
* @{
311323
*/
312324

@@ -402,8 +414,8 @@
402414
/** @} */ /* end of subsys_tracing_apis_work */
403415

404416
/**
405-
* @brief Work Queue Tracing APIs
406-
* @defgroup subsys_tracing_apis_work_q Work Queue Tracing APIs
417+
* @brief Tracing hooks for work queue events
418+
* @defgroup subsys_tracing_apis_work_q Work queue
407419
* @{
408420
*/
409421

@@ -476,8 +488,8 @@
476488
/** @} */ /* end of subsys_tracing_apis_work_q */
477489

478490
/**
479-
* @brief Work Delayable Tracing APIs
480-
* @defgroup subsys_tracing_apis_work_delayable Work Delayable Tracing APIs
491+
* @brief Tracing hooks for delayable work item events
492+
* @defgroup subsys_tracing_apis_work_delayable Delayable work item
481493
* @{
482494
*/
483495

@@ -597,8 +609,8 @@
597609
/** @} */ /* end of subsys_tracing_apis_work_delayable */
598610

599611
/**
600-
* @brief Work Poll Tracing APIs
601-
* @defgroup subsys_tracing_apis_work_poll Work Poll Tracing APIs
612+
* @brief Tracing hooks for triggered work item events
613+
* @defgroup subsys_tracing_apis_work_poll Triggered work item
602614
* @{
603615
*/
604616

@@ -670,8 +682,8 @@
670682
/** @} */ /* end of subsys_tracing_apis_work_poll */
671683

672684
/**
673-
* @brief Poll Tracing APIs
674-
* @defgroup subsys_tracing_apis_poll Poll Tracing APIs
685+
* @brief Tracing hooks for polling events
686+
* @defgroup subsys_tracing_apis_poll Polling
675687
* @{
676688
*/
677689

@@ -722,8 +734,8 @@
722734
/** @} */ /* end of subsys_tracing_apis_poll */
723735

724736
/**
725-
* @brief Semaphore Tracing APIs
726-
* @defgroup subsys_tracing_apis_sem Semaphore Tracing APIs
737+
* @brief Tracing hooks for semaphore events
738+
* @defgroup subsys_tracing_apis_sem Semaphore
727739
* @{
728740
*/
729741

@@ -777,8 +789,8 @@
777789
/** @} */ /* end of subsys_tracing_apis_sem */
778790

779791
/**
780-
* @brief Mutex Tracing APIs
781-
* @defgroup subsys_tracing_apis_mutex Mutex Tracing APIs
792+
* @brief Tracing hooks for mutex events
793+
* @defgroup subsys_tracing_apis_mutex Mutex
782794
* @{
783795
*/
784796

@@ -825,8 +837,8 @@
825837
/** @} */ /* end of subsys_tracing_apis_mutex */
826838

827839
/**
828-
* @brief Conditional Variable Tracing APIs
829-
* @defgroup subsys_tracing_apis_condvar Conditional Variable Tracing APIs
840+
* @brief Tracing hooks for conditional variable events
841+
* @defgroup subsys_tracing_apis_condvar Conditional variable
830842
* @{
831843
*/
832844

@@ -886,8 +898,8 @@
886898
/** @} */ /* end of subsys_tracing_apis_condvar */
887899

888900
/**
889-
* @brief Queue Tracing APIs
890-
* @defgroup subsys_tracing_apis_queue Queue Tracing APIs
901+
* @brief Tracing hooks for queue events
902+
* @defgroup subsys_tracing_apis_queue Queue
891903
* @{
892904
*/
893905

@@ -1087,8 +1099,8 @@
10871099
/** @} */ /* end of subsys_tracing_apis_queue */
10881100

10891101
/**
1090-
* @brief FIFO Tracing APIs
1091-
* @defgroup subsys_tracing_apis_fifo FIFO Tracing APIs
1102+
* @brief Tracing hooks for FIFO events
1103+
* @defgroup subsys_tracing_apis_fifo FIFO
10921104
* @{
10931105
*/
10941106

@@ -1219,8 +1231,8 @@
12191231
/** @} */ /* end of subsys_tracing_apis_fifo */
12201232

12211233
/**
1222-
* @brief LIFO Tracing APIs
1223-
* @defgroup subsys_tracing_apis_lifo LIFO Tracing APIs
1234+
* @brief Tracing hooks for LIFO events
1235+
* @defgroup subsys_tracing_apis_lifo LIFO
12241236
* @{
12251237
*/
12261238

@@ -1283,8 +1295,8 @@
12831295
/** @} */ /* end of subsys_tracing_apis_lifo */
12841296

12851297
/**
1286-
* @brief Stack Tracing APIs
1287-
* @defgroup subsys_tracing_apis_stack Stack Tracing APIs
1298+
* @brief Tracing hooks for stack events
1299+
* @defgroup subsys_tracing_apis_stack Stack
12881300
* @{
12891301
*/
12901302

@@ -1358,8 +1370,8 @@
13581370
/** @} */ /* end of subsys_tracing_apis_stack */
13591371

13601372
/**
1361-
* @brief Message Queue Tracing APIs
1362-
* @defgroup subsys_tracing_apis_msgq Message Queue Tracing APIs
1373+
* @brief Tracing hooks for message queue events
1374+
* @defgroup subsys_tracing_apis_msgq Message queue
13631375
* @{
13641376
*/
13651377

@@ -1477,8 +1489,8 @@
14771489
/** @} */ /* end of subsys_tracing_apis_msgq */
14781490

14791491
/**
1480-
* @brief Mailbox Tracing APIs
1481-
* @defgroup subsys_tracing_apis_mbox Mailbox Tracing APIs
1492+
* @brief Tracing hooks for mailbox events
1493+
* @defgroup subsys_tracing_apis_mbox Mailbox
14821494
* @{
14831495
*/
14841496

@@ -1570,8 +1582,8 @@
15701582
/** @} */ /* end of subsys_tracing_apis_mbox */
15711583

15721584
/**
1573-
* @brief Pipe Tracing APIs
1574-
* @defgroup subsys_tracing_apis_pipe Pipe Tracing APIs
1585+
* @brief Tracing hooks for pipe events
1586+
* @defgroup subsys_tracing_apis_pipe Pipe
15751587
* @{
15761588
*/
15771589

@@ -1656,8 +1668,8 @@
16561668
/** @} */ /* end of subsys_tracing_apis_pipe */
16571669

16581670
/**
1659-
* @brief Heap Tracing APIs
1660-
* @defgroup subsys_tracing_apis_heap Heap Tracing APIs
1671+
* @brief Tracing hooks for heap events
1672+
* @defgroup subsys_tracing_apis_heap Heap
16611673
* @{
16621674
*/
16631675

@@ -1815,8 +1827,8 @@
18151827
/** @} */ /* end of subsys_tracing_apis_heap */
18161828

18171829
/**
1818-
* @brief Memory Slab Tracing APIs
1819-
* @defgroup subsys_tracing_apis_mslab Memory Slab Tracing APIs
1830+
* @brief Tracing hooks for memory slab events
1831+
* @defgroup subsys_tracing_apis_mslab Memory slab
18201832
* @{
18211833
*/
18221834

@@ -1864,8 +1876,8 @@
18641876
/** @} */ /* end of subsys_tracing_apis_mslab */
18651877

18661878
/**
1867-
* @brief Timer Tracing APIs
1868-
* @defgroup subsys_tracing_apis_timer Timer Tracing APIs
1879+
* @brief Tracing hooks for timer events
1880+
* @defgroup subsys_tracing_apis_timer Timer
18691881
* @{
18701882
*/
18711883

@@ -1912,8 +1924,8 @@
19121924
/** @} */ /* end of subsys_tracing_apis_timer */
19131925

19141926
/**
1915-
* @brief Event Tracing APIs
1916-
* @defgroup subsys_tracing_apis_event Event Tracing APIs
1927+
* @brief Tracing hooks for event events
1928+
* @defgroup subsys_tracing_apis_event Event
19171929
* @{
19181930
*/
19191931

@@ -1968,8 +1980,8 @@
19681980
/** @} */ /* end of subsys_tracing_apis_event */
19691981

19701982
/**
1971-
* @brief System PM Tracing APIs
1972-
* @defgroup subsys_tracing_apis_pm_system System PM Tracing APIs
1983+
* @brief Tracing hooks for system power management events
1984+
* @defgroup subsys_tracing_apis_pm_system System PM
19731985
* @{
19741986
*/
19751987

@@ -1989,8 +2001,8 @@
19892001
/** @} */ /* end of subsys_tracing_apis_pm_system */
19902002

19912003
/**
1992-
* @brief PM Device Runtime Tracing APIs
1993-
* @defgroup subsys_tracing_apis_pm_device_runtime PM Device Runtime Tracing APIs
2004+
* @brief Tracing hooks for device runtime power management events
2005+
* @defgroup subsys_tracing_apis_pm_device_runtime PM Device Runtime
19942006
* @{
19952007
*/
19962008

@@ -2064,8 +2076,8 @@
20642076
/** @} */ /* end of subsys_tracing_apis_pm_device_runtime */
20652077

20662078
/**
2067-
* @brief Network Core Tracing APIs
2068-
* @defgroup subsys_tracing_apis_net Network Core Tracing APIs
2079+
* @brief Tracing hooks for network events
2080+
* @defgroup subsys_tracing_apis_net Network
20692081
* @{
20702082
*/
20712083

@@ -2114,8 +2126,8 @@
21142126
/** @} */ /* end of subsys_tracing_apis_net */
21152127

21162128
/**
2117-
* @brief Network Socket Tracing APIs
2118-
* @defgroup subsys_tracing_apis_socket Network Socket Tracing APIs
2129+
* @brief Tracing hooks for network socket events
2130+
* @defgroup subsys_tracing_apis_socket Network socket
21192131
* @{
21202132
*/
21212133

@@ -2412,12 +2424,12 @@
24122424
/** @} */ /* end of subsys_tracing_apis_socket */
24132425

24142426
/**
2415-
* @brief Named Tracing APIs
2416-
* @defgroup subsys_tracing_apis_named Named tracing APIs
2427+
* @brief Tracing hooks for user-defined named events
2428+
* @defgroup subsys_tracing_apis_named User-defined event
24172429
* @{
24182430
*/
24192431

2420-
/*
2432+
/**
24212433
* @brief Called by user to generate named events
24222434
*
24232435
* @param name name of event. Tracing subsystems may place a limit on
@@ -2430,8 +2442,8 @@
24302442
/** @} */ /* end of subsys_tracing_apis_named */
24312443

24322444
/**
2433-
* @brief GPIO Tracing APIs
2434-
* @defgroup subsys_tracing_apis_gpio GPIO Tracing APIs
2445+
* @brief Tracing hooks for GPIO events
2446+
* @defgroup subsys_tracing_apis_gpio GPIO
24352447
* @{
24362448
*/
24372449

‎include/zephyr/tracing/tracing_format.h‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,12 @@
44
* SPDX-License-Identifier: Apache-2.0
55
*/
66

7+
/**
8+
* @file
9+
* @ingroup subsys_tracing_format_apis
10+
* @brief Header file for tracing format API.
11+
*/
12+
713
#ifndef ZEPHYR_INCLUDE_TRACING_TRACING_FORMAT_H
814
#define ZEPHYR_INCLUDE_TRACING_TRACING_FORMAT_H
915

@@ -14,15 +20,23 @@ extern "C" {
1420
#endif
1521

1622
/**
17-
* @brief Tracing format APIs
18-
* @defgroup subsys_tracing_format_apis Tracing format APIs
23+
* @brief Helpers to format trace messages as strings or raw data
24+
* @defgroup subsys_tracing_format_apis Tracing format
1925
* @ingroup subsys_tracing
2026
* @{
2127
*/
2228

23-
/** @brief A structure to represent tracing data format. */
29+
/**
30+
* @brief A structure to represent tracing data format.
31+
*
32+
* This structure represents a piece of data to be emitted through the tracing subsystem.
33+
* It is typically used with @ref TRACING_FORMAT_DATA and @ref TRACING_DATA to wrap raw values or
34+
* memory regions in a common format that backends can consume
35+
*/
2436
typedef struct tracing_data {
37+
/** Pointer to the data buffer to be traced. */
2538
uint8_t *data;
39+
/** Size of the data buffer to be traced. */
2640
uint32_t length;
2741
} __packed tracing_data_t;
2842

‎include/zephyr/tracing/tracing_macros.h‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@
66
#ifndef ZEPHYR_INCLUDE_TRACING_TRACING_MACROS_H_
77
#define ZEPHYR_INCLUDE_TRACING_TRACING_MACROS_H_
88

9+
/**
10+
* @file
11+
* @ingroup subsys_tracing_macros
12+
* @brief Header file for tracing macros.
13+
*/
14+
915
#include <zephyr/sys/util_macro.h>
1016

1117
#if !defined(CONFIG_TRACING) && !defined(__DOXYGEN__)
@@ -25,9 +31,12 @@
2531
#else
2632

2733
/**
28-
* @brief Tracing utility macros
34+
* @brief Compile-time helpers to emit tracing events.
2935
* @defgroup subsys_tracing_macros Tracing utility macros
3036
* @ingroup subsys_tracing
37+
*
38+
* @note When @kconfig{CONFIG_TRACING} is disabled, all macros compile to no-ops, preserving call
39+
* sites with zero runtime cost.
3140
* @{
3241
*/
3342

0 commit comments

Comments
 (0)