Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_assert: |
Keir Mierle | 3cee879 | 2020-01-22 17:08:13 -0800 | [diff] [blame] | 2 | |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 3 | ========= |
Keir Mierle | 3cee879 | 2020-01-22 17:08:13 -0800 | [diff] [blame] | 4 | pw_assert |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 5 | ========= |
| 6 | |
| 7 | -------- |
| 8 | Overview |
| 9 | -------- |
Keir Mierle | 481d829 | 2020-07-31 01:10:05 -0700 | [diff] [blame] | 10 | Pigweed's assert module enables applications to check preconditions, triggering |
| 11 | a crash if the condition is not met. Consistent use of asserts is one aspect of |
| 12 | defensive programming that can lead to more reliable and less buggy code. |
Keir Mierle | 3cee879 | 2020-01-22 17:08:13 -0800 | [diff] [blame] | 13 | |
Keir Mierle | 481d829 | 2020-07-31 01:10:05 -0700 | [diff] [blame] | 14 | The assert API facilitates flexible crash handling through Pigweed's facade |
| 15 | mechanism. The API is desigend to enable features like: |
Keir Mierle | 3cee879 | 2020-01-22 17:08:13 -0800 | [diff] [blame] | 16 | |
Keir Mierle | 481d829 | 2020-07-31 01:10:05 -0700 | [diff] [blame] | 17 | - Optional ancillary printf-style messages along assertions |
| 18 | - Capturing actual values of binary operator assertions like ``a < b`` |
| 19 | - Compatibility with pw_tokenizer for reduced binary code size |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 20 | |
Keir Mierle | 481d829 | 2020-07-31 01:10:05 -0700 | [diff] [blame] | 21 | The ``pw_assert`` API provides three classes of macros: |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 22 | |
Keir Mierle | 481d829 | 2020-07-31 01:10:05 -0700 | [diff] [blame] | 23 | - **PW_CRASH(format, ...)** - Trigger a crash with a message. |
| 24 | - **PW_CHECK(condition[, format, ...])** - Assert a condition, optionally with |
| 25 | a message. |
| 26 | - **PW_CHECK_<type>_<cmp>(a, b[, fmt, ...])** - Assert that the expression ``a |
| 27 | <cmp> b`` is true, optionally with a message. |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 28 | - **PW_ASSERT(condition)** - Header- and constexpr-safe assert. |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 29 | |
| 30 | .. tip:: |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 31 | |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 32 | All of the ``CHECK`` macros optionally support a message with additional |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 33 | arguments, to assist in debugging when an assert triggers: |
| 34 | |
| 35 | .. code-block:: cpp |
| 36 | |
| 37 | PW_CHECK_INT_LE(ItemCount(), 100); |
| 38 | PW_CHECK_INT_LE(ItemCount(), 100, "System state: %s", GetStateStr()); |
| 39 | |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 40 | Example |
| 41 | ------- |
Keir Mierle | 3cee879 | 2020-01-22 17:08:13 -0800 | [diff] [blame] | 42 | |
| 43 | .. code-block:: cpp |
| 44 | |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 45 | #include "pw_assert/check.h" |
Keir Mierle | 3cee879 | 2020-01-22 17:08:13 -0800 | [diff] [blame] | 46 | |
| 47 | int main() { |
| 48 | bool sensor_running = StartSensor(&msg); |
| 49 | PW_CHECK(sensor_running, "Sensor failed to start; code: %s", msg); |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 50 | |
| 51 | int temperature_c = ReadSensorCelcius(); |
| 52 | PW_CHECK_INT_LE(temperature_c, 100, |
| 53 | "System is way out of heat spec; state=%s", |
| 54 | ReadSensorStateString()); |
Keir Mierle | 3cee879 | 2020-01-22 17:08:13 -0800 | [diff] [blame] | 55 | } |
| 56 | |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 57 | .. tip:: |
| 58 | |
| 59 | All macros have both a ``CHECK`` and ``DCHECK`` variant. The ``CHECK`` |
| 60 | variant is always enabled, even in production. Generally, we advise making |
| 61 | most asserts ``CHECK`` rather than ``DCHECK``, unless there is a critical |
| 62 | performance or code size reason to use ``DCHECK``. |
| 63 | |
| 64 | .. code-block:: cpp |
| 65 | |
| 66 | // This assert is always enabled, even in production. |
| 67 | PW_CHECK_INT_LE(ItemCount(), 100); |
| 68 | |
| 69 | // This assert disabled for release builds, where NDEBUG is defined. |
| 70 | // The functions ItemCount() and GetStateStr() are never called. |
| 71 | PW_DCHECK_INT_LE(ItemCount(), 100, "System state: %s", GetStateStr()); |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 72 | |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 73 | .. tip:: |
| 74 | |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 75 | Use ``PW_ASSERT`` from ``pw_assert/assert.h`` for asserts in headers or |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 76 | asserting in ``constexpr`` contexts. |
| 77 | |
Keir Mierle | 481d829 | 2020-07-31 01:10:05 -0700 | [diff] [blame] | 78 | Structure of assert modules |
| 79 | --------------------------- |
| 80 | The module is split into two components: |
| 81 | |
| 82 | 1. The **facade** (this module) which is only a macro interface layer, and |
| 83 | performs the actual checks for the conditions. |
| 84 | 2. The **backend**, provided elsewhere, that handles the consequences of an |
| 85 | assert failing. Example backends include ``pw_assert_basic``, which prints a |
| 86 | useful message and either quits the application (on host) or hangs in a |
| 87 | while loop (on device). In the future, there will be a tokenized assert |
| 88 | backend. This is also where application or product specific crash handling |
| 89 | would go. |
| 90 | |
| 91 | .. blockdiag:: |
| 92 | |
| 93 | blockdiag { |
| 94 | default_fontsize = 16; |
| 95 | facade [label = "facade"]; |
| 96 | backend [label = "backend"]; |
| 97 | facade -> backend |
| 98 | } |
| 99 | |
| 100 | See the Backend API section below for more details. |
| 101 | |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 102 | ---------- |
| 103 | Facade API |
| 104 | ---------- |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 105 | The below functions describe the assert API functions that applications should |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 106 | invoke to assert. These macros are found in the ``pw_assert/check.h`` header. |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 107 | |
| 108 | .. cpp:function:: PW_CRASH(format, ...) |
| 109 | |
| 110 | Trigger a crash with a message. Replaces LOG_FATAL() in other systems. Can |
| 111 | include a message with format arguments; for example: |
| 112 | |
| 113 | .. code-block:: cpp |
| 114 | |
| 115 | PW_CRASH("Unexpected: frobnitz in state: %s", frobnitz_state); |
| 116 | |
| 117 | Note: ``PW_CRASH`` is the equivalent of ``LOG_FATAL`` in other systems, where |
| 118 | a device crash is triggered with a message. In Pigweed, logging and |
| 119 | crashing/asserting are separated. There is a ``LOG_CRITICAL`` level in the |
| 120 | logging module, but it does not have side effects; for ``LOG_FATAL``, instead |
| 121 | use this macro (``PW_CRASH``). |
| 122 | |
| 123 | .. cpp:function:: PW_CHECK(condition) |
| 124 | .. cpp:function:: PW_CHECK(condition, format, ...) |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 125 | .. cpp:function:: PW_DCHECK(condition) |
| 126 | .. cpp:function:: PW_DCHECK(condition, format, ...) |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 127 | |
| 128 | Assert that a condition is true, optionally including a message with |
| 129 | arguments to report if the codition is false. |
| 130 | |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 131 | The ``DCHECK`` variants only run if ``NDEBUG`` is defined; otherwise, the |
| 132 | entire statement is removed (and the expression not evaluated). |
| 133 | |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 134 | Example: |
| 135 | |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 136 | .. code-block:: cpp |
| 137 | |
| 138 | PW_CHECK(StartTurbines()); |
| 139 | PW_CHECK(StartWarpDrive(), "Oddly warp drive couldn't start; ruh-roh!"); |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 140 | PW_CHECK(RunSelfTest(), "Failure in self test; try %d", TestAttempts()); |
| 141 | |
| 142 | .. attention:: |
| 143 | |
Keir Mierle | 0fa7f7d | 2020-05-07 12:34:00 -0700 | [diff] [blame] | 144 | Don't use use ``PW_CHECK`` for binary comparisons or status checks! |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 145 | |
| 146 | Instead, use the ``PW_CHECK_<TYPE>_<OP>`` macros. These macros enable |
| 147 | capturing the value of the operands, and also tokenizing them if using a |
| 148 | tokenizing assert backend. For example, if ``x`` and ``b`` are integers, |
| 149 | use instead ``PW_CHECK_INT_LT(x, b)``. |
| 150 | |
Wyatt Hepler | 1b3da3a | 2021-01-07 13:26:57 -0800 | [diff] [blame] | 151 | Additionally, use ``PW_CHECK_OK(status)`` when checking for an OK status, |
| 152 | since it enables showing a human-readable status string rather than an |
| 153 | integer (e.g. ``status == RESOURCE_EXHAUSTED`` instead of ``status == 5``. |
Keir Mierle | 0fa7f7d | 2020-05-07 12:34:00 -0700 | [diff] [blame] | 154 | |
| 155 | +------------------------------------+-------------------------------------+ |
| 156 | | **Do NOT do this** | **Do this instead** | |
| 157 | +------------------------------------+-------------------------------------+ |
| 158 | | ``PW_CHECK(a_int < b_int)`` | ``PW_CHECK_INT_LT(a_int, b_int)`` | |
| 159 | +------------------------------------+-------------------------------------+ |
| 160 | | ``PW_CHECK(a_ptr <= b_ptr)`` | ``PW_CHECK_PTR_LE(a_ptr, b_ptr)`` | |
| 161 | +------------------------------------+-------------------------------------+ |
Ewout van Bekkum | 9e97cfd | 2020-07-16 13:57:24 -0700 | [diff] [blame] | 162 | | ``PW_CHECK(Temp() <= 10.0)`` | ``PW_CHECK_FLOAT_EXACT_LE(`` | |
| 163 | | | `` Temp(), 10.0)`` | |
Keir Mierle | 0fa7f7d | 2020-05-07 12:34:00 -0700 | [diff] [blame] | 164 | +------------------------------------+-------------------------------------+ |
Wyatt Hepler | 1b3da3a | 2021-01-07 13:26:57 -0800 | [diff] [blame] | 165 | | ``PW_CHECK(Foo() == OkStatus())`` | ``PW_CHECK_OK(Foo())`` | |
Keir Mierle | 0fa7f7d | 2020-05-07 12:34:00 -0700 | [diff] [blame] | 166 | +------------------------------------+-------------------------------------+ |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 167 | |
Keir Mierle | fa8f89d | 2020-04-15 16:20:02 -0700 | [diff] [blame] | 168 | .. cpp:function:: PW_CHECK_NOTNULL(ptr) |
| 169 | .. cpp:function:: PW_CHECK_NOTNULL(ptr, format, ...) |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 170 | .. cpp:function:: PW_DCHECK_NOTNULL(ptr) |
| 171 | .. cpp:function:: PW_DCHECK_NOTNULL(ptr, format, ...) |
Keir Mierle | fa8f89d | 2020-04-15 16:20:02 -0700 | [diff] [blame] | 172 | |
| 173 | Assert that the given pointer is not ``NULL``, optionally including a message |
| 174 | with arguments to report if the pointer is ``NULL``. |
| 175 | |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 176 | The ``DCHECK`` variants only run if ``NDEBUG`` is defined; otherwise, the |
| 177 | entire statement is removed (and the expression not evaluated). |
| 178 | |
Keir Mierle | fa8f89d | 2020-04-15 16:20:02 -0700 | [diff] [blame] | 179 | .. code-block:: cpp |
| 180 | |
| 181 | Foo* foo = GetTheFoo() |
| 182 | PW_CHECK_NOTNULL(foo); |
| 183 | |
Keir Mierle | 0fa7f7d | 2020-05-07 12:34:00 -0700 | [diff] [blame] | 184 | Bar* bar = GetSomeBar(); |
Keir Mierle | fa8f89d | 2020-04-15 16:20:02 -0700 | [diff] [blame] | 185 | PW_CHECK_NOTNULL(bar, "Weirdly got NULL bar; state: %d", MyState()); |
| 186 | |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 187 | .. cpp:function:: PW_CHECK_TYPE_OP(a, b) |
| 188 | .. cpp:function:: PW_CHECK_TYPE_OP(a, b, format, ...) |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 189 | .. cpp:function:: PW_DCHECK_TYPE_OP(a, b) |
| 190 | .. cpp:function:: PW_DCHECK_TYPE_OP(a, b, format, ...) |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 191 | |
| 192 | Asserts that ``a OP b`` is true, where ``a`` and ``b`` are converted to |
| 193 | ``TYPE``; with ``OP`` and ``TYPE`` described below. |
| 194 | |
| 195 | If present, the optional format message is reported on failure. Depending on |
| 196 | the backend, values of ``a`` and ``b`` will also be reported. |
| 197 | |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 198 | The ``DCHECK`` variants only run if ``NDEBUG`` is defined; otherwise, the |
| 199 | entire statement is removed (and the expression not evaluated). |
| 200 | |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 201 | Example, with no message: |
| 202 | |
| 203 | .. code-block:: cpp |
| 204 | |
| 205 | PW_CHECK_INT_LE(CurrentTemperature(), 100); |
| 206 | PW_CHECK_INT_LE(ItemCount(), 100); |
| 207 | |
| 208 | Example, with an included message and arguments: |
| 209 | |
| 210 | .. code-block:: cpp |
| 211 | |
Ewout van Bekkum | 9e97cfd | 2020-07-16 13:57:24 -0700 | [diff] [blame] | 212 | PW_CHECK_FLOAT_EXACT_GE(BatteryVoltage(), 3.2, |
| 213 | "System state=%s", SysState()); |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 214 | |
| 215 | Below is the full list of binary comparison assert macros, along with the |
| 216 | type specifier. The specifier is irrelevant to application authors but is |
| 217 | needed for backend implementers. |
| 218 | |
Ewout van Bekkum | 9e97cfd | 2020-07-16 13:57:24 -0700 | [diff] [blame] | 219 | +-------------------------+--------------+-----------+-----------------------+ |
| 220 | | Macro | a, b type | condition | a, b format specifier | |
| 221 | +-------------------------+--------------+-----------+-----------------------+ |
| 222 | | PW_CHECK_INT_LE | int | a <= b | %d | |
| 223 | +-------------------------+--------------+-----------+-----------------------+ |
| 224 | | PW_CHECK_INT_LT | int | a < b | %d | |
| 225 | +-------------------------+--------------+-----------+-----------------------+ |
| 226 | | PW_CHECK_INT_GE | int | a >= b | %d | |
| 227 | +-------------------------+--------------+-----------+-----------------------+ |
| 228 | | PW_CHECK_INT_GT | int | a > b | %d | |
| 229 | +-------------------------+--------------+-----------+-----------------------+ |
| 230 | | PW_CHECK_INT_EQ | int | a == b | %d | |
| 231 | +-------------------------+--------------+-----------+-----------------------+ |
| 232 | | PW_CHECK_INT_NE | int | a != b | %d | |
| 233 | +-------------------------+--------------+-----------+-----------------------+ |
| 234 | | PW_CHECK_UINT_LE | unsigned int | a <= b | %u | |
| 235 | +-------------------------+--------------+-----------+-----------------------+ |
| 236 | | PW_CHECK_UINT_LT | unsigned int | a < b | %u | |
| 237 | +-------------------------+--------------+-----------+-----------------------+ |
| 238 | | PW_CHECK_UINT_GE | unsigned int | a >= b | %u | |
| 239 | +-------------------------+--------------+-----------+-----------------------+ |
| 240 | | PW_CHECK_UINT_GT | unsigned int | a > b | %u | |
| 241 | +-------------------------+--------------+-----------+-----------------------+ |
| 242 | | PW_CHECK_UINT_EQ | unsigned int | a == b | %u | |
| 243 | +-------------------------+--------------+-----------+-----------------------+ |
| 244 | | PW_CHECK_UINT_NE | unsigned int | a != b | %u | |
| 245 | +-------------------------+--------------+-----------+-----------------------+ |
| 246 | | PW_CHECK_PTR_LE | void* | a <= b | %p | |
| 247 | +-------------------------+--------------+-----------+-----------------------+ |
| 248 | | PW_CHECK_PTR_LT | void* | a < b | %p | |
| 249 | +-------------------------+--------------+-----------+-----------------------+ |
| 250 | | PW_CHECK_PTR_GE | void* | a >= b | %p | |
| 251 | +-------------------------+--------------+-----------+-----------------------+ |
| 252 | | PW_CHECK_PTR_GT | void* | a > b | %p | |
| 253 | +-------------------------+--------------+-----------+-----------------------+ |
| 254 | | PW_CHECK_PTR_EQ | void* | a == b | %p | |
| 255 | +-------------------------+--------------+-----------+-----------------------+ |
| 256 | | PW_CHECK_PTR_NE | void* | a != b | %p | |
| 257 | +-------------------------+--------------+-----------+-----------------------+ |
| 258 | | PW_CHECK_FLOAT_EXACT_LE | float | a <= b | %f | |
| 259 | +-------------------------+--------------+-----------+-----------------------+ |
| 260 | | PW_CHECK_FLOAT_EXACT_LT | float | a < b | %f | |
| 261 | +-------------------------+--------------+-----------+-----------------------+ |
| 262 | | PW_CHECK_FLOAT_EXACT_GE | float | a >= b | %f | |
| 263 | +-------------------------+--------------+-----------+-----------------------+ |
| 264 | | PW_CHECK_FLOAT_EXACT_GT | float | a > b | %f | |
| 265 | +-------------------------+--------------+-----------+-----------------------+ |
| 266 | | PW_CHECK_FLOAT_EXACT_EQ | float | a == b | %f | |
| 267 | +-------------------------+--------------+-----------+-----------------------+ |
| 268 | | PW_CHECK_FLOAT_EXACT_NE | float | a != b | %f | |
| 269 | +-------------------------+--------------+-----------+-----------------------+ |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 270 | |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 271 | The above ``CHECK_*_*()`` are also available in DCHECK variants, which will |
| 272 | only evaluate their arguments and trigger if the ``NDEBUG`` macro is defined. |
| 273 | |
Ewout van Bekkum | 9e97cfd | 2020-07-16 13:57:24 -0700 | [diff] [blame] | 274 | +--------------------------+--------------+-----------+----------------------+ |
| 275 | | Macro | a, b type | condition | a, b format | |
| 276 | | | | | specifier | |
| 277 | +--------------------------+--------------+-----------+----------------------+ |
| 278 | | PW_DCHECK_INT_LE | int | a <= b | %d | |
| 279 | +--------------------------+--------------+-----------+----------------------+ |
| 280 | | PW_DCHECK_INT_LT | int | a < b | %d | |
| 281 | +--------------------------+--------------+-----------+----------------------+ |
| 282 | | PW_DCHECK_INT_GE | int | a >= b | %d | |
| 283 | +--------------------------+--------------+-----------+----------------------+ |
| 284 | | PW_DCHECK_INT_GT | int | a > b | %d | |
| 285 | +--------------------------+--------------+-----------+----------------------+ |
| 286 | | PW_DCHECK_INT_EQ | int | a == b | %d | |
| 287 | +--------------------------+--------------+-----------+----------------------+ |
| 288 | | PW_DCHECK_INT_NE | int | a != b | %d | |
| 289 | +--------------------------+--------------+-----------+----------------------+ |
| 290 | | PW_DCHECK_UINT_LE | unsigned int | a <= b | %u | |
| 291 | +--------------------------+--------------+-----------+----------------------+ |
| 292 | | PW_DCHECK_UINT_LT | unsigned int | a < b | %u | |
| 293 | +--------------------------+--------------+-----------+----------------------+ |
| 294 | | PW_DCHECK_UINT_GE | unsigned int | a >= b | %u | |
| 295 | +--------------------------+--------------+-----------+----------------------+ |
| 296 | | PW_DCHECK_UINT_GT | unsigned int | a > b | %u | |
| 297 | +--------------------------+--------------+-----------+----------------------+ |
| 298 | | PW_DCHECK_UINT_EQ | unsigned int | a == b | %u | |
| 299 | +--------------------------+--------------+-----------+----------------------+ |
| 300 | | PW_DCHECK_UINT_NE | unsigned int | a != b | %u | |
| 301 | +--------------------------+--------------+-----------+----------------------+ |
| 302 | | PW_DCHECK_PTR_LE | void* | a <= b | %p | |
| 303 | +--------------------------+--------------+-----------+----------------------+ |
| 304 | | PW_DCHECK_PTR_LT | void* | a < b | %p | |
| 305 | +--------------------------+--------------+-----------+----------------------+ |
| 306 | | PW_DCHECK_PTR_GE | void* | a >= b | %p | |
| 307 | +--------------------------+--------------+-----------+----------------------+ |
| 308 | | PW_DCHECK_PTR_GT | void* | a > b | %p | |
| 309 | +--------------------------+--------------+-----------+----------------------+ |
| 310 | | PW_DCHECK_PTR_EQ | void* | a == b | %p | |
| 311 | +--------------------------+--------------+-----------+----------------------+ |
| 312 | | PW_DCHECK_PTR_NE | void* | a != b | %p | |
| 313 | +--------------------------+--------------+-----------+----------------------+ |
| 314 | | PW_DCHECK_FLOAT_EXACT_LE | float | a <= b | %f | |
| 315 | +--------------------------+--------------+-----------+----------------------+ |
| 316 | | PW_DCHECK_FLOAT_EXACT_LT | float | a < b | %f | |
| 317 | +--------------------------+--------------+-----------+----------------------+ |
| 318 | | PW_DCHECK_FLOAT_EXACT_GE | float | a >= b | %f | |
| 319 | +--------------------------+--------------+-----------+----------------------+ |
| 320 | | PW_DCHECK_FLOAT_EXACT_GT | float | a > b | %f | |
| 321 | +--------------------------+--------------+-----------+----------------------+ |
| 322 | | PW_DCHECK_FLOAT_EXACT_EQ | float | a == b | %f | |
| 323 | +--------------------------+--------------+-----------+----------------------+ |
| 324 | | PW_DCHECK_FLOAT_EXACT_NE | float | a != b | %f | |
| 325 | +--------------------------+--------------+-----------+----------------------+ |
| 326 | |
| 327 | .. attention:: |
| 328 | |
| 329 | For float, proper comparator checks which take floating point |
| 330 | precision and ergo error accumulation into account are not provided on |
| 331 | purpose as this comes with some complexity and requires application |
| 332 | specific tolerances in terms of Units of Least Precision (ULP). Instead, |
| 333 | we recommend developers carefully consider how floating point precision and |
| 334 | error impact the data they are bounding and whether checks are appropriate. |
| 335 | |
| 336 | .. cpp:function:: PW_CHECK_FLOAT_NEAR(a, b, abs_tolerance) |
| 337 | .. cpp:function:: PW_CHECK_FLOAT_NEAR(a, b, abs_tolerance, format, ...) |
| 338 | .. cpp:function:: PW_DCHECK_FLOAT_NEAR(a, b, abs_tolerance) |
| 339 | .. cpp:function:: PW_DCHECK_FLOAT_NEAR(a, b, abs_tolerance, format, ...) |
| 340 | |
| 341 | Asserts that ``(a >= b - abs_tolerance) && (a <= b + abs_tolerance)`` is true, |
| 342 | where ``a``, ``b``, and ``abs_tolerance`` are converted to ``float``. |
| 343 | |
| 344 | .. note:: |
| 345 | This also asserts that ``abs_tolerance >= 0``. |
| 346 | |
| 347 | The ``DCHECK`` variants only run if ``NDEBUG`` is defined; otherwise, the |
| 348 | entire statement is removed (and the expression not evaluated). |
| 349 | |
| 350 | Example, with no message: |
| 351 | |
| 352 | .. code-block:: cpp |
| 353 | |
| 354 | PW_CHECK_FLOAT_NEAR(cos(0.0f), 1, 0.001); |
| 355 | |
| 356 | Example, with an included message and arguments: |
| 357 | |
| 358 | .. code-block:: cpp |
| 359 | |
| 360 | PW_CHECK_FLOAT_NEAR(FirstOperation(), RedundantOperation(), 0.1, |
| 361 | "System state=%s", SysState()); |
Keir Mierle | b9b8816 | 2020-04-15 20:43:09 -0700 | [diff] [blame] | 362 | |
Keir Mierle | 0fa7f7d | 2020-05-07 12:34:00 -0700 | [diff] [blame] | 363 | .. cpp:function:: PW_CHECK_OK(status) |
| 364 | .. cpp:function:: PW_CHECK_OK(status, format, ...) |
| 365 | .. cpp:function:: PW_DCHECK_OK(status) |
| 366 | .. cpp:function:: PW_DCHECK_OK(status, format, ...) |
| 367 | |
Wyatt Hepler | 1b3da3a | 2021-01-07 13:26:57 -0800 | [diff] [blame] | 368 | Assert that ``status`` evaluates to ``pw::OkStatus()`` (in C++) or |
Keir Mierle | 0fa7f7d | 2020-05-07 12:34:00 -0700 | [diff] [blame] | 369 | ``PW_STATUS_OK`` (in C). Optionally include a message with arguments to |
| 370 | report. |
| 371 | |
| 372 | The ``DCHECK`` variants only run if ``NDEBUG`` is defined; otherwise, the |
| 373 | entire statement is removed (and the expression not evaluated). |
| 374 | |
| 375 | .. code-block:: cpp |
| 376 | |
| 377 | pw::Status operation_status = DoSomeOperation(); |
| 378 | PW_CHECK_OK(operation_status); |
| 379 | |
| 380 | // Any expression that evaluates to a pw::Status or pw_Status works. |
| 381 | PW_CHECK_OK(DoTheThing(), "System state: %s", SystemState()); |
| 382 | |
| 383 | // C works too. |
| 384 | pw_Status c_status = DoMoreThings(); |
| 385 | PW_CHECK_OK(c_status, "System state: %s", SystemState()); |
| 386 | |
| 387 | .. note:: |
| 388 | |
Wyatt Hepler | 1b3da3a | 2021-01-07 13:26:57 -0800 | [diff] [blame] | 389 | Using ``PW_CHECK_OK(status)`` instead of ``PW_CHECK(status == OkStatus())`` |
Keir Mierle | 0fa7f7d | 2020-05-07 12:34:00 -0700 | [diff] [blame] | 390 | enables displaying an error message with a string version of the error |
| 391 | code; for example ``status == RESOURCE_EXHAUSTED`` instead of ``status == |
| 392 | 5``. |
| 393 | |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 394 | ---------- |
| 395 | Assert API |
| 396 | ---------- |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 397 | The normal ``PW_CHECK_*`` and ``PW_DCHECK_*`` family of macros are intended to |
| 398 | provide rich debug information, like the file, line number, value of operands |
| 399 | in boolean comparisons, and more. However, this comes at a cost: these macros |
| 400 | depend directly on the backend headers, and may perform complicated call-site |
| 401 | transformations like tokenization. |
| 402 | |
| 403 | There are several issues with the normal ``PW_CHECK_*`` suite of macros: |
| 404 | |
| 405 | 1. ``PW_CHECK_*`` in headers can cause ODR violations in the case of tokenized |
| 406 | asserts, due to differing module choices. |
| 407 | 2. ``PW_CHECK_*`` is not constexpr-safe. |
| 408 | 3. ``PW_CHECK_*`` can cause code bloat with some backends; this is the tradeoff |
| 409 | to get rich assert information. |
| 410 | 4. ``PW_CHECK_*`` can trigger circular dependencies when asserts are used from |
| 411 | low-level contexts, like in ``<span>``. |
| 412 | |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 413 | **PW_ASSERT** solves all of the above problems: No risk of ODR violations, are |
| 414 | constexpr safe, and have a tiny call site footprint; and there is no header |
| 415 | dependency on the backend preventing circular include issues. However, there |
| 416 | are **no format messages, no captured line number, no captured file, no captured |
| 417 | expression, or anything other than a binary indication of failure**. |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 418 | |
| 419 | Example |
| 420 | ------- |
| 421 | |
| 422 | .. code-block:: cpp |
| 423 | |
| 424 | // This example demonstrates asserting in a header. |
| 425 | |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 426 | #include "pw_assert/assert.h" |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 427 | |
| 428 | class InlinedSubsystem { |
| 429 | public: |
| 430 | void DoSomething() { |
| 431 | // GOOD: No problem; PW_ASSERT is fine to inline and place in a header. |
| 432 | PW_ASSERT(IsEnabled()); |
| 433 | } |
| 434 | void DoSomethingElse() { |
| 435 | // BAD: Generally avoid using PW_DCHECK() or PW_CHECK in headers. If you |
| 436 | // want rich asserts or logs, move the function into the .cc file, and |
| 437 | // then use PW_CHECK there. |
| 438 | PW_DCHECK(IsEnabled()); // DON'T DO THIS |
| 439 | } |
| 440 | }; |
| 441 | |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 442 | PW_ASSERT API reference |
| 443 | ----------------------- |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 444 | .. cpp:function:: PW_ASSERT(condition) |
| 445 | |
| 446 | A header- and constexpr-safe version of ``PW_CHECK()``. |
| 447 | |
| 448 | If the given condition is false, crash the system. Otherwise, do nothing. |
| 449 | The condition is guaranteed to be evaluated. This assert implementation is |
| 450 | guaranteed to be constexpr-safe. |
| 451 | |
| 452 | .. cpp:function:: PW_DASSERT(condition) |
| 453 | |
| 454 | A header- and constexpr-safe version of ``PW_DCHECK()``. |
| 455 | |
| 456 | Same as ``PW_ASSERT()``, except that if ``PW_ASSERT_ENABLE_DEBUG == 1``, the |
| 457 | assert is disabled and condition is not evaluated. |
| 458 | |
| 459 | .. attention:: |
| 460 | |
| 461 | Unlike the ``PW_CHECK_*()`` suite of macros, ``PW_ASSERT()`` and |
| 462 | ``PW_DASSERT()`` capture no rich information like line numbers, the file, |
| 463 | expression arguments, or the stringified expression. Use these macros **only |
Alexei Frolov | 5a0450d | 2020-10-28 21:10:47 -0700 | [diff] [blame] | 464 | when absolutely necessary**---in headers, constexpr contexts, or in rare cases |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 465 | where the call site overhead of a full PW_CHECK must be avoided. |
| 466 | |
| 467 | Use ``PW_CHECK_*()`` whenever possible. |
| 468 | |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 469 | PW_ASSERT API backend |
| 470 | --------------------- |
| 471 | The ``PW_ASSERT`` API ultimately calls the C function |
| 472 | ``pw_assert_HandleFailure()``, which must be provided by the ``pw_assert`` |
| 473 | backend. |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 474 | |
Wyatt Hepler | 8bd4fb0 | 2021-05-03 15:30:58 -0700 | [diff] [blame^] | 475 | .. _module-pw_assert-circular-deps: |
| 476 | |
Wyatt Hepler | 3d0e315 | 2021-04-29 17:08:31 -0700 | [diff] [blame] | 477 | Avoiding circular dependencies with ``PW_ASSERT`` |
| 478 | ------------------------------------------------- |
| 479 | Because asserts are so widely used, including in low-level libraries, it is |
Wyatt Hepler | 8bd4fb0 | 2021-05-03 15:30:58 -0700 | [diff] [blame^] | 480 | common for the ``pw_assert`` backend to cause circular dependencies. Because of |
| 481 | this, assert backends may avoid declaring explicit dependencies, instead relying |
| 482 | on include paths to access header files. |
Wyatt Hepler | 3d0e315 | 2021-04-29 17:08:31 -0700 | [diff] [blame] | 483 | |
Wyatt Hepler | 8bd4fb0 | 2021-05-03 15:30:58 -0700 | [diff] [blame^] | 484 | In GN, the ``pw_assert`` backend's true dependencies are made available through |
| 485 | the ``$dir_pw_assert:deps`` group. When ``pw_assert_BACKEND`` is set, |
| 486 | ``$dir_pw_assert:deps`` must be listed in the ``pw_build_LINK_DEPS`` variable. |
| 487 | See :ref:`module-pw_build-link-deps`. |
| 488 | |
| 489 | If necessary, ``pw_assert`` backends can access dependencies from include paths |
| 490 | rather than GN ``deps``. In this case, the may disable GN header checking with |
| 491 | ``check_includes = false``. The true build dependencies must be listed in a |
| 492 | ``deps`` group, which the ``pw_assert`` facade depends on. The ``deps`` group |
| 493 | may be empty if the backend can use its dependencies directly without causing |
| 494 | circular dependencies. |
Wyatt Hepler | 3d0e315 | 2021-04-29 17:08:31 -0700 | [diff] [blame] | 495 | |
Armando Montanez | 179aa8e | 2021-03-10 11:46:35 -0800 | [diff] [blame] | 496 | .. _module-pw_assert-backend_api: |
| 497 | |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 498 | ----------- |
| 499 | Backend API |
| 500 | ----------- |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 501 | |
| 502 | The backend controls what to do in the case of an assertion failure. In the |
| 503 | most basic cases, the backend could display the assertion failure on something |
| 504 | like sys_io and halt in a while loop waiting for a debugger. In other cases, |
| 505 | the backend could store crash details like the current thread's stack to flash. |
| 506 | |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 507 | This facade module (``pw_assert``) does not provide a backend. See |
Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 508 | :ref:`module-pw_assert_basic` for a basic implementation. |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 509 | |
Keir Mierle | 49f8e7e | 2020-07-30 17:57:30 -0700 | [diff] [blame] | 510 | .. attention:: |
| 511 | |
| 512 | The facade macros (``PW_CRASH`` and related) are expected to behave like they |
Wyatt Hepler | 3d0e315 | 2021-04-29 17:08:31 -0700 | [diff] [blame] | 513 | have the ``[[noreturn]]`` attribute set. This implies that the backend handler |
| 514 | functions, ``PW_HANDLE_*`` defined by the backend, must not return. |
Keir Mierle | 49f8e7e | 2020-07-30 17:57:30 -0700 | [diff] [blame] | 515 | |
| 516 | In other words, the device must reboot. |
| 517 | |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 518 | The backend must provide the header |
| 519 | |
| 520 | ``pw_assert_backend/backend.h`` |
| 521 | |
| 522 | and that header must define the following macros: |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 523 | |
| 524 | .. cpp:function:: PW_HANDLE_CRASH(message, ...) |
| 525 | |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 526 | Trigger a system crash or halt, and if possible, deliver the specified |
| 527 | message and arguments to the user or developer. |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 528 | |
| 529 | .. cpp:function:: PW_HANDLE_ASSERT_FAILURE(condition_str, message, ...) |
| 530 | |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 531 | Trigger a system crash or halt, and if possible, deliver the condition string |
| 532 | (indicating what expression was false) and the message with format arguments, |
| 533 | to the user or developer. |
| 534 | |
| 535 | This macro is invoked from the ``PW_CHECK`` facade macro if condition is |
| 536 | false. |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 537 | |
| 538 | .. cpp:function:: PW_HANDLE_ASSERT_BINARY_COMPARE_FAILURE( \ |
| 539 | a_str, a_val, op_str, b_str, b_val, type_fmt, message, ...) |
| 540 | |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 541 | Trigger a system crash or halt for a failed binary comparison assert (e.g. |
| 542 | any of the ``PW_CHECK_<type>_<op>`` macros). The handler should combine the |
| 543 | assert components into a useful message for the user; though in some cases |
| 544 | this may not be possible. |
Keir Mierle | ec9bf1b | 2020-03-03 10:27:01 -0800 | [diff] [blame] | 545 | |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 546 | Consider the following example: |
| 547 | |
| 548 | .. code-block:: cpp |
| 549 | |
| 550 | int temp = 16; |
| 551 | int max_temp = 15; |
| 552 | PW_CHECK_INT_LE(temp, MAX_TEMP, "Got too hot; state: %s", GetSystemState()); |
| 553 | |
| 554 | In this block, the assert will trigger, which will cause the facade to invoke |
| 555 | the handler macro. Below is the meaning of the arguments, referencing to the |
| 556 | example: |
| 557 | |
| 558 | - ``a_str`` - Stringified first operand. In the example: ``"temp"``. |
| 559 | - ``a_val`` - The value of the first operand. In the example: ``16``. |
| 560 | - ``op_str`` - The string version of the operator. In the example: "<=". |
| 561 | - ``b_str`` - Stringified second operand. In the example: ``"max_temp"``. |
| 562 | - ``b_val`` - The value of the second operand. In the example: ``15``. |
| 563 | - ``type_fmt`` - The format code for the type. In the example: ``"%d"``. |
| 564 | - ``message, ...`` - A formatted message to go with the assert. In the |
| 565 | example: ``"Got too hot; state: %s", "ON_FIRE"``. |
| 566 | |
| 567 | .. tip:: |
| 568 | |
Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 569 | See :ref:`module-pw_assert_basic` for one way to combine these arguments |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 570 | into a meaningful error message. |
| 571 | |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 572 | Additionally, the backend must provide a link-time function for the |
| 573 | ``PW_ASSERT`` assert handler. This does not need to appear in the backend |
| 574 | header, but instead is in a ``.cc`` file. |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 575 | |
| 576 | .. cpp:function:: pw_assert_HandleFailure() |
| 577 | |
| 578 | Handle a low-level crash. This crash entry happens through |
Wyatt Hepler | a59998f | 2021-03-19 14:35:10 -0700 | [diff] [blame] | 579 | ``pw_assert/assert.h``. In this crash handler, there is no access to line, |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 580 | file, expression, or other rich assert information. Backends should do |
| 581 | something reasonable in this case; typically, capturing the stack is useful. |
| 582 | |
Wyatt Hepler | 8bd4fb0 | 2021-05-03 15:30:58 -0700 | [diff] [blame^] | 583 | Backend build targets |
| 584 | --------------------- |
| 585 | In GN, the backend must provide a ``deps`` build target in the same directory as |
| 586 | the backend target. The ``deps`` target contains the backend's dependencies that |
| 587 | could result in a dependency cycle. In the simplest case, it can be an empty |
| 588 | group. Circular dependencies are a common problem with ``pw_assert`` because it |
| 589 | is so widely used. See :ref:`module-pw_assert-circular-deps`. |
| 590 | |
Keir Mierle | 49f8e7e | 2020-07-30 17:57:30 -0700 | [diff] [blame] | 591 | -------------------------- |
| 592 | Frequently asked questions |
| 593 | -------------------------- |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 594 | |
Keir Mierle | 3f35672 | 2020-07-31 00:43:43 -0700 | [diff] [blame] | 595 | When should DCHECK_* be used instead of CHECK_* and vice versa? |
| 596 | --------------------------------------------------------------- |
| 597 | There is no hard and fast rule for when to use one or the other. |
| 598 | |
| 599 | In theory, ``DCHECK_*`` macros should never be used and all the asserts should |
| 600 | remain active in production. In practice, **assert statements come at a binary |
| 601 | size and runtime cost**, even when using extensions like a tokenized assert |
| 602 | backend that strips the stringified assert expression from the binary. Each |
| 603 | assert is **at least a branch with a function call**; depending on the assert |
| 604 | backend, that function call may take several arguments (like the message, the |
| 605 | file line number, the module, etc). These function calls can take 10-20 bytes |
| 606 | or more of ROM each. Thus, there is a balance to be struct between ``DCHECK_*`` |
| 607 | and ``CHECK_*``. |
| 608 | |
| 609 | Pigweed uses these conventions to decide between ``CHECK_*`` and ``DCHECK_*``: |
| 610 | |
| 611 | - **Prefer to use CHECK_* at public API boundaries** of modules, where an |
| 612 | invalid value is a clear programmer bug. In certain cases use ``DCHECK_*`` to |
| 613 | keep binary size small when in production; for example, in modules with a |
| 614 | large public API surface, or modules with many inlined functions in headers. |
| 615 | - **Avoid using CHECK_* macros in headers.** It is still OK to use ``CHECK_*`` |
| 616 | macros in headers, but carefully consider the cost, since inlined use of the |
| 617 | ``CHECK_*`` macros in headers will expand to the full assert cost for every |
| 618 | translation unit that includes the header and calls the function with the |
| 619 | ``CHECK_*`` instance. ``DCHECK_*`` macros are are better, but even they come |
| 620 | at a cost, since it is preferable to be able to compile a binary in debug |
| 621 | mode for as long as possible on the road to production. |
| 622 | - **Prefer to use DCHECK_* variants for internal asserts** that attempt to |
| 623 | catch module-author level programming errors. For example, use DCHECKs to |
| 624 | verify internal function preconditions, or other invariants that should |
| 625 | always be true but will likely never fire in production. In some cases using |
| 626 | ``CHECK_*`` macros for internal consistency checking can make sense, if the |
| 627 | runtime cost is low and there are only a couple of instances. |
| 628 | |
| 629 | .. tip:: |
| 630 | |
Keir Mierle | 481d829 | 2020-07-31 01:10:05 -0700 | [diff] [blame] | 631 | **Do not return error status codes for obvious API misuse** |
Keir Mierle | 3f35672 | 2020-07-31 00:43:43 -0700 | [diff] [blame] | 632 | |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 633 | Returning an error code may **mask the earliest sign of a bug** because |
| 634 | notifying the developer of the problem depends on correct propagation of the |
| 635 | error to upper levels of the system. Instead, prefer to use the ``CHECK_*`` |
| 636 | or ``DCHECK_*`` macros to ensure a prompt termination and warning to the |
| 637 | developer. |
Keir Mierle | 3f35672 | 2020-07-31 00:43:43 -0700 | [diff] [blame] | 638 | |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 639 | **Error status codes should be reserved for system misbehaviour or expected |
| 640 | exceptional cases**, like a sensor is not yet ready, or a storage subsystem |
| 641 | is full when writing. Doing ``CHECK_*`` assertions in those cases would be a |
Keir Mierle | 3f35672 | 2020-07-31 00:43:43 -0700 | [diff] [blame] | 642 | mistake; so use error codes in those cases instead. |
| 643 | |
Keir Mierle | 49f8e7e | 2020-07-30 17:57:30 -0700 | [diff] [blame] | 644 | How should objects be asserted against or compared? |
| 645 | --------------------------------------------------- |
| 646 | Unfortunatly, there is no native mechanism for this, and instead the way to |
| 647 | assert object states or comparisons is with the normal ``PW_CHECK_*`` macros |
| 648 | that operate on booleans, ints, and floats. |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 649 | |
Keir Mierle | 49f8e7e | 2020-07-30 17:57:30 -0700 | [diff] [blame] | 650 | This is due to the requirement of supporting C and also tokenization. It may be |
| 651 | possible support rich object comparions by defining a convention for |
| 652 | stringifying objects; however, this hasn't been added yet. Additionally, such a |
| 653 | mechanism would not work well with tokenization. In particular, it would |
| 654 | require runtime stringifying arguments and rendering them with ``%s``, which |
| 655 | leads to binary bloat even with tokenization. So it is likely that a rich |
| 656 | object assert API won't be added. |
| 657 | |
| 658 | Why was the assert facade designed this way? |
| 659 | -------------------------------------------- |
| 660 | The Pigweed assert API was designed taking into account the needs of several |
| 661 | past projects the team members were involved with. Based on those experiences, |
| 662 | the following were key requirements for the API: |
| 663 | |
| 664 | 1. **C compatibility** - Since asserts are typically invoked from arbitrary |
| 665 | contexts, including from vendor or third party code, the assert system must |
| 666 | have a C-compatible API. Some API functions working only in C++ is |
| 667 | acceptable, as long as the key functions work in C. |
| 668 | 2. **Capturing both expressions and values** - Since asserts can trigger in |
| 669 | ways that are not repeatable, it is important to capture rich diagnostic |
| 670 | information to help identifying the root cause of the fault. For asserts, |
| 671 | this means including the failing expression text, and optionally also |
| 672 | capturing failing expression values. For example, instead of capturing an |
| 673 | error with the expression (``x < y``), capturing an error with the |
| 674 | expression and values(``x < y, with x = 10, y = 0``). |
| 675 | 3. **Tokenization compatible** - It's important that the assert expressions |
| 676 | support tokenization; both the expression itself (e.g. ``a < b``) and the |
| 677 | message attached to the expression. For example: ``PW_CHECK(ItWorks(), "Ruh |
| 678 | roh: %d", some_int)``. |
| 679 | 4. **Customizable assert handling** - Most products need to support custom |
| 680 | handling of asserts. In some cases, an assert might trigger printing out |
| 681 | details to a UART; in other cases, it might trigger saving a log entry to |
| 682 | flash. The assert system must support this customization. |
| 683 | |
| 684 | The combination of #1, #2, and #3 led to the structure of the API. In |
| 685 | particular, the need to support tokenized asserts and the need to support |
| 686 | capturing values led to the choice of having ``PW_CHECK_INT_LE(a, b)`` instead |
| 687 | of ``PW_CHECK(a <= b)``. Needing to support tokenization is what drove the |
| 688 | facade & backend arrangement, since the backend must provide the raw macros for |
| 689 | asserting in that case, rather than terminating at a C-style API. |
| 690 | |
| 691 | Why isn't there a ``PW_CHECK_LE``? Why is the type (e.g. ``INT``) needed? |
| 692 | ------------------------------------------------------------------------- |
| 693 | The problem with asserts like ``PW_CHECK_LE(a, b)`` instead of |
| 694 | ``PW_CHECK_INT_LE(a, b)`` or ``PW_CHECK_FLOAT_EXACT_LE(a, b)`` is that to |
| 695 | capture the arguments with the tokenizer, we need to know the types. Using the |
| 696 | preprocessor, it is impossible to dispatch based on the types of ``a`` and |
| 697 | ``b``, so unfortunately having a separate macro for each of the types commonly |
| 698 | asserted on is necessary. |
Keir Mierle | c1cb12d | 2020-06-01 11:59:41 -0700 | [diff] [blame] | 699 | |
| 700 | ------------- |
| 701 | Compatibility |
| 702 | ------------- |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 703 | The facade is compatible with both C and C++. |
| 704 | |
| 705 | ---------------- |
| 706 | Roadmap & Status |
| 707 | ---------------- |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 708 | The Pigweed assert subsystem consiststs of several modules that work in |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 709 | coordination. This module is the facade (API), then a number of backends are |
| 710 | available to handle assert failures. Products can also define their own |
| 711 | backends. In some cases, the backends will have backends (like |
| 712 | ``pw_log_tokenized``). |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 713 | |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 714 | Below is a brief summary of what modules are ready for use: |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 715 | |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 716 | Available assert backends |
| 717 | ------------------------- |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 718 | - ``pw_assert`` - **Stable** - The assert facade (this module). This module is |
| 719 | stable, and in production use. The documentation is comprehensive and covers |
| 720 | the functionality. There are (a) tests for the facade macro processing logic, |
| 721 | using a fake assert backend; and (b) compile tests to verify that the |
| 722 | selected backend compiles with all supported assert constructions and types. |
| 723 | - ``pw_assert_basic`` - **Stable** - The assert basic module is a simple assert |
| 724 | handler that displays the failed assert line and the values of captured |
| 725 | arguments. Output is directed to ``pw_sys_io``. This module is a great |
| 726 | ready-to-roll module when bringing up a system, but is likely not the best |
| 727 | choice for production. |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 728 | - ``pw_assert_log`` - **Stable** - This assert backend redirects to logging, |
| 729 | but with a logging flag set that indicates an assert failure. This is our |
| 730 | advised approach to get **tokenized asserts**--by using tokenized logging, |
| 731 | then using the ``pw_assert_log`` backend. |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 732 | |
Keir Mierle | 854adec | 2020-09-03 14:07:19 -0700 | [diff] [blame] | 733 | Note: If one desires a null assert module (where asserts are removed), use |
| 734 | ``pw_assert_log`` in combination with ``pw_log_null``. This will direct asserts |
| 735 | to logs, then the logs are removed due to the null backend. |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 736 | |
| 737 | Missing functionality |
| 738 | --------------------- |
Keir Mierle | 77d3cbd | 2020-08-03 21:14:38 -0700 | [diff] [blame] | 739 | - **Stack traces** - Pigweed doesn't have a reliable stack walker, which makes |
| 740 | displaying a stack trace on crash harder. We plan to add this eventually. |
| 741 | - **Snapshot integration** - Pigweed doesn't yet have a rich system state |
| 742 | capture system that can capture state like number of tasks, available memory, |
| 743 | and so on. Snapshot facilities are the obvious ones to run inside an assert |
| 744 | handler. It'll happen someday. |