Skip to content
Permalink
Browse files

doc: add custom logger frontend description

Describe how custom logger is enabled and what it does.

Signed-off-by: Marcin Szymczyk <marcin.szymczyk@nordicsemi.no>
  • Loading branch information...
masz-nordic authored and carlescufi committed Jun 24, 2019
1 parent a0c0996 commit bddb3f364142399e547050d8e0c46e807e4d9008
Showing with 24 additions and 11 deletions.
  1. +24 −11 doc/reference/logging/index.rst
@@ -8,26 +8,28 @@ 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:

- Deferred logging reduces the time needed to log a message by shifting time
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
====

0 comments on commit bddb3f3

Please sign in to comment.
You can’t perform that action at this time.