1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2017 Intel Corporation 3 */ 4 5 #ifndef _RTE_LOG_H_ 6 #define _RTE_LOG_H_ 7 8 /** 9 * @file 10 * 11 * RTE Logs API 12 * 13 * This file provides a log API to RTE applications. 14 */ 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 #include <stdint.h> 21 #include <stdio.h> 22 #include <stdarg.h> 23 #include <stdbool.h> 24 25 #include <rte_common.h> 26 #include <rte_config.h> 27 #include <rte_compat.h> 28 29 /* SDK log type */ 30 #define RTE_LOGTYPE_EAL 0 /**< Log related to eal. */ 31 #define RTE_LOGTYPE_MALLOC 1 /**< Log related to malloc. */ 32 #define RTE_LOGTYPE_RING 2 /**< Log related to ring. */ 33 #define RTE_LOGTYPE_MEMPOOL 3 /**< Log related to mempool. */ 34 #define RTE_LOGTYPE_TIMER 4 /**< Log related to timers. */ 35 #define RTE_LOGTYPE_PMD 5 /**< Log related to poll mode driver. */ 36 #define RTE_LOGTYPE_HASH 6 /**< Log related to hash table. */ 37 #define RTE_LOGTYPE_LPM 7 /**< Log related to LPM. */ 38 #define RTE_LOGTYPE_KNI 8 /**< Log related to KNI. */ 39 #define RTE_LOGTYPE_ACL 9 /**< Log related to ACL. */ 40 #define RTE_LOGTYPE_POWER 10 /**< Log related to power. */ 41 #define RTE_LOGTYPE_METER 11 /**< Log related to QoS meter. */ 42 #define RTE_LOGTYPE_SCHED 12 /**< Log related to QoS port scheduler. */ 43 #define RTE_LOGTYPE_PORT 13 /**< Log related to port. */ 44 #define RTE_LOGTYPE_TABLE 14 /**< Log related to table. */ 45 #define RTE_LOGTYPE_PIPELINE 15 /**< Log related to pipeline. */ 46 #define RTE_LOGTYPE_MBUF 16 /**< Log related to mbuf. */ 47 #define RTE_LOGTYPE_CRYPTODEV 17 /**< Log related to cryptodev. */ 48 #define RTE_LOGTYPE_EFD 18 /**< Log related to EFD. */ 49 #define RTE_LOGTYPE_EVENTDEV 19 /**< Log related to eventdev. */ 50 #define RTE_LOGTYPE_GSO 20 /**< Log related to GSO. */ 51 52 /* these log types can be used in an application */ 53 #define RTE_LOGTYPE_USER1 24 /**< User-defined log type 1. */ 54 #define RTE_LOGTYPE_USER2 25 /**< User-defined log type 2. */ 55 #define RTE_LOGTYPE_USER3 26 /**< User-defined log type 3. */ 56 #define RTE_LOGTYPE_USER4 27 /**< User-defined log type 4. */ 57 #define RTE_LOGTYPE_USER5 28 /**< User-defined log type 5. */ 58 #define RTE_LOGTYPE_USER6 29 /**< User-defined log type 6. */ 59 #define RTE_LOGTYPE_USER7 30 /**< User-defined log type 7. */ 60 #define RTE_LOGTYPE_USER8 31 /**< User-defined log type 8. */ 61 62 /** First identifier for extended logs */ 63 #define RTE_LOGTYPE_FIRST_EXT_ID 32 64 65 /* Can't use 0, as it gives compiler warnings */ 66 #define RTE_LOG_EMERG 1U /**< System is unusable. */ 67 #define RTE_LOG_ALERT 2U /**< Action must be taken immediately. */ 68 #define RTE_LOG_CRIT 3U /**< Critical conditions. */ 69 #define RTE_LOG_ERR 4U /**< Error conditions. */ 70 #define RTE_LOG_WARNING 5U /**< Warning conditions. */ 71 #define RTE_LOG_NOTICE 6U /**< Normal but significant condition. */ 72 #define RTE_LOG_INFO 7U /**< Informational. */ 73 #define RTE_LOG_DEBUG 8U /**< Debug-level messages. */ 74 #define RTE_LOG_MAX RTE_LOG_DEBUG /**< Most detailed log level. */ 75 76 /** 77 * Change the stream that will be used by the logging system. 78 * 79 * This can be done at any time. The f argument represents the stream 80 * to be used to send the logs. If f is NULL, the default output is 81 * used (stderr). 82 * 83 * @param f 84 * Pointer to the stream. 85 * @return 86 * - 0 on success. 87 * - Negative on error. 88 */ 89 int rte_openlog_stream(FILE *f); 90 91 /** 92 * Retrieve the stream used by the logging system (see rte_openlog_stream() 93 * to change it). 94 * 95 * @return 96 * Pointer to the stream. 97 */ 98 FILE *rte_log_get_stream(void); 99 100 /** 101 * Set the global log level. 102 * 103 * After this call, logs with a level lower or equal than the level 104 * passed as argument will be displayed. 105 * 106 * @param level 107 * Log level. A value between RTE_LOG_EMERG (1) and RTE_LOG_DEBUG (8). 108 */ 109 void rte_log_set_global_level(uint32_t level); 110 111 /** 112 * Get the global log level. 113 * 114 * @return 115 * The current global log level. 116 */ 117 uint32_t rte_log_get_global_level(void); 118 119 /** 120 * Get the log level for a given type. 121 * 122 * @param logtype 123 * The log type identifier. 124 * @return 125 * 0 on success, a negative value if logtype is invalid. 126 */ 127 int rte_log_get_level(uint32_t logtype); 128 129 /** 130 * For a given `logtype`, check if a log with `loglevel` can be printed. 131 * 132 * @param logtype 133 * The log type identifier 134 * @param loglevel 135 * Log level. A value between RTE_LOG_EMERG (1) and RTE_LOG_DEBUG (8). 136 * @return 137 * Returns 'true' if log can be printed and 'false' if it can't. 138 */ 139 __rte_experimental 140 bool rte_log_can_log(uint32_t logtype, uint32_t loglevel); 141 142 /** 143 * Set the log level for a given type based on globbing pattern. 144 * 145 * @param pattern 146 * The globbing pattern identifying the log type. 147 * @param level 148 * The level to be set. 149 * @return 150 * 0 on success, a negative value if level is invalid. 151 */ 152 int rte_log_set_level_pattern(const char *pattern, uint32_t level); 153 154 /** 155 * Set the log level for a given type based on regular expression. 156 * 157 * @param regex 158 * The regular expression identifying the log type. 159 * @param level 160 * The level to be set. 161 * @return 162 * 0 on success, a negative value if level is invalid. 163 */ 164 int rte_log_set_level_regexp(const char *regex, uint32_t level); 165 166 /** 167 * Set the log level for a given type. 168 * 169 * @param logtype 170 * The log type identifier. 171 * @param level 172 * The level to be set. 173 * @return 174 * 0 on success, a negative value if logtype or level is invalid. 175 */ 176 int rte_log_set_level(uint32_t logtype, uint32_t level); 177 178 /** 179 * Get the current loglevel for the message being processed. 180 * 181 * Before calling the user-defined stream for logging, the log 182 * subsystem sets a per-lcore variable containing the loglevel and the 183 * logtype of the message being processed. This information can be 184 * accessed by the user-defined log output function through this 185 * function. 186 * 187 * @return 188 * The loglevel of the message being processed. 189 */ 190 int rte_log_cur_msg_loglevel(void); 191 192 /** 193 * Get the current logtype for the message being processed. 194 * 195 * Before calling the user-defined stream for logging, the log 196 * subsystem sets a per-lcore variable containing the loglevel and the 197 * logtype of the message being processed. This information can be 198 * accessed by the user-defined log output function through this 199 * function. 200 * 201 * @return 202 * The logtype of the message being processed. 203 */ 204 int rte_log_cur_msg_logtype(void); 205 206 /** 207 * Register a dynamic log type 208 * 209 * If a log is already registered with the same type, the returned value 210 * is the same than the previous one. 211 * 212 * @param name 213 * The string identifying the log type. 214 * @return 215 * - >0: success, the returned value is the log type identifier. 216 * - (-ENOMEM): cannot allocate memory. 217 */ 218 int rte_log_register(const char *name); 219 220 /** 221 * Register a dynamic log type and try to pick its level from EAL options 222 * 223 * rte_log_register() is called inside. If successful, the function tries 224 * to search for matching regexp in the list of EAL log level options and 225 * pick the level from the last matching entry. If nothing can be applied 226 * from the list, the level will be set to the user-defined default value. 227 * 228 * @param name 229 * Name for the log type to be registered 230 * @param level_def 231 * Fallback level to be set if the global list has no matching options 232 * @return 233 * - >=0: the newly registered log type 234 * - <0: rte_log_register() error value 235 */ 236 int rte_log_register_type_and_pick_level(const char *name, uint32_t level_def); 237 238 /** 239 * @warning 240 * @b EXPERIMENTAL: this API may change without prior notice 241 * 242 * Dump name of each logtype, one per line. 243 * 244 * @param out 245 * Stream where the list is sent. 246 * @param prefix 247 * String preceding each logtype in the output. 248 */ 249 __rte_experimental 250 void rte_log_list_types(FILE *out, const char *prefix); 251 252 /** 253 * Dump log information. 254 * 255 * Dump the global level and the registered log types. 256 * 257 * @param f 258 * The output stream where the dump should be sent. 259 */ 260 void rte_log_dump(FILE *f); 261 262 /** 263 * Generates a log message. 264 * 265 * The message will be sent in the stream defined by the previous call 266 * to rte_openlog_stream(). 267 * 268 * The level argument determines if the log should be displayed or 269 * not, depending on the loglevel settings. 270 * 271 * The preferred alternative is the RTE_LOG() because it adds the 272 * level and type in the logged string. 273 * 274 * @param level 275 * Log level. A value between RTE_LOG_EMERG (1) and RTE_LOG_DEBUG (8). 276 * @param logtype 277 * The log type, for example, RTE_LOGTYPE_EAL. 278 * @param format 279 * The format string, as in printf(3), followed by the variable arguments 280 * required by the format. 281 * @return 282 * - 0: Success. 283 * - Negative on error. 284 */ 285 int rte_log(uint32_t level, uint32_t logtype, const char *format, ...) 286 #ifdef __GNUC__ 287 #if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ > 2)) 288 __rte_cold 289 #endif 290 #endif 291 __rte_format_printf(3, 4); 292 293 /** 294 * Generates a log message. 295 * 296 * The message will be sent in the stream defined by the previous call 297 * to rte_openlog_stream(). 298 * 299 * The level argument determines if the log should be displayed or 300 * not, depending on the loglevel settings. A trailing 301 * newline may be added if needed. 302 * 303 * The preferred alternative is the RTE_LOG() because it adds the 304 * level and type in the logged string. 305 * 306 * @param level 307 * Log level. A value between RTE_LOG_EMERG (1) and RTE_LOG_DEBUG (8). 308 * @param logtype 309 * The log type, for example, RTE_LOGTYPE_EAL. 310 * @param format 311 * The format string, as in printf(3), followed by the variable arguments 312 * required by the format. 313 * @param ap 314 * The va_list of the variable arguments required by the format. 315 * @return 316 * - 0: Success. 317 * - Negative on error. 318 */ 319 int rte_vlog(uint32_t level, uint32_t logtype, const char *format, va_list ap) 320 __rte_format_printf(3, 0); 321 322 /** 323 * Generates a log message. 324 * 325 * The RTE_LOG() is a helper that prefixes the string with the log level 326 * and type, and call rte_log(). 327 * 328 * @param l 329 * Log level. A value between EMERG (1) and DEBUG (8). The short name is 330 * expanded by the macro, so it cannot be an integer value. 331 * @param t 332 * The log type, for example, EAL. The short name is expanded by the 333 * macro, so it cannot be an integer value. 334 * @param ... 335 * The fmt string, as in printf(3), followed by the variable arguments 336 * required by the format. 337 * @return 338 * - 0: Success. 339 * - Negative on error. 340 */ 341 #define RTE_LOG(l, t, ...) \ 342 rte_log(RTE_LOG_ ## l, \ 343 RTE_LOGTYPE_ ## t, # t ": " __VA_ARGS__) 344 345 /** 346 * Generates a log message for data path. 347 * 348 * Similar to RTE_LOG(), except that it is removed at compilation time 349 * if the RTE_LOG_DP_LEVEL configuration option is lower than the log 350 * level argument. 351 * 352 * @param l 353 * Log level. A value between EMERG (1) and DEBUG (8). The short name is 354 * expanded by the macro, so it cannot be an integer value. 355 * @param t 356 * The log type, for example, EAL. The short name is expanded by the 357 * macro, so it cannot be an integer value. 358 * @param ... 359 * The fmt string, as in printf(3), followed by the variable arguments 360 * required by the format. 361 * @return 362 * - 0: Success. 363 * - Negative on error. 364 */ 365 #define RTE_LOG_DP(l, t, ...) \ 366 (void)((RTE_LOG_ ## l <= RTE_LOG_DP_LEVEL) ? \ 367 rte_log(RTE_LOG_ ## l, \ 368 RTE_LOGTYPE_ ## t, # t ": " __VA_ARGS__) : \ 369 0) 370 371 #define RTE_LOG_REGISTER_IMPL(type, name, level) \ 372 int type; \ 373 RTE_INIT(__##type) \ 374 { \ 375 type = rte_log_register_type_and_pick_level(name, RTE_LOG_##level); \ 376 if (type < 0) \ 377 type = RTE_LOGTYPE_EAL; \ 378 } 379 380 /** 381 * @warning 382 * @b EXPERIMENTAL: this API may change without prior notice 383 * 384 * Register a dynamic log type in constructor context with its name and level. 385 * 386 * It is a wrapper macro for declaring the logtype, register the log and 387 * sets it's level in the constructor context. 388 * 389 * @param type 390 * The log type identifier 391 * @param name 392 * Name for the log type to be registered 393 * @param level 394 * Log level. A value between EMERG (1) and DEBUG (8). 395 */ 396 #define RTE_LOG_REGISTER(type, name, level) \ 397 RTE_LOG_REGISTER_IMPL(type, RTE_STR(name), level) 398 399 /** 400 * @warning 401 * @b EXPERIMENTAL: this API may change without prior notice 402 * 403 * This is an equivalent to RTE_LOG_REGISTER, but relying on the build system 404 * to select the right format for the logtype. 405 */ 406 #define RTE_LOG_REGISTER_DEFAULT(type, level) \ 407 RTE_LOG_REGISTER_IMPL(type, RTE_STR(RTE_LOG_DEFAULT_LOGTYPE), level) 408 409 /** 410 * @warning 411 * @b EXPERIMENTAL: this API may change without prior notice 412 * 413 * This is an equivalent to RTE_LOG_REGISTER, but relying on the build system 414 * to select the right prefix for the logtype. 415 */ 416 #define RTE_LOG_REGISTER_SUFFIX(type, suffix, level) \ 417 RTE_LOG_REGISTER_IMPL(type, \ 418 RTE_STR(RTE_LOG_DEFAULT_LOGTYPE) "." RTE_STR(suffix), level) 419 420 #ifdef __cplusplus 421 } 422 #endif 423 424 #endif /* _RTE_LOG_H_ */ 425