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