Skip to content
Snippets Groups Projects
Commit 1ecb6beb authored by Heinrich Schuchardt's avatar Heinrich Schuchardt :speech_balloon: Committed by Tom Rini
Browse files

doc: remove redundant doc/README.log 


doc/README.log was already moved to doc/develop/logging.rst but has been
recreated by an incorrect merge.

Signed-off-by: Heinrich Schuchardt's avatarHeinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass's avatarSimon Glass <sjg@chromium.org>
parent a4326612
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 0 additions and 283 deletions
doc/README.log deleted 100644 → 0
+ 0
− 283
View file @ a4326612
Logging in U-Boot
=================
Introduction
------------
U-Boot's internal operation involves many different steps and actions. From
setting up the board to displaying a start-up screen to loading an Operating
System, there are many component parts each with many actions.
Most of the time this internal detail is not useful. Displaying it on the
console would delay booting (U-Boot's primary purpose) and confuse users.
But for digging into what is happening in a particular area, or for debugging
a problem it is often useful to see what U-Boot is doing in more detail than
is visible from the basic console output.
U-Boot's logging feature aims to satisfy this goal for both users and
developers.
Logging levels
--------------
There are a number logging levels available, in increasing order of verbosity:
LOGL_EMERG - Printed before U-Boot halts
LOGL_ALERT - Indicates action must be taken immediate or U-Boot will crash
LOGL_CRIT - Indicates a critical error that will cause boot failure
LOGL_ERR - Indicates an error that may cause boot failure
LOGL_WARNING - Warning about an unexpected condition
LOGL_NOTE - Important information about progress
LOGL_INFO - Information about normal boot progress
LOGL_DEBUG - Debug information (useful for debugging a driver or subsystem)
LOGL_DEBUG_CONTENT - Debug message showing full message content
LOGL_DEBUG_IO - Debug message showing hardware I/O access
Logging category
----------------
Logging can come from a wide variety of places within U-Boot. Each log message
has a category which is intended to allow messages to be filtered according to
their source.
The following main categories are defined:
LOGC_NONE - Unknown category (e.g. a debug() statement)
UCLASS_... - Related to a particular uclass (e.g. UCLASS_USB)
LOGC_ARCH - Related to architecture-specific code
LOGC_BOARD - Related to board-specific code
LOGC_CORE - Related to core driver-model support
LOGC_DT - Related to device tree control
LOGC_EFI - Related to EFI implementation
Enabling logging
----------------
The following options are used to enable logging at compile time:
CONFIG_LOG - Enables the logging system
CONFIG_LOG_MAX_LEVEL - Max log level to build (anything higher is compiled
out)
CONFIG_LOG_CONSOLE - Enable writing log records to the console
If CONFIG_LOG is not set, then no logging will be available.
The above have SPL and TPL versions also, e.g. CONFIG_SPL_LOG_MAX_LEVEL and
CONFIG_TPL_LOG_MAX_LEVEL.
Temporary logging within a single file
--------------------------------------
Sometimes it is useful to turn on logging just in one file. You can use this:
#define LOG_DEBUG
to enable building in of all logging statements in a single file. Put it at
the top of the file, before any #includes. This overrides any log-level setting
in U-Boot, including CONFIG_LOG_DEFAULT_LEVEL, but just for that file.
Convenience functions
---------------------
A number of convenience functions are available to shorten the code needed
for logging:
log_err(_fmt...)
log_warning(_fmt...)
log_notice(_fmt...)
log_info(_fmt...)
log_debug(_fmt...)
log_content(_fmt...)
log_io(_fmt...)
With these the log level is implicit in the name. The category is set by
LOG_CATEGORY, which you can only define once per file, above all #includes:
#define LOG_CATEGORY LOGC_ALLOC
or
#define LOG_CATEGORY UCLASS_SPI
Remember that all uclasses IDs are log categories too.
Log commands
------------
The 'log' command provides access to several features:
level - access the default log level
format - access the console log format
rec - output a log record
test - run tests
Type 'help log' for details.
Using DEBUG
-----------
U-Boot has traditionally used a #define called DEBUG to enable debugging on a
file-by-file basis. The debug() macro compiles to a printf() statement if
DEBUG is enabled, and an empty statement if not.
With logging enabled, debug() statements are interpreted as logging output
with a level of LOGL_DEBUG and a category of LOGC_NONE.
The logging facilities are intended to replace DEBUG, but if DEBUG is defined
at the top of a file, then it takes precedence. This means that debug()
statements will result in output to the console and this output will not be
logged.
Logging destinations
--------------------
If logging information goes nowhere then it serves no purpose. U-Boot provides
several possible determinations for logging information, all of which can be
enabled or disabled independently:
console - goes to stdout
syslog - broadcast RFC 3164 messages to syslog servers on UDP port 514
The syslog driver sends the value of environmental variable 'log_hostname' as
HOSTNAME if available.
Log format
----------
You can control the log format using the 'log format' command. The basic
format is:
LEVEL.category,file.c:123-func() message
In the above, file.c:123 is the filename where the log record was generated and
func() is the function name. By default ('log format default') only the
function name and message are displayed on the console. You can control which
fields are present, but not the field order.
Filters
-------
Filters are attached to log drivers to control what those drivers emit. Only
records that pass through the filter make it to the driver.
Filters can be based on several criteria:
- maximum log level
- in a set of categories
- in a set of files
If no filters are attached to a driver then a default filter is used, which
limits output to records with a level less than CONFIG_LOG_MAX_LEVEL.
Logging statements
------------------
The main logging function is:
log(category, level, format_string, ...)
Also debug() and error() will generate log records - these use LOG_CATEGORY
as the category, so you should #define this right at the top of the source
file to ensure the category is correct.
You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This
can be used whenever your function returns an error value:
return log_ret(uclass_first_device(UCLASS_MMC, &dev));
This will write a log record when an error code is detected (a value < 0). This
can make it easier to trace errors that are generated deep in the call stack.
Code size
---------
Code size impact depends largely on what is enabled. The following numbers are
generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in
bytes):
This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0
CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0
The last option turns every debug() statement into a logging call, which
bloats the code hugely. The advantage is that it is then possible to enable
all logging within U-Boot.
To Do
-----
There are lots of useful additions that could be made. None of the below is
implemented! If you do one, please add a test in test/py/tests/test_log.py
Convenience functions to support setting the category:
log_arch(level, format_string, ...) - category LOGC_ARCH
log_board(level, format_string, ...) - category LOGC_BOARD
log_core(level, format_string, ...) - category LOGC_CORE
log_dt(level, format_string, ...) - category LOGC_DT
More logging destinations:
device - goes to a device (e.g. serial)
buffer - recorded in a memory buffer
Convert debug() statements in the code to log() statements
Support making printf() emit log statements a L_INFO level
Convert error() statements in the code to log() statements
Figure out what to do with BUG(), BUG_ON() and warn_non_spl()
Figure out what to do with assert()
Add a way to browse log records
Add a way to record log records for browsing using an external tool
Add commands to add and remove filters
Add commands to add and remove log devices
Allow sharing of printf format strings in log records to reduce storage size
for large numbers of log records
Add a command-line option to sandbox to set the default logging level
Convert core driver model code to use logging
Convert uclasses to use logging with the correct category
Consider making log() calls emit an automatic newline, perhaps with a logn()
function to avoid that
Passing log records through to linux (e.g. via device tree /chosen)
Provide a command to access the number of log records generated, and the
number dropped due to them being generated before the log system was ready.
Add a printf() format string pragma so that log statements are checked properly
Enhance the log console driver to show level / category / file / line
information
Add a command to add new log records and delete existing records.
Provide additional log() functions - e.g. logc() to specify the category
--
Simon Glass <sjg@chromium.org>
15-Sep-17
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Imprint & Privacy Policy