[PATCH 18/18] doc: Update logging documentation

[Sean Anderson]

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 at gmail.com>
---

 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