From mboxrd@z Thu Jan 1 00:00:00 1970 From: Sean Anderson Date: Tue, 6 Oct 2020 15:16:10 -0400 Subject: [PATCH 18/18] doc: Update logging documentation In-Reply-To: <20201006191610.761899-1-seanga2@gmail.com> References: <20201006191610.761899-1-seanga2@gmail.com> Message-ID: <20201006191610.761899-19-seanga2@gmail.com> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de 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:: + + 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 + +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'. + 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 -- 2.28.0