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