diff --git a/doc/guides/index.rst b/doc/guides/index.rst index 543044c8770..8acbb0d2aef 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -35,3 +35,4 @@ User and Developer Guides optimizations/index zephyr_cmake_package.rst thread_local_storage.rst + logging/index diff --git a/doc/guides/logging/dictionary.rst b/doc/guides/logging/dictionary.rst new file mode 100644 index 00000000000..08c36945e59 --- /dev/null +++ b/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 /log_dictionary.json + +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. diff --git a/doc/guides/logging/index.rst b/doc/guides/logging/index.rst new file mode 100644 index 00000000000..505feb29781 --- /dev/null +++ b/doc/guides/logging/index.rst @@ -0,0 +1,9 @@ +.. _logging_guide: + +Logging +####### + +.. toctree:: + :maxdepth: 1 + + dictionary.rst