1.. _module-pw_assert_tokenized: 2 3=================== 4pw_assert_tokenized 5=================== 6 7-------- 8Overview 9-------- 10The ``pw_assert_tokenized`` module provides ``PW_ASSERT()`` and ``PW_CHECK_*()`` 11backends for the ``pw_assert`` module. These backends are much more space 12efficient than using ``pw_assert_log`` with ``pw_log_tokenized`` The tradeoff, 13however, is that ``PW_CHECK_*()`` macros are much more limited as all argument 14values are discarded. This means only constant string information is captured in 15the reported tokens. 16 17* **PW_ASSERT()**: The ``PW_ASSERT()`` macro will capture the file name and line 18 number of the assert statement. By default, it is passed to the logging system 19 to produce a string like this: 20 21 .. code-block:: text 22 23 PW_ASSERT() or PW_DASSERT() failure at 24 pw_result/public/pw_result/result.h:63 25 26* **PW_CHECK_\*()**: The ``PW_CHECK_*()`` macros work in contexts where 27 tokenization is fully supported, so they are able to capture the CHECK 28 statement expression and any provided string literal in addition to the file 29 name in the pw_log_tokenized key/value format: 30 31 .. code-block:: text 32 33 "■msg♦Check failure: \*unoptimizable >= 0, Ensure this CHECK logic 34 stays■module♦KVS■file♦pw_kvs/size_report/base.cc" 35 36 Evaluated values of ``PW_CHECK_*()`` statements are not captured, and any 37 string formatting arguments are also not captured. This minimizes call-site 38 cost as only two arguments are ever passed to the handler (the calculated 39 token, and the line number of the statement). 40 41 Note that the line number is passed to the tokenized logging system as 42 metadata, but is not part of the tokenized string. This is to ensure the 43 CHECK callsite maximizes efficiency by only passing two arguments to the 44 handler. 45 46In both cases, the assert handler is only called with two arguments: a 32-bit 47token to represent a string, and the integer line number of the callsite. 48 49----- 50Setup 51----- 52 53#. Set ``pw_assert_BACKEND = "$dir_pw_assert_tokenized:check_backend"`` and 54 ``pw_assert_LITE_BACKEND = "$dir_pw_assert_tokenized:assert_backend"`` in 55 your target configuration. 56#. Ensure your target provides 57 ``pw_log_tokenized_HANDLER_BACKEND``. By default, pw_assert_tokenized will 58 forward assert failures to the log system. The tokenizer handler should check 59 for ``LOG_LEVEL_FATAL`` and properly divert to a crash handler. 60#. Add file name tokens to your token database. pw_assert_tokenized can't create 61 file name tokens that can be parsed out of the final compiled binary. The 62 ``pw_relative_source_file_names`` 63 :ref:`GN template<module-pw_build-relative-source-file-names>` can be used to 64 collect the names of all source files used in your final executable into a 65 JSON file, which can then be included in the creation of a tokenizer 66 database. 67 68Example file name token database setup 69-------------------------------------- 70 71.. code-block:: 72 73 pw_executable("main") { 74 deps = [ 75 # ... 76 ] 77 sources = [ "main.cc" ] 78 } 79 80 pw_tokenizer_database("log_tokens") { 81 database = "tools/tokenized_logs.csv" 82 deps = [ 83 ":source_file_names", 84 ":main", 85 ] 86 optional_paths = [ "$root_build_dir/**/*.elf" ] 87 input_databases = [ "$target_gen_dir/source_file_names.json" ] 88 } 89 90 # Extracts all source/header file names from "main" and its transitive 91 # dependencies for tokenization. 92 pw_relative_source_file_names("source_file_names") { 93 deps = [ ":main" ] 94 outputs = [ "$target_gen_dir/source_file_names.json" ] 95 } 96 97 98.. warning:: 99 This module is experimental and does not provide a stable API. 100