1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2023 Intel Corporation. 3 4Log Library 5=========== 6 7The DPDK Log library provides the logging functionality for other DPDK libraries and drivers. 8By default, in a Linux application, logs are sent to syslog and also to the console. 9On FreeBSD and Windows applications, logs are sent only to the console. 10However, the log function can be overridden by the user to use a different logging mechanism. 11 12Log Levels 13---------- 14 15Log messages from apps and libraries are reported with a given level of severity. 16These levels, specified in ``rte_log.h`` are (from most to least important): 17 18#. Emergency 19#. Alert 20#. Critical 21#. Error 22#. Warning 23#. Notice 24#. Information 25#. Debug 26 27At runtime, only messages of a configured level or above (i.e. of higher importance) 28will be emitted by the application to the log output. 29That level can be configured either by the application calling the relevant APIs from the logging library, 30or by the user passing the ``--log-level`` parameter to the EAL via the application. 31 32Setting Global Log Level 33~~~~~~~~~~~~~~~~~~~~~~~~ 34 35To adjust the global log level for an application, 36just pass a numeric level or a level name to the ``--log-level`` EAL parameter. 37For example:: 38 39 /path/to/app --log-level=error 40 41 /path/to/app --log-level=debug 42 43 /path/to/app --log-level=5 # warning 44 45Within an application, the log level can be similarly set using the ``rte_log_set_global_level`` API. 46 47Setting Log Level for a Component 48~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 49 50In some cases, for example, for debugging purposes, 51it may be desirable to increase or decrease the log level for only a specific component, or set of components. 52To facilitate this, the ``--log-level`` argument also accepts an, optionally wildcarded, component name, 53along with the desired level for that component. 54For example:: 55 56 /path/to/app --log-level=lib.eal:crit 57 58 /path/to/app --log-level=lib.*:warning 59 60Within an application, the same result can be got using the ``rte_log_set_level_pattern()`` or ``rte_log_set_level_regex()`` APIs. 61 62Using Logging APIs to Generate Log Messages 63------------------------------------------- 64 65To output log messages, ``rte_log()`` API function should be used. 66As well as the log message, ``rte_log()`` takes two additional parameters: 67 68* The log level 69* The log component type 70 71The log level is a numeric value as discussed above. 72The component type is a unique id that identifies the particular DPDK component to the logging system. 73To get this id, each component needs to register itself at startup, 74using the macro ``RTE_LOG_REGISTER_DEFAULT``. 75This macro takes two parameters, with the second being the default log level for the component. 76The first parameter, called "type", the name of the "logtype", or "component type" variable used in the component. 77This variable will be defined by the macro, and should be passed as the second parameter in calls to ``rte_log()``. 78In general, most DPDK components define their own logging macros to simplify the calls to the log APIs. 79They do this by: 80 81* Hiding the component type parameter inside the macro so it never needs to be passed explicitly. 82* Using the log-level definitions given in ``rte_log.h`` to allow short textual names to be used in 83 place of the numeric log levels. 84 85The following code is taken from ``rte_dmadev.c`` and shows the log registration, 86and subsequent definition of a shortcut logging macro. 87It can be used as a template for any new components using DPDK logging. 88 89.. code:: C 90 91 RTE_LOG_REGISTER_DEFAULT(rte_dma_logtype, INFO); 92 #define RTE_DMA_LOG(level, ...) \ 93 rte_log(RTE_LOG_ ## level, rte_dma_logtype, RTE_FMT("dma: " \ 94 RTE_FMT_HEAD(__VA_ARGS__,) "\n", RTE_FMT_TAIL(__VA_ARGS__,))) 95 96.. note:: 97 98 Because the log registration macro provides the logtype variable definition, 99 it should be placed near the top of the C file using it. 100 If not, the logtype variable should be defined as an "extern int" near the top of the file. 101 102 Similarly, if logging is to be done by multiple files in a component, 103 only one file should register the logtype via the macro, 104 and the logtype should be defined as an "extern int" in a common header file. 105 Any component-specific logging macro should similarly be defined in that header. 106 107Throughout the dmadev library, all logging calls are therefore of the form: 108 109.. code:: C 110 111 RTE_DMA_LOG(ERR, "Name can't be NULL"); 112 113 RTE_DMA_LOG(WARNING, "Device %d already started", dev_id); 114