On 17.10.20 20:07, Sean Anderson wrote:
This updates logging documentation with some examples of the new commands added in the previous commits. It also removes some items from the to-do list which have been implemented.
Signed-off-by: Sean Anderson seanga2@gmail.com Reviewed-by: Simon Glass sjg@chromium.org
Changes in v3:
- Fix heading level of Filters section
- Remove a few more already-implemented features from the TODO list
Changes in v2:
- Add a few informational commands
- Clarify wording of filter documentation
- Include enum definitions instead of re-documenting them
- Reorganize log documentation; related sections should now be more proximate
doc/develop/logging.rst | 242 +++++++++++++++++++--------------------- 1 file changed, 115 insertions(+), 127 deletions(-)
diff --git a/doc/develop/logging.rst b/doc/develop/logging.rst index 6a22062073..2b87bc2b4f 100644 --- a/doc/develop/logging.rst +++ b/doc/develop/logging.rst @@ -21,23 +21,13 @@ 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 +There are a number logging levels available.
+.. kernel-doc:: include/log.h
- :identifiers: log_level_t
Logging category
@@ -46,16 +36,8 @@ 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
+.. kernel-doc:: include/log.h
- :identifiers: log_category_t
Enabling logging
@@ -72,7 +54,6 @@ 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
@@ -86,46 +67,8 @@ to enable building in of all logging statements in a single file. Put it at the top of the file, before any #includes.
To actually get U-Boot to output this you need to also set the default logging -level - e.g. set CONFIG_LOG_DEFAULT_LEVEL to 7 (LOGL_DEBUG) or more. Otherwise -debug output is suppressed and will not be generated.
-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, e.g.
-.. code-block:: c
- #define LOG_CATEGORY LOGC_ALLOC
-Remember that all uclasses IDs are log categories too.
-Log command
-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.
+level - e.g. set CONFIG_LOG_DEFAULT_LEVEL to 7 (:c:type:`LOGL_DEBUG`) or more. +Otherwise debug output is suppressed and will not be generated.
Using DEBUG
@@ -142,51 +85,6 @@ 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_MAX_LOG_LEVEL.
Logging statements
@@ -210,6 +108,112 @@ can be used whenever your function returns an error value: 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.
+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, e.g.
+.. code-block:: c
- #define LOG_CATEGORY LOGC_ALLOC
+Remember that all uclasses IDs are log categories too.
+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.
+Filters +-------
+Filters are attached to log drivers to control what those drivers emit. FIlters +can either allow or deny a log message when they match it. Only records which +are allowed by a filter make it to the driver.
+Filters can be based on several criteria:
+* minimum or 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_MAX_LOG_LEVEL.
+Log command +-----------
+The 'log' command provides access to several features:
+* level - get/set the log level +* categories - list log categories
How does the user get the sorted list of all level texts?
+* drivers - list log drivers +* filter-list - list filters +* filter-add - add a new filter +* filter-remove - remove filters +* format - access the console log format +* rec - output a log record
+Type 'help log' for details.
+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 message +is displayed on the console. You can control which fields are present, but not +the field order.
+Adding Filters +~~~~~~~~~~~~~~
+To add new filters at runtime, use the 'log filter-add' command. For example, to +suppress messages from the SPI subsystem, run::
- log filter-add -D -c spi
+You will also need to add another filter to allow other messages (because the +default filter no longer applies)::
- log filter-add -A -l debug
Are level numbers also accepted?
How do you add a file filter?
I would prefer a table with all parameters used for filtering with an explanation, e.g.
-A - allow filter -D - deny filter -c <category> - category to which the filter applies -l <level> - for deny filter deny all messages with a level less or equal <level>, for allow filter allow all messages with a level greater or equal <level> ...
Put the examples under the table of parameters.
Best regards
Heinrich
+To view active filters, use the 'log filter-list' command. Some example output +is::
- => log filter-list
- num policy level categories files
0 deny <=IO spi
An extra space after '<=' would make the output line more readable.
Best regards
Heinrich
1 allow <=DEBUG+Note that filters are processed in-order from top to bottom, not in the order of +their filter number. Filters are added to the top of the list if they deny when +they match, and to the bottom if they allow when they match. For more +information, consult the usage of the 'log' command, by running 'help log'.
Code size
@@ -226,12 +230,11 @@ 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 +implemented! If you do one, please add a test in test/log/log_test.c
Convenience functions to support setting the category:
@@ -253,25 +256,15 @@ 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
@@ -282,12 +275,7 @@ 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 +Add a command to delete existing log records.
Logging API