The open source OpenXR runtime
a/u_logging: Docs for logging.
authored by
Ryan Pavlik
and committed by
Jakob Bornecrantz
8af1bfbf
8a936f24
+188
-40
+188
-40
src/xrt/auxiliary/util/u_logging.h
+188
-40
src/xrt/auxiliary/util/u_logging.h
···
32
32
*/
33
33
34
34
/*!
35
+
* @brief Logging level enum
36
+
*/
37
+
enum u_logging_level
38
+
{
39
+
U_LOGGING_TRACE, //!< Trace messages, highly verbose.
40
+
U_LOGGING_DEBUG, //!< Debug messages, verbose.
41
+
U_LOGGING_INFO, //!< Info messages: not very verbose, not indicating a problem.
42
+
U_LOGGING_WARN, //!< Warning messages: indicating a potential problem
43
+
U_LOGGING_ERROR, //!< Error messages: indicating a problem
44
+
U_LOGGING_RAW, //!< Special level for raw printing, prints a new-line.
45
+
};
46
+
47
+
/*!
35
48
* For places where you really just want printf, prints a new-line.
36
49
*/
37
50
#define U_LOG_RAW(...) \
···
39
52
u_log(__FILE__, __LINE__, __func__, U_LOGGING_RAW, __VA_ARGS__); \
40
53
} while (false)
41
54
55
+
/*!
56
+
* @name Base Logging Utilities
57
+
* In most cases, you will want to use another macro from this file, or a module/driver-local macro, to do your logging.
58
+
* @{
59
+
*/
60
+
/*!
61
+
* @brief Log a message at @p level , with file, line, and function context (always logs) - typically wrapped
62
+
* in a helper macro.
63
+
*
64
+
* @param level A @ref u_logging_level value for this message.
65
+
* @param ... Format string and optional format arguments.
66
+
*/
42
67
#define U_LOG(level, ...) \
43
68
do { \
44
69
u_log(__FILE__, __LINE__, __func__, level, __VA_ARGS__); \
45
70
} while (false)
46
71
72
+
/*!
73
+
* @brief Log at @p level only if the level is at least @p cond_level - typically wrapped in a helper macro.
74
+
*
75
+
* Adds file, line, and function context. Like U_LOG() but conditional.
76
+
*
77
+
* @param level A @ref u_logging_level value for this message.
78
+
* @param cond_level The minimum @ref u_logging_level that will be actually output.
79
+
* @param ... Format string and optional format arguments.
80
+
*/
47
81
#define U_LOG_IFL(level, cond_level, ...) \
48
82
do { \
49
83
if (cond_level <= level) { \
50
84
u_log(__FILE__, __LINE__, __func__, level, __VA_ARGS__); \
51
85
} \
52
86
} while (false)
53
-
87
+
/*!
88
+
* @brief Log at @p level for a given @ref xrt_device - typically wrapped in a helper macro.
89
+
*
90
+
* Adds file, line, and function context, and forwards device context from provided @p xdev .
91
+
*
92
+
* Like U_LOG() but calling u_log_xdev() (which takes a device) instead.
93
+
*
94
+
* @param level A @ref u_logging_level value for this message.
95
+
* @param xdev The @ref xrt_device pointer associated with this message.
96
+
* @param ... Format string and optional format arguments.
97
+
*/
54
98
#define U_LOG_XDEV(level, xdev, ...) \
55
99
do { \
56
100
u_log_xdev(__FILE__, __LINE__, __func__, level, xdev, __VA_ARGS__); \
57
101
} while (false)
58
-
102
+
/*!
103
+
* @brief Log at @p level for a given @ref xrt_device, only if the level is at least @p cond_level - typically wrapped
104
+
* in a helper macro.
105
+
*
106
+
* Adds file, line, and function context, and forwards device context from provided @p xdev .
107
+
* @param level A @ref u_logging_level value for this message.
108
+
* @param cond_level The minimum @ref u_logging_level that will be actually output.
109
+
* @param xdev The @ref xrt_device pointer associated with this message.
110
+
* @param ... Format string and optional format arguments.
111
+
*/
59
112
#define U_LOG_XDEV_IFL(level, cond_level, xdev, ...) \
60
113
do { \
61
114
if (cond_level <= level) { \
···
63
116
} \
64
117
} while (false)
65
118
66
-
// clang-format off
67
-
#define U_LOG_T(...) U_LOG_IFL_T(u_log_get_global_level(), __VA_ARGS__)
68
-
#define U_LOG_D(...) U_LOG_IFL_D(u_log_get_global_level(), __VA_ARGS__)
69
-
#define U_LOG_I(...) U_LOG_IFL_I(u_log_get_global_level(), __VA_ARGS__)
70
-
#define U_LOG_W(...) U_LOG_IFL_W(u_log_get_global_level(), __VA_ARGS__)
71
-
#define U_LOG_E(...) U_LOG_IFL_E(u_log_get_global_level(), __VA_ARGS__)
72
119
73
-
#define U_LOG_IFL_T(cond_level, ...) U_LOG_IFL(U_LOGGING_TRACE, cond_level, __VA_ARGS__)
74
-
#define U_LOG_IFL_D(cond_level, ...) U_LOG_IFL(U_LOGGING_DEBUG, cond_level, __VA_ARGS__)
75
-
#define U_LOG_IFL_I(cond_level, ...) U_LOG_IFL(U_LOGGING_INFO, cond_level, __VA_ARGS__)
76
-
#define U_LOG_IFL_W(cond_level, ...) U_LOG_IFL(U_LOGGING_WARN, cond_level, __VA_ARGS__)
77
-
#define U_LOG_IFL_E(cond_level, ...) U_LOG_IFL(U_LOGGING_ERROR, cond_level, __VA_ARGS__)
78
-
79
-
#define U_LOG_XDEV_IFL_T(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_TRACE, cond_level, xdev, __VA_ARGS__)
80
-
#define U_LOG_XDEV_IFL_D(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_DEBUG, cond_level, xdev, __VA_ARGS__)
81
-
#define U_LOG_XDEV_IFL_I(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_INFO, cond_level, xdev, __VA_ARGS__)
82
-
#define U_LOG_XDEV_IFL_W(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_WARN, cond_level, xdev, __VA_ARGS__)
83
-
#define U_LOG_XDEV_IFL_E(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_ERROR, cond_level, xdev, __VA_ARGS__)
84
-
85
-
#define U_LOG_XDEV_T(xdev, ...) U_LOG_XDEV(U_LOGGING_TRACE, xdev, __VA_ARGS__)
86
-
#define U_LOG_XDEV_D(xdev, ...) U_LOG_XDEV(U_LOGGING_DEBUG, xdev, __VA_ARGS__)
87
-
#define U_LOG_XDEV_I(xdev, ...) U_LOG_XDEV(U_LOGGING_INFO, xdev, __VA_ARGS__)
88
-
#define U_LOG_XDEV_W(xdev, ...) U_LOG_XDEV(U_LOGGING_WARN, xdev, __VA_ARGS__)
89
-
#define U_LOG_XDEV_E(xdev, ...) U_LOG_XDEV(U_LOGGING_ERROR, xdev, __VA_ARGS__)
90
-
// clang-format on
91
-
92
-
enum u_logging_level
93
-
{
94
-
U_LOGGING_TRACE,
95
-
U_LOGGING_DEBUG,
96
-
U_LOGGING_INFO,
97
-
U_LOGGING_WARN,
98
-
U_LOGGING_ERROR,
99
-
U_LOGGING_RAW, //!< Special level for raw printing, prints a new-line.
100
-
};
101
120
102
121
/*!
103
122
* Returns the global logging level, subsystems own logging level take precedence.
···
106
125
u_log_get_global_level(void);
107
126
108
127
/*!
109
-
* This function always logs, level is used for printing or passed to native
110
-
* logging functions.
128
+
* @brief Main non-device-related log implementation function: do not call directly, use a macro that wraps it.
129
+
*
130
+
* This function always logs: level is used for printing or passed to native logging functions.
131
+
*
132
+
* @param file Source file name associated with a message
133
+
* @param line Source file line associated with a message
134
+
* @param func Function name associated with a message
135
+
* @param level Message level: used for formatting or forwarding to native log functions
136
+
* @param format Format string
137
+
* @param ... Format parameters
111
138
*/
112
139
void
113
140
u_log(const char *file, int line, const char *func, enum u_logging_level level, const char *format, ...)
114
141
XRT_PRINTF_FORMAT(5, 6);
115
142
116
143
/*!
117
-
* This function always logs, level is used for printing or passed to native
118
-
* logging functions.
144
+
* @brief Main device-related log implementation function: do not call directly, use a macro that wraps it.
145
+
*
146
+
* This function always logs: level is used for printing or passed to native logging functions.
147
+
* @param file Source file name associated with a message
148
+
* @param line Source file line associated with a message
149
+
* @param func Function name associated with a message
150
+
* @param level Message level: used for formatting or forwarding to native log functions
151
+
* @param xdev The associated @ref xrt_device
152
+
* @param format Format string
153
+
* @param ... Format parameters
119
154
*/
120
155
void
121
156
u_log_xdev(const char *file,
···
126
161
const char *format,
127
162
...) XRT_PRINTF_FORMAT(6, 7);
128
163
164
+
/*!
165
+
* @}
166
+
*/
167
+
168
+
169
+
/*!
170
+
* @name Logging macros conditional on global log level
171
+
*
172
+
* These each imply a log level, and will only log if the global log level is equal or lower.
173
+
* They are often used for one-off logging in a module with few other logging needs,
174
+
* where having a module-specific log level would be unnecessary.
175
+
*
176
+
* @see U_LOG_IFL, u_log_get_global_level()
177
+
* @param ... Format string and optional format arguments.
178
+
* @{
179
+
*/
180
+
//! Log a message at U_LOGGING_TRACE level, conditional on the global log level
181
+
#define U_LOG_T(...) U_LOG_IFL_T(u_log_get_global_level(), __VA_ARGS__)
182
+
183
+
//! Log a message at U_LOGGING_DEBUG level, conditional on the global log level
184
+
#define U_LOG_D(...) U_LOG_IFL_D(u_log_get_global_level(), __VA_ARGS__)
185
+
186
+
//! Log a message at U_LOGGING_INFO level, conditional on the global log level
187
+
#define U_LOG_I(...) U_LOG_IFL_I(u_log_get_global_level(), __VA_ARGS__)
188
+
189
+
//! Log a message at U_LOGGING_WARN level, conditional on the global log level
190
+
#define U_LOG_W(...) U_LOG_IFL_W(u_log_get_global_level(), __VA_ARGS__)
191
+
192
+
//! Log a message at U_LOGGING_ERROR level, conditional on the global log level
193
+
#define U_LOG_E(...) U_LOG_IFL_E(u_log_get_global_level(), __VA_ARGS__)
194
+
195
+
/*!
196
+
* @}
197
+
*/
198
+
199
+
/*!
200
+
* @name Logging macros conditional on provided log level
201
+
*
202
+
* These are often wrapped within a module, to automatically supply
203
+
* @p cond_level as appropriate for that module.
204
+
*
205
+
* @see U_LOG_IFL
206
+
* @param cond_level The minimum @ref u_logging_level that will be actually output.
207
+
* @param ... Format string and optional format arguments.
208
+
*
209
+
* @{
210
+
*/
211
+
//! Conditionally log a message at U_LOGGING_TRACE level.
212
+
#define U_LOG_IFL_T(cond_level, ...) U_LOG_IFL(U_LOGGING_TRACE, cond_level, __VA_ARGS__)
213
+
//! Conditionally log a message at U_LOGGING_DEBUG level.
214
+
#define U_LOG_IFL_D(cond_level, ...) U_LOG_IFL(U_LOGGING_DEBUG, cond_level, __VA_ARGS__)
215
+
//! Conditionally log a message at U_LOGGING_INFO level.
216
+
#define U_LOG_IFL_I(cond_level, ...) U_LOG_IFL(U_LOGGING_INFO, cond_level, __VA_ARGS__)
217
+
//! Conditionally log a message at U_LOGGING_WARN level.
218
+
#define U_LOG_IFL_W(cond_level, ...) U_LOG_IFL(U_LOGGING_WARN, cond_level, __VA_ARGS__)
219
+
//! Conditionally log a message at U_LOGGING_ERROR level.
220
+
#define U_LOG_IFL_E(cond_level, ...) U_LOG_IFL(U_LOGGING_ERROR, cond_level, __VA_ARGS__)
221
+
/*!
222
+
* @}
223
+
*/
224
+
225
+
226
+
227
+
/*!
228
+
* @name Device-related logging macros conditional on provided log level
229
+
*
230
+
* These are often wrapped within a driver, to automatically supply @p xdev and
231
+
* @p cond_level from their conventional names and log level member variable.
232
+
*
233
+
* @param level A @ref u_logging_level value for this message.
234
+
* @param cond_level The minimum @ref u_logging_level that will be actually output.
235
+
* @param xdev The @ref xrt_device pointer associated with this message.
236
+
* @param ... Format string and optional format arguments.
237
+
*
238
+
* @{
239
+
*/
240
+
//! Conditionally log a device-related message at U_LOGGING_TRACE level.
241
+
#define U_LOG_XDEV_IFL_T(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_TRACE, cond_level, xdev, __VA_ARGS__)
242
+
//! Conditionally log a device-related message at U_LOGGING_DEBUG level.
243
+
#define U_LOG_XDEV_IFL_D(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_DEBUG, cond_level, xdev, __VA_ARGS__)
244
+
//! Conditionally log a device-related message at U_LOGGING_INFO level.
245
+
#define U_LOG_XDEV_IFL_I(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_INFO, cond_level, xdev, __VA_ARGS__)
246
+
//! Conditionally log a device-related message at U_LOGGING_WARN level.
247
+
#define U_LOG_XDEV_IFL_W(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_WARN, cond_level, xdev, __VA_ARGS__)
248
+
//! Conditionally log a device-related message at U_LOGGING_ERROR level.
249
+
#define U_LOG_XDEV_IFL_E(xdev, cond_level, ...) U_LOG_XDEV_IFL(U_LOGGING_ERROR, cond_level, xdev, __VA_ARGS__)
250
+
/*!
251
+
* @}
252
+
*/
253
+
254
+
/*!
255
+
* @name Device-related logging macros that always log.
256
+
*
257
+
* These wrap U_LOG_XDEV() to supply the @p level - which is only used for formatting the output, these macros always
258
+
* log regardless of level.
259
+
*
260
+
* @param xdev The @ref xrt_device pointer associated with this message.
261
+
* @param ... Format string and optional format arguments.
262
+
* @{
263
+
*/
264
+
//! Log a device-related message at U_LOGGING_TRACE level (always logs).
265
+
#define U_LOG_XDEV_T(xdev, ...) U_LOG_XDEV(U_LOGGING_TRACE, xdev, __VA_ARGS__)
266
+
//! Log a device-related message at U_LOGGING_DEBUG level (always logs).
267
+
#define U_LOG_XDEV_D(xdev, ...) U_LOG_XDEV(U_LOGGING_DEBUG, xdev, __VA_ARGS__)
268
+
//! Log a device-related message at U_LOGGING_INFO level (always logs).
269
+
#define U_LOG_XDEV_I(xdev, ...) U_LOG_XDEV(U_LOGGING_INFO, xdev, __VA_ARGS__)
270
+
//! Log a device-related message at U_LOGGING_WARN level (always logs).
271
+
#define U_LOG_XDEV_W(xdev, ...) U_LOG_XDEV(U_LOGGING_WARN, xdev, __VA_ARGS__)
272
+
//! Log a device-related message at U_LOGGING_ERROR level (always logs).
273
+
#define U_LOG_XDEV_E(xdev, ...) U_LOG_XDEV(U_LOGGING_ERROR, xdev, __VA_ARGS__)
274
+
/*!
275
+
* @}
276
+
*/
129
277
130
278
/*!
131
279
* @}