[U-Boot,v3,14/14] log: Add documentation

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

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

Hi Lukasz,

On 21 November 2017 at 18:19, Lukasz Majewski <lukma@denx.de> wrote:
> 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

[..]

>> +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).

OK I will send a patch for that.

>
>> +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.
>> +

[..]

>
> As I said before - this is a great piece of SW.

Great, thanks!

>
> Reviewed-by: Lukasz Majewski <lukma@denx.de>
>
> Best regards,
>
> Lukasz Majewski

Regards,
Simon