idf_monitor: add support for filtering options

docs/en/get-started/idf-monitor.rst

@@ -105,6 +105,90 @@ Sometimes you may want to stop new output printed to screen, to see the log befo
 toggle the display (discard all serial data when the display is off) so that you can stop to see the log, and revert
 again quickly without quitting the monitor.
 
+Filtering the Output
+====================
+
+The IDF monitor can be invoked as ``make monitor PRINT_FILTER=""`` with
+specifying a custom ``PRINT_FILTER`` option for filtering outputs. The default
+value is an empty string which means that everything will be printed.
+Restrictions on what to print can be specified as a series of
+``<tag>:<log_level>`` items where ``<tag>`` is the tag string and
+``<log_level>`` is a character from set ``{N, E, W, I, D, V, *}`` referring to
+a level for :doc:`logging <../../api-reference/system/log>`. For example,
+``PRINT_FILTER="tag1:W"`` will match and print (only) the outputs written with
+``ESP_LOGW("tag1", ...)`` or at lower verbosity level, i.e. ``ESP_LOGE("tag1",
+...)``. Not specifying a
+``<log_level>`` or using ``*`` defaults to Verbose level.
+
+.. note::
+   The primary logging is set up at compilation time through the
+   :doc:`logging library<../../api-reference/system/log>`.
+   Output filtering by the IDF monitor is only a secondary solution because
+   one cannot filter something which has been disabled at compilation time.
+   The advantage of the secondary filtering is that one can use various
+   filtering options without recompiling the application.
+
+A restriction applies to tags when one wants to use them together with output
+filtering: they cannot contain spaces, asterisks ``*`` and semicolons ``:``.
+
+If the last line of the output is written without an end of line then the
+output filtering might get confused, i.e. the monitor starts to print the line and only
+later finds out that the line should have not been written. This is a known
+issue and can be avoided by always adding an end of line after printing
+something (especially when no output follows immediately afterwards).
+
+Examples Of Filtering Rules:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Asterisk can be used to match any tags. However, specifying
+  ``PRINT_FILTER="*:I tag1:E"`` will print for ``tag1`` only errors because
+  the rule for ``tag1`` has a precedence over the rule for ``*``.
+- The default (empty) rule is equivalent to ``*:V`` because matching every tag
+  at level Verbose or lower means matching everything.
+- Rule ``"tag1:W tag1:E"`` is equivalent to ``"tag1:E"`` because any
+  consequent occurrence of the same tag name overwrites the previous one.
+- Rule ``"tag1:I tag2:W"`` will print only ``tag1`` at verbosity level Info or
+  lower and ``tag2`` at verbosity level Warning or lower.
+- Rule ``"tag1:I tag2:W tag3:N"`` is essentially equivalent to the previous
+  one because ``tag3:N`` specifies that ``tag3`` should not be printed.
+- ``tag3:N`` in rule ``"tag1:I tag2:W tag3:N *:V"`` is more meaningful because
+  in this context the result will be that ``tag3`` will not be printed,
+  ``tag1`` and ``tag2`` will be at the specified (or lower) verbosity level
+  and everything else will be printed by default.
+- ``"*:N"`` will suppress all outputs even prints made by something else than
+  the logging functions, e.g. ``printf``. For printing those outputs one need
+  to use ``*:E`` or higher verbosity level.
+- Rules ``"tag1:V"``, ``"tag1:v"``, ``"tag1:"``, ``"tag1:*"`` and ``"tag1"``
+  are all equivalent ones.
+
+A More Complex Filtering Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following log snippet was acquired using ``make monitor``::
+
+    load:0x40078000,len:13564
+    entry 0x40078d4c
+    E (31) esp_image: image at 0x30000 has invalid magic byte
+    W (31) esp_image: image at 0x30000 has invalid SPI mode 255
+    E (39) boot: Factory app partition is not bootable
+    I (568) cpu_start: Pro cpu up.
+    I (569) heap_init: Initializing. RAM available for dynamic allocation:
+    I (603) cpu_start: Pro cpu start user code
+    D (309) light_driver: [light_init, 74]:status: 1, mode: 2
+    D (318) vfs: esp_vfs_register_fd_range is successful for range <54; 64) and VFS ID 1
+    I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
+
+The captured output for ``make monitor PRINT_FILTER="wifi esp_image:E light_driver:I"`` is the following::
+
+    E (31) esp_image: image at 0x30000 has invalid magic byte
+    I (328) wifi: wifi driver task: 3ffdbf84, prio:23, stack:4096, core=0
+
+``make monitor PRINT_FILTER="light_driver:D esp_image:N boot:N cpu_start:N vfs:N wifi:N *:V"`` gives the following output::
+
+    load:0x40078000,len:13564
+    entry 0x40078d4c
+    I (569) heap_init: Initializing. RAM available for dynamic allocation:
+    D (309) light_driver: [light_init, 74]:status: 1, mode: 2
 
 Simple Monitor
 ==============