On Mon, 20 Nov 2017 15:33:35 -0700 Simon Glass <s...@chromium.org> wrote:
> Add documentation for the log system.
>
> Signed-off-by: Simon Glass <s...@chromium.org>
> Reviewed-by: Bin Meng <bmeng...@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 <s...@chromium.org>
> +15-Sep-17
As I said before - this is a great piece of SW.
Reviewed-by: Lukasz Majewski <lu...@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: w...@denx.de
pgpNfuDLikLlD.pgp
Description: OpenPGP digital signature
_______________________________________________ U-Boot mailing list U-Boot@lists.denx.de https://lists.denx.de/listinfo/u-boot
