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 <sean...@gmail.com> > Reviewed-by: Simon Glass <s...@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 > ----------- >