96 lines
3.4 KiB
ReStructuredText
96 lines
3.4 KiB
ReStructuredText
.. _module-pw_assert_tokenized:
|
|
|
|
===================
|
|
pw_assert_tokenized
|
|
===================
|
|
|
|
--------
|
|
Overview
|
|
--------
|
|
The ``pw_assert_tokenized`` module provides ``PW_ASSERT()`` and ``PW_CHECK_*()``
|
|
backends for the ``pw_assert`` module. These backends are much more space
|
|
efficient than using ``pw_assert_log`` with ``pw_log_tokenized`` The tradeoff,
|
|
however, is that ``PW_CHECK_*()`` macros are much more limited as all argument
|
|
values are discarded. This means only constant string information is captured in
|
|
the reported tokens.
|
|
|
|
* **PW_ASSERT()**: The ``PW_ASSERT()`` macro will capture the file name and line
|
|
number of the assert statement. By default, it is passed to the logging system
|
|
to produce a string like this:
|
|
|
|
PW_ASSERT() or PW_DASSERT() failure at
|
|
pw_result/public/pw_result/result.h:63
|
|
|
|
* **PW_CHECK_\*()**: The ``PW_CHECK_*()`` macros work in contexts where
|
|
tokenization is fully supported, so they are able to capture the CHECK
|
|
statement expression and any provided string literal in addition to the file
|
|
name:
|
|
|
|
Check failure in pw_metric/size_report/base.cc: \*unoptimizable >= 0,
|
|
Ensure this CHECK logic stays.
|
|
|
|
Evaluated values of ``PW_CHECK_*()`` statements are not captured, and any
|
|
string formatting arguments are also not captured. This minimizes call-site
|
|
cost as only two arguments are ever passed to the handler (the calculated
|
|
token, and the line number of the statement).
|
|
|
|
Note that the line number is passed to the tokenized logging system as
|
|
metadata, but is not part of the tokenized string. This is to ensure the
|
|
CHECK callsite maximizes efficiency by only passing two arguments to the
|
|
handler.
|
|
|
|
In both cases, the assert handler is only called with two arguments: a 32-bit
|
|
token to represent a string, and the integer line number of the callsite.
|
|
|
|
-----
|
|
Setup
|
|
-----
|
|
|
|
#. Set ``pw_assert_BACKEND = "$dir_pw_assert_tokenized:check_backend"`` and
|
|
``pw_assert_LITE_BACKEND = "$dir_pw_assert_tokenized:assert_backend"`` in
|
|
your target configuration.
|
|
#. Ensure your target provides ``pw_tokenizer_GLOBAL_HANDLER_BACKEND``. By
|
|
default, pw_assert_tokenized will forward assert failures to the tokenizer
|
|
handler as logs. The tokenizer handler should check for ``LOG_LEVEL_FATAL``
|
|
and properly divert to a crash handler.
|
|
#. Add file name tokens to your token database. pw_assert_tokenized can't create
|
|
file name tokens that can be parsed out of the final compiled binary. The
|
|
``pw_relative_source_file_names``
|
|
:ref:`GN template<module-pw_build-relative-source-file-names>` can be used to
|
|
collect the names of all source files used in your final executable into a
|
|
JSON file, which can then be included in the creation of a tokenizer
|
|
database.
|
|
|
|
Example file name token database setup
|
|
--------------------------------------
|
|
|
|
.. code-block::
|
|
|
|
pw_executable("main") {
|
|
deps = [
|
|
# ...
|
|
]
|
|
sources = [ "main.cc" ]
|
|
}
|
|
|
|
pw_tokenizer_database("log_tokens") {
|
|
database = "tools/tokenized_logs.csv"
|
|
deps = [
|
|
":source_file_names",
|
|
":main",
|
|
]
|
|
optional_paths = [ "$root_build_dir/**/*.elf" ]
|
|
input_databases = [ "$target_gen_dir/source_file_names.json" ]
|
|
}
|
|
|
|
# Extracts all source/header file names from "main" and its transitive
|
|
# dependencies for tokenization.
|
|
pw_relative_source_file_names("source_file_names") {
|
|
deps = [ ":main" ]
|
|
outputs = [ "$target_gen_dir/source_file_names.json" ]
|
|
}
|
|
|
|
|
|
.. warning::
|
|
This module is experimental and does not provide a stable API.
|