diff --git a/doc/api/api.rst b/doc/api/api.rst index 4b8b75e2179..4ca6df22448 100644 --- a/doc/api/api.rst +++ b/doc/api/api.rst @@ -22,5 +22,6 @@ The use of the Zephyr APIs is the same for all platforms and boards. device.rst io_interfaces.rst event_logger.rst + system_log.rst power_management_api diff --git a/doc/api/system_log.rst b/doc/api/system_log.rst new file mode 100644 index 00000000000..10cbf904437 --- /dev/null +++ b/doc/api/system_log.rst @@ -0,0 +1,95 @@ +.. _system_log: + +System Log API +################# + +.. contents:: + :depth: 1 + :local: + :backlinks: top + +System Log +************ + +.. doxygengroup:: system_log + :project: Zephyr + :content-only: + +The system log API provides a common interface to process messages issued by +developers. These messages are currently printed on the terminal but the API is +defined in a generic way. + +This API can be deactivated through the Kconfig options, see +:ref:`global_kconfig`. +This aproach prevents impacting image size and execution time when the system +log is not needed. + +Each of the four ``SYS_LOG_X`` macros correspond to a different logging level, +The logging macros activate when their logging level or higher is set. + +There are two configuration categories: configurations per module and global +configurations. When logging is enabled globally, it works for modules. However, +modules can disable logging locally. Every module can specify its own logging +level. The module must define the :c:macro:`SYS_LOG_LEVEL` macro before +including the :file:`` header file to do so. Unless a global +override is set, the module logging level will be honored. The global override +can only increase the logging level. It cannot be used to lower module logging +levels that were previously set higher. + +You can set a local domain to differentiate messages. When no domain is set, +then the ``[general]`` domain appears before the message. Define the +:c:macro:`SYS_LOG_DOMAIN` macro before including the :file:`misc/sys_log.h` +header file to set the domain. + +When several macros are active, the printed messages can be differentiated in +two ways: by a tag printed before the message or by ANSI colors. See the +:option:`CONFIG_SYS_LOG_SHOW_TAGS` and :option:`CONFIG_SYS_LOG_SHOW_COLOR` +Kconfig options for more information. + +Define the :c:macro:`SYS_LOG_NO_NEWLINE` macro before including the +:file:`misc/sys_log.h` header file to prevent macros appending a new line at the +end of the logging message. + +.. _global_kconfig: + +Global Kconfig Options +********************** + +These options can be found in the following path :file:`misc/Kconfig`. + +:option:`CONFIG_SYS_LOG`: Global switch, turns on/off all system logging. + +:option:`CONFIG_SYS_LOG_DEFAULT_LEVEL`: Default level, sets the logging level +used by modules that are not setting their own logging level. + +:option:`CONFIG_SYS_LOG_SHOW_TAGS`: Globally sets whether level tags will be +shown on log or not. + +:option:`CONFIG_SYS_LOG_SHOW_COLOR`: Globally sets whether ANSI colors will be +used by the system log. + +:option:`CONFIG_SYS_LOG_OVERRIDE_LEVEL`: It overrides module logging level when +it is not set or set lower than the override value. + +Example +******* + +The following macro: + + .. code-block:: c + + SYS_LOG_WRN("hi!"); + +Will produce: + + .. code-block:: console + + [general] [WRN] main: Hi! + +For the above example to work at least one of the following settings must be +true: + +- The :option:`CONFIG_SYS_LOG_DEFAULT_LEVEL` is set to 2 or above and module + configuration is not set. +- The module configuration is set to 2 or above. +- The :option:`CONFIG_SYS_LOG_OVERRIDE_LEVEL` is set to 2 or above. diff --git a/include/misc/sys_log.h b/include/misc/sys_log.h index ee0fcd87ae2..2826174cda0 100644 --- a/include/misc/sys_log.h +++ b/include/misc/sys_log.h @@ -40,6 +40,11 @@ extern "C" { #define SYS_LOG_LEVEL CONFIG_SYS_LOG_OVERRIDE_LEVEL #endif +/** + * @brief System Log + * @defgroup system_log System Log + * @{ + */ #if defined(CONFIG_SYS_LOG) && (SYS_LOG_LEVEL > SYS_LOG_LEVEL_OFF) #define IS_SYS_LOG_ACTIVE 1 @@ -144,7 +149,7 @@ extern "C" { * active. it's meant to report severe errors, such as those from which it's * not possible to recover. * - * @param A string optionally containing printk valid conversion specifier, + * @param ... A string optionally containing printk valid conversion specifier, * followed by as many values as specifiers. */ #define SYS_LOG_ERR(...) { ; } @@ -161,7 +166,7 @@ extern "C" { * It's meant to register messages related to unusual situations that are * not necesarily errors. * - * @param A string optionally containing printk valid conversion specifier, + * @param ... A string optionally containing printk valid conversion specifier, * followed by as many values as specifiers. */ #define SYS_LOG_WRN(...) { ; } @@ -176,7 +181,7 @@ extern "C" { * @details available if SYS_LOG_LEVEL is SYS_LOG_LEVEL_INFO or higher. * It's meant to write generic user oriented messages. * - * @param A string optionally containing printk valid conversion specifier, + * @param ... A string optionally containing printk valid conversion specifier, * followed by as many values as specifiers. */ #define SYS_LOG_INF(...) { ; } @@ -191,11 +196,14 @@ extern "C" { * @details highest logging level, available if SYS_LOG_LEVEL is * SYS_LOG_LEVEL_DEBUG. It's meant to write developer oriented information. * - * @param A string optionally containing printk valid conversion specifier, + * @param ... A string optionally containing printk valid conversion specifier, * followed by as many values as specifiers. */ #define SYS_LOG_DBG(...) { ; } #endif +/** + * @} + */ #ifdef __cplusplus }