doc: add documentation for dictionary-based logging

This adds new documentation for dictionary-based logging on
usage and low-level information.

Signed-off-by: Daniel Leung <[email protected]>

Author: dcpleung

doc/guides/index.rst

@@ -35,3 +35,4 @@ User and Developer Guides
    optimizations/index
    zephyr_cmake_package.rst
    thread_local_storage.rst
+   logging/index

doc/guides/logging/dictionary.rst

@@ -0,0 +1,69 @@
+.. _logging_guide_dictionary:
+
+Dictionary-based Logging
+########################
+
+Dictionary-based logging, instead of human readable texts, outputs the log
+messages in binary format. This binary format encodes arguments to formatted
+strings in their native storage formats which can be more compact than their
+text equivalents. For statically defined strings (including the format
+strings and any string arguments), references to the ELF file are encoded
+instead of the whole strings. A dictionary created at build time contains
+the mappings between these references and the actual strings. This allows
+the offline parser to obtain the strings from the dictionary to parse
+the log messages. This binary format allows a more compact representation
+of log messages in certain scenarios. However, this requires the use of
+an offline parser and is not as intuitive to use as text-based log messages.
+
+Note that ``long double`` is not supported by Python's ``struct`` module.
+Therefore, log messages with ``long double`` will not display the correct
+values.
+
+
+Configuration
+*************
+
+Here are kconfig options related to dictionary-based logging:
+
+- :option:`CONFIG_LOG_DICTIONARY_SUPPORT` enables dictionary-based logging
+  support. This should be selected by the backends which require it.
+
+- The UART backend can be used for dictionary-based logging. These are
+  additional config for the UART backend:
+
+  - :option:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX` tells
+    the UART backend to output hexadecimal characters for dictionary based
+    logging. This is useful when the log data needs to be captured manually
+    via terminals and consoles.
+
+  - :option:`CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_BIN` tells
+    the UART backend to output binary data.
+
+
+Usage
+*****
+
+When dictionary-based logging is enabled via enabling related logging backends,
+a JSON database file, named :file:`log_dictionary.json`, will be created
+in the build directory. This database file contains information for the parser
+to correctly parse the log data. Note that this database file only works
+with the same build, and cannot be used for any other builds.
+
+To use the log parser:
+
+.. code-block:: console
+
+   ./scripts/logging/dictionary/log_parser.py <build dir>/log_dictionary.json <log data file>
+
+The parser takes two required arguments, where the first one is the full path
+to the JSON database file, and the second part is the file containing log data.
+Add an optional argument ``--hex`` to the end if the log data file contains
+hexadecimal characters
+(e.g. when ``CONFIG_LOG_BACKEND_UART_OUTPUT_DICTIONARY_HEX=y``). This tells
+the parser to convert the hexadecimal characters to binary before parsing.
+
+
+Example
+-------
+
+Please refer to :ref:`logging_dictionary_sample` on how to use the log parser.

doc/guides/logging/index.rst

@@ -0,0 +1,9 @@
+.. _logging_guide:
+
+Logging
+#######
+
+.. toctree::
+   :maxdepth: 1
+
+   dictionary.rst