On Mon, 20 Nov 2017 15:33:35 -0700 Simon Glass sjg@chromium.org wrote:
Add documentation for the log system.
Signed-off-by: Simon Glass sjg@chromium.org Reviewed-by: Bin Meng bmeng.cn@gmail.com
Changes in v3:
- Rebase to master
Changes in v2:
- Drop the special log() functions from the README
doc/README.log | 214 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 doc/README.log
diff --git a/doc/README.log b/doc/README.log new file mode 100644 index 00000000000..f653fe7d797 --- /dev/null +++ b/doc/README.log @@ -0,0 +1,214 @@ +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
+Enabling logging +----------------
+The following options are used to enable logging at compile time:
- CONFIG_LOG - Enables the logging system
- CONFIG_MAX_LOG_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 versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL.
+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
+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.
+Code size +---------
+Code size impact depends largely on what is enabled. The following numbers are +for snow, which is a Thumb-2 board:
+This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0
It would be more informative to add units (KiB, B).
+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
+Convenience functions to support a category defined for a single file, for +example:
- #define LOG_CATEGORY UCLASS_USB
+all of these can use LOG_CATEGORY as the category, and a log level +corresponding to the function name:
- logc(level, format_string, ...)
+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
As I said before - this is a great piece of SW.
Reviewed-by: Lukasz Majewski lukma@denx.de
Best regards,
Lukasz Majewski
--
DENX Software Engineering GmbH, Managing Director: Wolfgang Denk HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd@denx.de