From mboxrd@z Thu Jan 1 00:00:00 1970 From: Sean Anderson Date: Tue, 6 Oct 2020 16:38:10 -0400 Subject: [PATCH 18/18] doc: Update logging documentation In-Reply-To: <002b171a-b73e-6832-8e1a-bede152215ee@gmx.de> References: <20201006191610.761899-1-seanga2@gmail.com> <20201006191610.761899-19-seanga2@gmail.com> <002b171a-b73e-6832-8e1a-bede152215ee@gmx.de> Message-ID: List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de On 10/6/20 4:34 PM, Heinrich Schuchardt wrote: > On 10/6/20 9:16 PM, 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 >> --- >> >> doc/develop/logging.rst | 42 +++++++++++++++++++++++++++++------------ >> 1 file changed, 30 insertions(+), 12 deletions(-) >> >> diff --git a/doc/develop/logging.rst b/doc/develop/logging.rst >> index 6a22062073..8b6237f829 100644 >> --- a/doc/develop/logging.rst >> +++ b/doc/develop/logging.rst >> @@ -174,18 +174,45 @@ 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 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: >> >> -* maximum log level >> +* 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. >> >> +Adding Filters >> +~~~~~~~~~~~~~~ >> + >> +To add new filters at runtime, use the 'log filter-add' command. For example, to >> +filter messages from the SPI subsystem, run:: > > Does "filter" mean I see only messages from SPI or does this mean I see > no messages from SPI? If you mean suppress, please, use that word or > something similar. Ok. > >> + >> + log filter-add -D -c spi >> + >> +You will also need to allow everything else to emit messages (because the >> +default filter no longer applies):: >> + >> + log filter-add -A -l debug > > Thank you for starting the documenation. > > Unfortunately after reading the lines above I have no clue what the > meaning of -D -A -c -l are. These options are currently documented in the help text for log. Should they be added here? I am concerned that duplicating documentation will result in drift over time. > > Users will need a complete description of the log command with all > 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 >> + 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'. Here is my suggestion of where to find a complete list of options. --Sean >> >> Logging statements >> ------------------ >> @@ -259,8 +286,6 @@ 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 >> @@ -268,10 +293,6 @@ 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,9 +303,6 @@ 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 >> >