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