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