@@ -51,6 +51,7 @@ INPUT = @TOPDIR@/doc/api/doxy-api-index.md \
@TOPDIR@/lib/kni \
@TOPDIR@/lib/kvargs \
@TOPDIR@/lib/latencystats \
+ @TOPDIR@/lib/log \
@TOPDIR@/lib/lpm \
@TOPDIR@/lib/mbuf \
@TOPDIR@/lib/member \
@@ -443,9 +443,7 @@ Per-lcore variables are implemented using *Thread Local Storage* (TLS) to provid
Logs
~~~~
-A logging API is provided by EAL.
-By default, in a Linux application, logs are sent to syslog and also to the console.
-However, the log function can be overridden by the user to use a different logging mechanism.
+While originally part of EAL, DPDK logging functionality is now provided by the :ref:`Log_Library`.
Trace and Debug Functions
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -12,6 +12,7 @@ Programmer's Guide
overview
source_org
env_abstraction_layer
+ log_lib
service_cores
trace_lib
rcu_lib
new file mode 100644
@@ -0,0 +1,115 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2023 Intel Corporation.
+
+.. _log_library:
+
+Log Library
+============
+
+The DPDK Log library provides the logging functionality for other DPDK libraries and drivers.
+By default, in a Linux application, logs are sent to syslog and also to the console.
+On FreeBSD and Windows applications, logs are sent only to the console.
+However, the log function can be overridden by the user to use a different logging mechanism.
+
+Log Levels
+-----------
+
+Log messages from apps and libraries are reported with a given level of severity.
+These levels, specified in ``rte_log.h`` are (from most to least important):
+
+#. Emergency
+#. Alert
+#. Critical
+#. Error
+#. Warning
+#. Notice
+#. Information
+#. Debug
+
+At runtime, only messages of a configured level or above (i.e. of higher importance)
+will be emitted by the application to the log output.
+That level can be configured either by the application calling the relevant APIs from the logging library,
+or by the user passing the ``--log-level`` parameter to the EAL via the application.
+
+Setting Global Log Level
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To adjust the global log level for an application,
+just pass a numeric level or a level name to the ``--log-level`` EAL parameter.
+For example::
+
+ /path/to/app --log-level=error
+
+ /path/to/app --log-level=debug
+
+ /path/to/app --log-level=5 # warning
+
+Within an application, the log level can be similarly set using the ``rte_log_set_global_level`` API.
+
+Setting Log Level for a Component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In some cases, for example, for debugging purposes,
+it may be desirable to increase or decrease the log level for only a specific component, or set of components.
+To facilitate this, the ``--log-level`` argument also accepts an, optionally wildcarded, component name,
+along with the desired level for that component.
+For example::
+
+ /path/to/app --log-level=lib.eal:crit
+
+ /path/to/app --log-level=lib.*:warning
+
+Within an application, the same result can be got using the ``rte_log_set_level_pattern()`` or ``rte_log_set_level_regex()`` APIs.
+
+Using Logging APIs to Generate Log Messages
+--------------------------------------------
+
+To output log messages, ``rte_log()`` API function should be used.
+As well as the log message, ``rte_log()`` takes two additional parameters:
+
+* The log level
+* The log component type
+
+The log level is a numeric value as discussed above.
+The component type is a unique id that identifies the particular DPDK component to the logging system.
+To get this id, each component needs to register itself at startup,
+using the macro ``RTE_LOG_REGISTER_DEFAULT``.
+This macro takes two parameters, with the second being the default log level for the component.
+The first parameter, called "type", the name of the "logtype", or "component type" variable used in the component.
+This variable will be defined by the macro, and should be passed as the second parameter in calls to ``rte_log()``.
+In general, most DPDK components define their own logging macros to simplify the calls to the log APIs.
+They do this by:
+
+* Hiding the component type parameter inside the macro so it never needs to be passed explicitly.
+* Using the log-level definitions given in ``rte_log.h`` to allow short textual names to be used in
+ place of the numeric log levels.
+
+The following code is taken from ``rte_dmadev.c`` and shows the log registration,
+and subsequent definition of a shortcut logging macro.
+It can be used as a template for any new components using DPDK logging.
+
+.. code:: C
+
+ RTE_LOG_REGISTER_DEFAULT(rte_dma_logtype, INFO);
+ #define RTE_DMA_LOG(level, ...) \
+ rte_log(RTE_LOG_ ## level, rte_dma_logtype, RTE_FMT("dma: " \
+ RTE_FMT_HEAD(__VA_ARGS__,) "\n", RTE_FMT_TAIL(__VA_ARGS__,)))
+
+.. note::
+
+ Because the log registration macro provides the logtype variable definition,
+ it should be placed near the top of the C file using it.
+ If not, the logtype variable should be defined as an "extern int" near the top of the file.
+
+ Similarly, if logging is to be done by multiple files in a component,
+ only one file should register the logtype via the macro,
+ and the logtype should be defined as an "extern int" in a common header file.
+ Any component-specific logging macro should similarly be defined in that header.
+
+Throughout the dmadev library, all logging calls are therefore of the form:
+
+.. code:: C
+
+ RTE_DMA_LOG(ERR, "Name can't be NULL");
+
+ RTE_DMA_LOG(WARNING, "Device %d already started", dev_id);
@@ -39,7 +39,7 @@
#include "eal_options.h"
#include "eal_filesystem.h"
#include "eal_private.h"
-#include "eal_log.h"
+#include "log_internal.h"
#ifndef RTE_EXEC_ENV_WINDOWS
#include "eal_trace.h"
#endif
@@ -152,13 +152,6 @@ int rte_eal_tailqs_init(void);
*/
int rte_eal_intr_init(void);
-/**
- * Close the default log stream
- *
- * This function is private to EAL.
- */
-void rte_eal_log_cleanup(void);
-
/**
* Init alarm mechanism. This is to allow a callback be called after
* specific time.
@@ -18,7 +18,6 @@ sources += files(
'eal_common_interrupts.c',
'eal_common_launch.c',
'eal_common_lcore.c',
- 'eal_common_log.c',
'eal_common_mcfg.c',
'eal_common_memalloc.c',
'eal_common_memory.c',
@@ -27,7 +27,6 @@ headers += files(
'rte_keepalive.h',
'rte_launch.h',
'rte_lcore.h',
- 'rte_log.h',
'rte_malloc.h',
'rte_mcslock.h',
'rte_memory.h',
@@ -49,10 +49,10 @@
#include "eal_hugepages.h"
#include "eal_memcfg.h"
#include "eal_trace.h"
-#include "eal_log.h"
#include "eal_options.h"
#include "eal_vfio.h"
#include "hotplug_mp.h"
+#include "log_internal.h"
#define MEMSIZE_IF_NO_HUGE_PAGE (64ULL * 1024ULL * 1024ULL)
@@ -11,7 +11,6 @@ sources += files(
'eal_hugepage_info.c',
'eal_interrupts.c',
'eal_lcore.c',
- 'eal_log.c',
'eal_memalloc.c',
'eal_memory.c',
'eal_thread.c',
@@ -22,7 +22,7 @@ subdir(exec_env)
subdir(arch_subdir)
-deps += ['kvargs']
+deps += ['log', 'kvargs']
if not is_windows
deps += ['telemetry']
endif
@@ -140,21 +140,6 @@ DPDK_23 {
rte_lcore_iterate;
rte_lcore_to_cpu_id;
rte_lcore_to_socket_id;
- rte_log;
- rte_log_can_log;
- rte_log_cur_msg_loglevel;
- rte_log_cur_msg_logtype;
- rte_log_dump;
- rte_log_get_global_level;
- rte_log_get_level;
- rte_log_get_stream;
- rte_log_list_types;
- rte_log_register;
- rte_log_register_type_and_pick_level;
- rte_log_set_global_level;
- rte_log_set_level;
- rte_log_set_level_pattern;
- rte_log_set_level_regexp;
rte_malloc;
rte_malloc_dump_heaps;
rte_malloc_dump_stats;
@@ -225,7 +210,6 @@ DPDK_23 {
rte_mp_request_async;
rte_mp_request_sync;
rte_mp_sendmsg;
- rte_openlog_stream;
rte_rand;
rte_rand_max;
rte_realloc;
@@ -299,7 +283,6 @@ DPDK_23 {
rte_vfio_noiommu_is_enabled; # WINDOWS_NO_EXPORT
rte_vfio_release_device; # WINDOWS_NO_EXPORT
rte_vfio_setup_device; # WINDOWS_NO_EXPORT
- rte_vlog;
rte_zmalloc;
rte_zmalloc_socket;
@@ -26,8 +26,8 @@
#include "eal_firmware.h"
#include "eal_hugepages.h"
#include "eal_trace.h"
-#include "eal_log.h"
#include "eal_windows.h"
+#include "log_internal.h"
#define MEMSIZE_IF_NO_HUGE_PAGE (64ULL * 1024ULL * 1024ULL)
@@ -12,7 +12,6 @@ sources += files(
'eal_hugepages.c',
'eal_interrupts.c',
'eal_lcore.c',
- 'eal_log.c',
'eal_memalloc.c',
'eal_memory.c',
'eal_mp.c',
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: BSD-3-Clause
# Copyright(c) 2017 Intel Corporation
-includes = [global_inc]
-
+deps += 'log'
sources = files('rte_kvargs.c')
headers = files('rte_kvargs.h')
similarity index 99%
rename from lib/eal/common/eal_common_log.c
rename to lib/log/log.c
@@ -15,8 +15,11 @@
#include <rte_log.h>
#include <rte_per_lcore.h>
-#include "eal_log.h"
-#include "eal_private.h"
+#include "log_internal.h"
+
+#ifdef RTE_EXEC_ENV_WINDOWS
+#define strdup _strdup
+#endif
struct rte_log_dynamic_type {
const char *name;
new file mode 100644
@@ -0,0 +1,12 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2023 Intel Corporation
+ */
+
+#include <rte_common.h>
+#include "log_internal.h"
+
+int
+eal_log_init(__rte_unused const char *id, __rte_unused int facility)
+{
+ return 0;
+}
similarity index 69%
rename from lib/eal/common/eal_log.h
rename to lib/log/log_internal.h
@@ -2,31 +2,43 @@
* Copyright 2021 Mellanox Technologies, Ltd
*/
-#ifndef EAL_LOG_H
-#define EAL_LOG_H
+#ifndef LOG_INTERNAL_H
+#define LOG_INTERNAL_H
#include <stdio.h>
#include <stdint.h>
+#include <rte_compat.h>
/*
* Initialize the default log stream.
*/
+__rte_internal
int eal_log_init(const char *id, int facility);
/*
* Determine where log data is written when no call to rte_openlog_stream.
*/
+__rte_internal
void eal_log_set_default(FILE *default_log);
/*
* Save a log option for later.
*/
+__rte_internal
int eal_log_save_regexp(const char *regexp, uint32_t level);
+__rte_internal
int eal_log_save_pattern(const char *pattern, uint32_t level);
/*
* Convert log level to string.
*/
+__rte_internal
const char *eal_log_level2str(uint32_t level);
-#endif /* EAL_LOG_H */
+/*
+ * Close the default log stream
+ */
+__rte_internal
+void rte_eal_log_cleanup(void);
+
+#endif /* LOG_INTERNAL_H */
similarity index 97%
rename from lib/eal/linux/eal_log.c
rename to lib/log/log_linux.c
@@ -8,7 +8,7 @@
#include <rte_log.h>
-#include "eal_log.h"
+#include "log_internal.h"
/*
* default log function
similarity index 93%
rename from lib/eal/windows/eal_log.c
rename to lib/log/log_windows.c
@@ -4,7 +4,7 @@
#include <rte_common.h>
#include <rte_log.h>
-#include "eal_log.h"
+#include "log_internal.h"
/* set the log to default function, called during eal init process. */
int
new file mode 100644
@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2022 Intel Corporation
+
+includes += global_inc
+sources = files(
+ 'log.c',
+ 'log_' + exec_env + '.c'
+)
+headers = files('rte_log.h')
similarity index 100%
rename from lib/eal/include/rte_log.h
rename to lib/log/rte_log.h
new file mode 100644
@@ -0,0 +1,34 @@
+DPDK_23 {
+ global:
+
+ rte_log;
+ rte_log_cur_msg_loglevel;
+ rte_log_cur_msg_logtype;
+ rte_log_can_log;
+ rte_log_dump;
+ rte_log_get_global_level;
+ rte_log_get_level;
+ rte_log_get_stream;
+ rte_log_list_types;
+ rte_log_register;
+ rte_log_register_type_and_pick_level;
+ rte_log_set_global_level;
+ rte_log_set_level;
+ rte_log_set_level_pattern;
+ rte_log_set_level_regexp;
+ rte_openlog_stream;
+ rte_vlog;
+
+ local: *;
+};
+
+INTERNAL {
+ global:
+
+ eal_log_init;
+ eal_log_level2str;
+ eal_log_save_pattern;
+ eal_log_save_regexp;
+ eal_log_set_default;
+ rte_eal_log_cleanup;
+};
@@ -9,6 +9,7 @@
# given as a dep, no need to mention ring. This is especially true for the
# core libs which are widely reused, so their deps are kept to a minimum.
libraries = [
+ 'log',
'kvargs', # eal depends on kvargs
'telemetry', # basic info querying
'eal', # everything depends on eal
@@ -1,8 +1,7 @@
# SPDX-License-Identifier: BSD-3-Clause
# Copyright(c) 2018 Intel Corporation
-includes = [global_inc]
-
+deps += 'log'
sources = files('telemetry.c', 'telemetry_data.c', 'telemetry_legacy.c')
headers = files('rte_telemetry.h')
includes += include_directories('../metrics')