From 52398df7b6a14ed4c1dee824ce2ffe074731a7e7 Mon Sep 17 00:00:00 2001 From: Anas Nashif Date: Wed, 5 May 2021 13:18:48 -0400 Subject: [PATCH] doc: integrate dict logging into main logging section This belong alongside other logging related documentation. No for this to exist on its own. Signed-off-by: Anas Nashif --- doc/guides/index.rst | 1 - doc/guides/logging/dictionary.rst | 69 ------------------------------- doc/guides/logging/index.rst | 9 ---- doc/reference/logging/index.rst | 69 +++++++++++++++++++++++++++++++ 4 files changed, 69 insertions(+), 79 deletions(-) delete mode 100644 doc/guides/logging/dictionary.rst delete mode 100644 doc/guides/logging/index.rst diff --git a/doc/guides/index.rst b/doc/guides/index.rst index 8acbb0d2aef..543044c8770 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -35,4 +35,3 @@ 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 deleted file mode 100644 index 08c36945e59..00000000000 --- a/doc/guides/logging/dictionary.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _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 deleted file mode 100644 index 505feb29781..00000000000 --- a/doc/guides/logging/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _logging_guide: - -Logging -####### - -.. toctree:: - :maxdepth: 1 - - dictionary.rst diff --git a/doc/reference/logging/index.rst b/doc/reference/logging/index.rst index 35abb2585f4..8bccaa252d3 100644 --- a/doc/reference/logging/index.rst +++ b/doc/reference/logging/index.rst @@ -636,6 +636,75 @@ Example message formatted using :c:func:`log_output_msg_process` or [00:00:00.000,274] sample_instance.inst1: logging message + +.. _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. + +Please refer to :ref:`logging_dictionary_sample` on how to use the log parser. + + + Limitations and recommendations *******************************