diff --git a/doc/reference/logging/index.rst b/doc/reference/logging/index.rst index e869e03afa1..1fa655a30cc 100644 --- a/doc/reference/logging/index.rst +++ b/doc/reference/logging/index.rst @@ -8,9 +8,10 @@ Logging :depth: 2 The logger API provides a common interface to process messages issued by -developers. These messages are processed by active backends. Currently only the -UART backend is available. However, a generic backend interface exists and more -backends can be added and easily plugged in to the system. +developers. Messages are passed through a frontend and are then +processed by active backends. +Custom frontend and backends can be used if needed. +Default configuration uses built-in frontend and UART backend. Summary of logger features: @@ -18,16 +19,17 @@ Summary of logger features: consuming operations to a known context instead of processing and sending the log message when called. - Multiple backends supported (up to 9 backends). +- Custom frontend supported. - Compile time filtering on module level. - Run time filtering independent for each backend. - Additional run time filtering on module instance level. - Timestamping with user provided function. -- Dedicated API for dumping data -- Dedicated API for handling transient strings +- Dedicated API for dumping data. +- Dedicated API for handling transient strings. - Panic support - in panic mode logger switches to blocking, synchronous processing. - Printk support - printk message can be redirected to the logger. -- Design ready for multi-domain/multi-processor system +- Design ready for multi-domain/multi-processor system. Logger API is highly configurable at compile time as well as at run time. Using Kconfig options (see :ref:`logger_kconfig`) logs can be gradually removed from @@ -67,8 +69,8 @@ Each module which is using the logger must specify its unique name and register itself to the logger. If module consists of more than one file, registration is performed in one file but each file must define a module name. -Logger is designed to be thread safe and minimizes time needed to log the -message. Time consuming operations like string formatting or access to the +Logger's default frontend is designed to be thread safe and minimizes time needed +to log the message. Time consuming operations like string formatting or access to the transport are not performed by default when logger API is called. When logger API is called a message is created and added to the list. Dedicated, configurable pool of log messages is used. There are 2 types of messages: @@ -148,6 +150,8 @@ log_strdup(). :option:`CONFIG_LOG_DOMAIN_ID`: Domain ID. Valid in multi-domain systems. +:option:`CONFIG_LOG_FRONTEND`: Redirect logs to a custom frontend. + :option:`CONFIG_LOG_BACKEND_UART`: Enabled build-in UART backend. :option:`CONFIG_LOG_BACKEND_SHOW_COLOR`: Enables coloring of errors (red) @@ -349,10 +353,10 @@ Logger consists of 3 main parts: Log message is generated by a source of logging which can be a module or instance of a module. -Frontend -======== +Default Frontend +================ -Frontend is engaged when logger API is called in a source of logging (e.g. +Default frontend is engaged when logger API is called in a source of logging (e.g. :c:macro:`LOG_INF`) and is responsible for filtering a message (compile and run time), allocating buffer for the message, creating the message and putting that message into the list of pending messages. Since logger API can be called in an @@ -399,6 +403,15 @@ particular source will be buffered. | INF | ERR | INF | OFF | ... | OFF | +------+------+------+------+-----+------+ +Custom Frontend +=============== + +Custom frontend is enabled using :option:`CONFIG_LOG_FRONTEND`. Logs are redirected +to functions declared in :zephyr_file:`include/logging/log_frontend.h`. +This may be required in very time-sensitive cases, but this hurts +logger functionality. All features from default frontend, core and all backends +are not used. + Core ====