logger: Describe runtime logger trace filtration usage

Each mechanism in logger tool chould be described in sof-dox.

Signed-off-by: Karol Trzcinski <karolx.trzcinski@linux.intel.com>

Author: ktrzcinx

developer_guides/debugability/logger/index.rst

@@ -36,6 +36,7 @@ Usage sof-logger <option(s)> <file(s)>
 -v ver_file    Enable checking the firmware version with the ver_file file instead of the default: "/sys/kernel/debug/sof/fw_version"
 -s			       Take a snapshot of state
 -r			       Less formatted output for chained log processors
+-F options		Update trace filtering
 -d			       Dump ldc information
 
 Examples:
@@ -120,3 +121,67 @@ Examples:
   .. code-block:: bash
 
      sof-logger -l ldc_file -d
+
+
+Trace filtering
+***************
+
+It's possible to change current logs level for any instance of component in
+runtime. To do so, use `-F` option, where `options` have
+following format:
+
+   <log_level>=<component1>[, <component2>]
+
+Where *<log_level>* is one of:
+
+- ``c`` / ``critical``
+- ``e`` / ``error``
+- ``w`` / ``warning``
+- ``i`` / ``info``
+- ``d`` / ``debug``
+- ``v`` / ``verbose``
+
+After **=** character, there is a list of component, separated with comma.
+Each components starts with *name* description followed by optional part with
+*instance* description.
+
+List of possible components names comes from UUID declaration,
+see :ref:`uuid-api` for more detailed information.
+Try use ``-d`` flag in logger to list each component names.
+There is also a special name - ``*`` - used to apply given trace
+level to each component.
+
+Instance description may have one of following form:
+
+- ``*`` - each component instance with given *name*
+- ``X`` - only for *name* equal *pipe*, then apply to pipe component
+- ``X.*`` - update each component on selected pipeline *X*
+- ``X.Y`` - component with id *Y* on pipeline *X*
+
+Trace levels changes works in same order as options given in command line,
+and new set overwrites old value. It allows to easily enable verbose logs only
+for selected components and keeping lowest possible log level (critical) for
+others, example:
+
+   sof-logger -l ldc_file -t -Fcritical=* -Fverbose="dai*, volume1.1"
+
+Similar example may be prepared for components on particular pipeline:
+
+   sof-loggerr -l ldc_file -t -Fcritical=* 1.* -Fverbose=dai1.1
+
+
+Detailed description
+--------------------
+
+Filtration mechanism is realized on firmware side, so after change the log level
+to verbose for each component, then DSP may be overhelmed by tracing.
+
+Communication between firmware and logger is realized through driver debug file
+systems.
+Logger writes to ``sys/kernel/debug/sof/filter`` new trace settings,
+which will be used to create *IPC* message.
+Simple text data format is used:
+
+``uuid1_id pipe1_id comp1_id log1_level [; uuid2_id pipe2_id comp2_id log2_level]\n``
+
+Any unimportant field, except for ``log_level``, can be set to ``-1``.