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,70 @@ 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 with following argument 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* 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 component names from `ldc` file content.
+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
+- ``X.*`` - each component on selected pipeline *X*
+- ``X.Y`` - component on pipeline *X* with id *Y*
+
+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 -Fc=* -Fv=*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.
+
+Core functionality is provided by DSP, so filtration does not work in offline
+mode - during conversion previously saved input file.
+
+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 with new trace levels.
+Simple text data format is used:
+
+``log1_level uuid1_id pipe1_id comp1_id; [log2_level uuid2_id pipe2_id comp2_id;]\n``
+
+Unused uuid_id should be set here to 0, other unused fields should be set to -1.
+``log_level`` always must be set to valid value - represents ``LOG_LEVEL_*``
+defines values.