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 #include <assert.h> 17 #include <stdint.h> 18 #include <stdio.h> 19 #include <stdarg.h> 20 #include <stdbool.h> 21 22 #include <rte_common.h> 23 #include <rte_config.h> 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /* SDK log type */ 30 #define RTE_LOGTYPE_EAL 0 /**< Log related to eal. */ 31 /* was RTE_LOGTYPE_MALLOC */ 32 /* was RTE_LOGTYPE_RING */ 33 /* was RTE_LOGTYPE_MEMPOOL */ 34 /* was RTE_LOGTYPE_TIMER */ 35 /* was RTE_LOGTYPE_PMD */ 36 /* was RTE_LOGTYPE_HASH */ 37 /* was RTE_LOGTYPE_LPM */ 38 /* was RTE_LOGTYPE_KNI */ 39 /* was RTE_LOGTYPE_ACL */ 40 /* was RTE_LOGTYPE_POWER */ 41 /* was RTE_LOGTYPE_METER */ 42 /* was RTE_LOGTYPE_SCHED */ 43 /* was RTE_LOGTYPE_PORT */ 44 /* was RTE_LOGTYPE_TABLE */ 45 /* was RTE_LOGTYPE_PIPELINE */ 46 /* was RTE_LOGTYPE_MBUF */ 47 /* was RTE_LOGTYPE_CRYPTODEV */ 48 /* was RTE_LOGTYPE_EFD */ 49 /* was RTE_LOGTYPE_EVENTDEV */ 50 /* was RTE_LOGTYPE_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 bool rte_log_can_log(uint32_t logtype, uint32_t loglevel); 140 141 /** 142 * Set the log level for a given type based on globbing pattern. 143 * 144 * @param pattern 145 * The globbing pattern identifying the log type. 146 * @param level 147 * The level to be set. 148 * @return 149 * 0 on success, a negative value if level is invalid. 150 */ 151 int rte_log_set_level_pattern(const char *pattern, uint32_t level); 152 153 /** 154 * Set the log level for a given type based on regular expression. 155 * 156 * @param regex 157 * The regular expression identifying the log type. 158 * @param level 159 * The level to be set. 160 * @return 161 * 0 on success, a negative value if level is invalid. 162 */ 163 int rte_log_set_level_regexp(const char *regex, uint32_t level); 164 165 /** 166 * Set the log level for a given type. 167 * 168 * @param logtype 169 * The log type identifier. 170 * @param level 171 * The level to be set. 172 * @return 173 * 0 on success, a negative value if logtype or level is invalid. 174 */ 175 int rte_log_set_level(uint32_t logtype, uint32_t level); 176 177 /** 178 * Get the current loglevel for the message being processed. 179 * 180 * Before calling the user-defined stream for logging, the log 181 * subsystem sets a per-lcore variable containing the loglevel and the 182 * logtype of the message being processed. This information can be 183 * accessed by the user-defined log output function through this 184 * function. 185 * 186 * @return 187 * The loglevel of the message being processed. 188 */ 189 int rte_log_cur_msg_loglevel(void); 190 191 /** 192 * Get the current logtype for the message being processed. 193 * 194 * Before calling the user-defined stream for logging, the log 195 * subsystem sets a per-lcore variable containing the loglevel and the 196 * logtype of the message being processed. This information can be 197 * accessed by the user-defined log output function through this 198 * function. 199 * 200 * @return 201 * The logtype of the message being processed. 202 */ 203 int rte_log_cur_msg_logtype(void); 204 205 /** 206 * Register a dynamic log type 207 * 208 * If a log is already registered with the same type, the returned value 209 * is the same than the previous one. 210 * 211 * @param name 212 * The string identifying the log type. 213 * @return 214 * - >0: success, the returned value is the log type identifier. 215 * - (-ENOMEM): cannot allocate memory. 216 */ 217 int rte_log_register(const char *name); 218 219 /** 220 * Register a dynamic log type and try to pick its level from EAL options 221 * 222 * rte_log_register() is called inside. If successful, the function tries 223 * to search for matching regexp in the list of EAL log level options and 224 * pick the level from the last matching entry. If nothing can be applied 225 * from the list, the level will be set to the user-defined default value. 226 * 227 * @param name 228 * Name for the log type to be registered 229 * @param level_def 230 * Fallback level to be set if the global list has no matching options 231 * @return 232 * - >=0: the newly registered log type 233 * - <0: rte_log_register() error value 234 */ 235 int rte_log_register_type_and_pick_level(const char *name, uint32_t level_def); 236 237 /** 238 * Dump name of each logtype, one per line. 239 * 240 * @param out 241 * Stream where the list is sent. 242 * @param prefix 243 * String preceding each logtype in the output. 244 */ 245 void rte_log_list_types(FILE *out, const char *prefix); 246 247 /** 248 * Dump log information. 249 * 250 * Dump the global level and the registered log types. 251 * 252 * @param f 253 * The output stream where the dump should be sent. 254 */ 255 void rte_log_dump(FILE *f); 256 257 /** 258 * Generates a log message. 259 * 260 * The message will be sent in the stream defined by the previous call 261 * to rte_openlog_stream(). 262 * 263 * The level argument determines if the log should be displayed or 264 * not, depending on the loglevel settings. 265 * 266 * The preferred alternative is the RTE_LOG() because it adds the 267 * level and type in the logged string. 268 * 269 * @param level 270 * Log level. A value between RTE_LOG_EMERG (1) and RTE_LOG_DEBUG (8). 271 * @param logtype 272 * The log type, for example, RTE_LOGTYPE_EAL. 273 * @param format 274 * The format string, as in printf(3), followed by the variable arguments 275 * required by the format. 276 * @return 277 * - 0: Success. 278 * - Negative on error. 279 */ 280 int rte_log(uint32_t level, uint32_t logtype, const char *format, ...) 281 __rte_cold 282 __rte_format_printf(3, 4); 283 284 /** 285 * Generates a log message. 286 * 287 * The message will be sent in the stream defined by the previous call 288 * to rte_openlog_stream(). 289 * 290 * The level argument determines if the log should be displayed or 291 * not, depending on the loglevel settings. A trailing 292 * newline may be added if needed. 293 * 294 * The preferred alternative is the RTE_LOG() because it adds the 295 * level and type in the logged string. 296 * 297 * @param level 298 * Log level. A value between RTE_LOG_EMERG (1) and RTE_LOG_DEBUG (8). 299 * @param logtype 300 * The log type, for example, RTE_LOGTYPE_EAL. 301 * @param format 302 * The format string, as in printf(3), followed by the variable arguments 303 * required by the format. 304 * @param ap 305 * The va_list of the variable arguments required by the format. 306 * @return 307 * - 0: Success. 308 * - Negative on error. 309 */ 310 int rte_vlog(uint32_t level, uint32_t logtype, const char *format, va_list ap) 311 __rte_format_printf(3, 0); 312 313 /** 314 * Generates a log message. 315 * 316 * The RTE_LOG() is a helper that prefixes the string with the log level 317 * and type, and call rte_log(). 318 * 319 * @param l 320 * Log level. A value between EMERG (1) and DEBUG (8). The short name is 321 * expanded by the macro, so it cannot be an integer value. 322 * @param t 323 * The log type, for example, EAL. The short name is expanded by the 324 * macro, so it cannot be an integer value. 325 * @param ... 326 * The fmt string, as in printf(3), followed by the variable arguments 327 * required by the format. 328 * @return 329 * - 0: Success. 330 * - Negative on error. 331 */ 332 #define RTE_LOG(l, t, ...) \ 333 rte_log(RTE_LOG_ ## l, \ 334 RTE_LOGTYPE_ ## t, # t ": " __VA_ARGS__) 335 336 /** 337 * Generates a log message for data path. 338 * 339 * Similar to RTE_LOG(), except that it is removed at compilation time 340 * if the RTE_LOG_DP_LEVEL configuration option is lower than the log 341 * level argument. 342 * 343 * @param l 344 * Log level. A value between EMERG (1) and DEBUG (8). The short name is 345 * expanded by the macro, so it cannot be an integer value. 346 * @param t 347 * The log type, for example, EAL. The short name is expanded by the 348 * macro, so it cannot be an integer value. 349 * @param ... 350 * The fmt string, as in printf(3), followed by the variable arguments 351 * required by the format. 352 * @return 353 * - 0: Success. 354 * - Negative on error. 355 */ 356 #define RTE_LOG_DP(l, t, ...) \ 357 (void)((RTE_LOG_ ## l <= RTE_LOG_DP_LEVEL) ? \ 358 rte_log(RTE_LOG_ ## l, \ 359 RTE_LOGTYPE_ ## t, # t ": " __VA_ARGS__) : \ 360 0) 361 362 #if defined(RTE_TOOLCHAIN_GCC) && !defined(PEDANTIC) 363 #define RTE_LOG_CHECK_NO_NEWLINE(fmt) \ 364 static_assert(!__builtin_strchr(fmt, '\n'), \ 365 "This log format string contains a \\n") 366 #else 367 #define RTE_LOG_CHECK_NO_NEWLINE(...) 368 #endif 369 370 /** 371 * Generates a log message with a single trailing newline. 372 * 373 * The RTE_LOG_LINE() is a helper that expands logging of a message 374 * with RTE_LOG() appending a single newline to the formatted message. 375 * 376 * @param l 377 * Log level. A value between EMERG (1) and DEBUG (8). The short name 378 * is expanded by the macro, so it cannot be an integer value. 379 * @param t 380 * The log type, for example, EAL. The short name is expanded by the 381 * macro, so it cannot be an integer value. 382 * @param ... 383 * The fmt string, as in printf(3), followed by the variable arguments 384 * required by the format. 385 */ 386 #define RTE_LOG_LINE(l, t, ...) do { \ 387 RTE_LOG_CHECK_NO_NEWLINE(RTE_FMT_HEAD(__VA_ARGS__ ,)); \ 388 RTE_LOG(l, t, RTE_FMT(RTE_FMT_HEAD(__VA_ARGS__ ,) "\n", \ 389 RTE_FMT_TAIL(__VA_ARGS__ ,))); \ 390 } while (0) 391 392 /** 393 * Generates a log message for data path with a single trailing newline. 394 * 395 * Similar to RTE_LOG_LINE(), except that it is removed at compilation 396 * time if the RTE_LOG_DP_LEVEL configuration option is lower than the 397 * log level argument. 398 * 399 * The RTE_LOG_LINE() is a helper that expands logging of a message 400 * with RTE_LOG_DP() appending a single newline to the formatted 401 * message. 402 * 403 * @param l 404 * Log level. A value between EMERG (1) and DEBUG (8). The short name 405 * is expanded by the macro, so it cannot be an integer value. 406 * @param t 407 * The log type, for example, EAL. The short name is expanded by the 408 * macro, so it cannot be an integer value. 409 * @param ... 410 * The fmt string, as in printf(3), followed by the variable arguments 411 * required by the format. 412 */ 413 #define RTE_LOG_DP_LINE(l, t, ...) do { \ 414 RTE_LOG_CHECK_NO_NEWLINE(RTE_FMT_HEAD(__VA_ARGS__ ,)); \ 415 RTE_LOG_DP(l, t, RTE_FMT(RTE_FMT_HEAD(__VA_ARGS__ ,) "\n", \ 416 RTE_FMT_TAIL(__VA_ARGS__ ,))); \ 417 } while (0) 418 419 #define RTE_LOG_COMMA , 420 421 /** 422 * Generates a log message with a supplied prefix and arguments with a 423 * single trailing newline. 424 * 425 * The RTE_LOG_LINE_PREFIX() is a helper that expands logging of a 426 * message with RTE_LOG() prepending the supplied prefix and arguments 427 * appending a single newline to the formatted message. 428 * 429 * @param l 430 * Log level. A value between EMERG (1) and DEBUG (8). The short name 431 * is expanded by the macro, so it cannot be an integer value. 432 * @param t 433 * The log type, for example, EAL. The short name is expanded by the 434 * macro, so it cannot be an integer value. 435 * @param prefix 436 * The prefix format string. 437 * @param args 438 * The arguments for the prefix format string. If args contains 439 * multiple arguments use RTE_LOG_COMMA to defer expansion. 440 * @param ... 441 * The fmt string, as in printf(3), followed by the variable arguments 442 * required by the format. 443 */ 444 #define RTE_LOG_LINE_PREFIX(l, t, prefix, args, ...) do { \ 445 RTE_LOG_CHECK_NO_NEWLINE(RTE_FMT_HEAD(prefix __VA_ARGS__ ,)); \ 446 RTE_LOG(l, t, RTE_FMT(prefix RTE_FMT_HEAD(__VA_ARGS__ ,) "\n", \ 447 args RTE_LOG_COMMA RTE_FMT_TAIL(__VA_ARGS__ ,))); \ 448 } while (0) 449 450 /** 451 * Generates a log message for the data path with a supplied prefix and 452 * arguments with a single trailing newline. 453 * 454 * The RTE_LOG_DP_LINE_PREFIX() is a helper that expands logging of a 455 * message with RTE_LOG_DP() prepending the supplied prefix and 456 * arguments appending a single newline to the formatted message. 457 * 458 * @param l 459 * Log level. A value between EMERG (1) and DEBUG (8). The short name 460 * is expanded by the macro, so it cannot be an integer value. 461 * @param t 462 * The log type, for example, EAL. The short name is expanded by the 463 * macro, so it cannot be an integer value. 464 * @param prefix 465 * The prefix format string. 466 * @param args 467 * The arguments for the prefix format string. If args contains 468 * multiple arguments use RTE_LOG_COMMA to defer expansion. 469 * @param ... 470 * The fmt string, as in printf(3), followed by the variable arguments 471 * required by the format. 472 */ 473 #define RTE_LOG_DP_LINE_PREFIX(l, t, prefix, args, ...) do { \ 474 RTE_LOG_CHECK_NO_NEWLINE(RTE_FMT_HEAD(prefix __VA_ARGS__ ,)); \ 475 RTE_LOG_DP(l, t, RTE_FMT(prefix RTE_FMT_HEAD(__VA_ARGS__ ,) "\n", \ 476 args RTE_LOG_COMMA RTE_FMT_TAIL(__VA_ARGS__ ,))); \ 477 } while (0) 478 479 #define RTE_LOG_REGISTER_IMPL(type, name, level) \ 480 int type; \ 481 RTE_INIT(__##type) \ 482 { \ 483 type = rte_log_register_type_and_pick_level(name, RTE_LOG_##level); \ 484 if (type < 0) \ 485 type = RTE_LOGTYPE_EAL; \ 486 } 487 488 /** 489 * Register a dynamic log type in constructor context with its name and level. 490 * 491 * It is a wrapper macro for declaring the logtype, register the log and 492 * sets it's level in the constructor context. 493 * 494 * @param type 495 * The log type identifier 496 * @param name 497 * Name for the log type to be registered 498 * @param level 499 * Log level. A value between EMERG (1) and DEBUG (8). 500 */ 501 #define RTE_LOG_REGISTER(type, name, level) \ 502 RTE_LOG_REGISTER_IMPL(type, RTE_STR(name), level) 503 504 /** 505 * This is an equivalent to RTE_LOG_REGISTER, but relying on the build system 506 * to select the right format for the logtype. 507 */ 508 #define RTE_LOG_REGISTER_DEFAULT(type, level) \ 509 RTE_LOG_REGISTER_IMPL(type, RTE_STR(RTE_LOG_DEFAULT_LOGTYPE), level) 510 511 /** 512 * This is an equivalent to RTE_LOG_REGISTER, but relying on the build system 513 * to select the right prefix for the logtype. 514 */ 515 #define RTE_LOG_REGISTER_SUFFIX(type, suffix, level) \ 516 RTE_LOG_REGISTER_IMPL(type, \ 517 RTE_STR(RTE_LOG_DEFAULT_LOGTYPE) "." RTE_STR(suffix), level) 518 519 #ifdef __cplusplus 520 } 521 #endif 522 523 #endif /* _RTE_LOG_H_ */ 524