Software APIs
check.h
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#ifndef OPENTITAN_SW_DEVICE_LIB_TESTING_TEST_FRAMEWORK_CHECK_H_
6#define OPENTITAN_SW_DEVICE_LIB_TESTING_TEST_FRAMEWORK_CHECK_H_
7
8#include <stdbool.h>
9
10#include "sw/device/lib/base/macros.h"
11#include "sw/device/lib/base/memory.h"
12#include "sw/device/lib/base/status.h"
13#include "sw/device/lib/dif/dif_base.h"
14#include "sw/device/lib/runtime/hart.h"
15#include "sw/device/lib/runtime/log.h"
16#include "sw/device/lib/testing/test_framework/status.h"
17
18/**
19 * Runtime assertion macros with log.h integration.
20 */
21
22#ifdef __cplusplus
23#error "This file is C-only; it is not a polyglot header!"
24#endif
25
26/**
27 * Checks that the given condition is true. If the condition is false, this
28 * function logs and then returns a `kInternal` error.
29 *
30 * @param condition An expression to check.
31 * @param ... Arguments to a LOG_* macro, which are evaluated if the check
32 * fails.
33 */
34#define CHECK_IMPL(condition, ...) \
35 ({ \
36 status_t sts_ = OK_STATUS(); \
37 /* NOTE: The volatile intermediate variable is added to guarantee that \
38 * this macro won't be optimized out when used with compiling time \
39 * constants.*/ \
40 volatile bool res_ = (condition); \
41 if (!res_) { \
42 /* NOTE: because the condition in this if \
43 statement can be statically determined, \
44 only one of the below string constants \
45 will be included in the final binary.*/ \
46 if (OT_VA_ARGS_COUNT(_, ##__VA_ARGS__) == 0) { \
47 LOG_ERROR("CHECK-fail: " #condition); \
48 } else { \
49 LOG_ERROR("CHECK-fail: " __VA_ARGS__); \
50 } \
51 sts_ = INTERNAL(); \
52 } \
53 sts_; \
54 })
55
56/**
57 * Checks that the given condition is true. If the condition is false, this
58 * function logs and then aborts.
59 *
60 * @param condition An expression to check.
61 * @param ... Arguments to a LOG_* macro, which are evaluated if the check
62 * fails.
63 */
64#define CHECK(condition, ...) \
65 do { \
66 if (status_err(CHECK_IMPL(condition, ##__VA_ARGS__))) { \
67 /* Currently, this macro will call into \
68 the test failure code, which logs \
69 "FAIL" and aborts. In the future, \
70 we will try to condition on whether \
71 or not this is a test.*/ \
72 test_status_set(kTestStatusFailed); \
73 } \
74 } while (false)
75
76/**
77 * Same as `CHECK` above but returns a status_t if false rather than aborting.
78 */
79#define TRY_CHECK(condition, ...) TRY(CHECK_IMPL(condition, ##__VA_ARGS__))
80
81// Note that this is *not* a polyglot header, so we can use the C11-only
82// _Generic keyword safely.
83// See: https://en.cppreference.com/w/c/language/generic
84// clang-format off
85#define SHOW_MISMATCH_FMT_STR_(a) _Generic((a), \
86 bool: "CHECK-fail: [%d] got: 0x%02x; want: 0x%02x", \
87 int8_t: "CHECK-fail: [%d] got: 0x%02x; want: 0x%02x", \
88 uint8_t: "CHECK-fail: [%d] got: 0x%02x; want: 0x%02x", \
89 int16_t: "CHECK-fail: [%d] got: 0x%04x; want: 0x%04x", \
90 uint16_t: "CHECK-fail: [%d] got: 0x%04x; want: 0x%04x", \
91 int32_t: "CHECK-fail: [%d] got: 0x%08x; want: 0x%08x", \
92 uint32_t: "CHECK-fail: [%d] got: 0x%08x; want: 0x%08x", \
93 int64_t: "CHECK-fail: [%d] got: 0x%016x; want: 0x%016x", \
94 uint64_t: "CHECK-fail: [%d] got: 0x%016x; want: 0x%016x")
95#define SHOW_MATCH_FMT_STR_(a) _Generic((a), \
96 bool: "CHECK-fail: [%d] both equal: 0x%02x", \
97 int8_t: "CHECK-fail: [%d] both equal: 0x%02x", \
98 uint8_t: "CHECK-fail: [%d] both equal: 0x%02x", \
99 int16_t: "CHECK-fail: [%d] both equal: 0x%04x", \
100 uint16_t: "CHECK-fail: [%d] both equal: 0x%04x", \
101 int32_t: "CHECK-fail: [%d] both equal: 0x%08x", \
102 uint32_t: "CHECK-fail: [%d] both equal: 0x%08x", \
103 int64_t: "CHECK-fail: [%d] both equal: 0x%016x", \
104 uint64_t: "CHECK-fail: [%d] both equal: 0x%016x")
105// clang-format on
106
107/**
108 * Compare `actual_` against `ref_` buffer.
109 *
110 * Prints matches between `actual_` and `ref_` before logging an error.
111 *
112 * @param expect_eq_ True if the arrays are expected to be equal, false
113 * otherwise.
114 * @param actual_ Buffer containing actual values.
115 * @param ref_ Buffer containing the reference values.
116 * @param size_ Number of items to compare.
117 * @param ... Arguments to a LOG_* macro, which are evaluated if the check.
118 * @return Either `kOk` or `kInternal`.
119 */
120
121#define CHECK_ARRAYS_IMPL(expect_eq_, actual_, ref_, size_, ...) \
122 ({ \
123 static_assert(sizeof(*(actual_)) == sizeof(*(ref_)), \
124 "CHECK_ARRAYS requires arguments of equal size."); \
125 status_t sts_ = OK_STATUS(); \
126 volatile bool is_eq = \
127 memcmp((actual_), (ref_), size_ * sizeof(*(actual_))) == 0; \
128 if (is_eq != expect_eq_) { \
129 if (OT_VA_ARGS_COUNT(_, ##__VA_ARGS__) == 0) { \
130 LOG_INFO("CHECK-fail: " #actual_ " %smatches " #ref_, \
131 expect_eq_ ? " un" : " "); \
132 } else { \
133 LOG_INFO("CHECK-fail: " __VA_ARGS__); \
134 } \
135 for (size_t i = 0; i < size_; ++i) { \
136 if (expect_eq_) { \
137 LOG_INFO(SHOW_MISMATCH_FMT_STR_((actual_)[i]), i, (actual_)[i], \
138 (ref_)[i]); \
139 } else { \
140 LOG_INFO(SHOW_MATCH_FMT_STR_((actual_)[i]), i, (actual_)[i]); \
141 } \
142 } \
143 sts_ = INTERNAL(); \
144 } \
145 sts_; \
146 })
147
148/**
149 * Compare `num_items_` of `actual_` against `expected_` buffer.
150 *
151 * Prints differences between `actual_` and `expected_` before logging an error.
152 * Note in case the arrays are not equal the test will be terminated.
153 * @param actual_ Buffer containing actual values.
154 * @param expected_ Buffer containing expected values.
155 * @param num_items_ Number of items to compare.
156 * @param ... Arguments to a LOG_* macro, which are evaluated if the check.
157 */
158#define CHECK_ARRAYS_EQ(actual_, expected_, num_items_, ...) \
159 do { \
160 if (status_err(CHECK_ARRAYS_IMPL(true, actual_, expected_, num_items_, \
161 ##__VA_ARGS__))) { \
162 /* Currently, this macro will call into the test failure code, \
163 which logs "FAIL" and aborts. In the future, we will try to \
164 condition on whether or not this is a test.*/ \
165 test_status_set(kTestStatusFailed); \
166 } \
167 } while (false)
168
169/**
170 * Same as `CHECK_ARRAYS_EQ` above but returns `kInternal` if the arrays are not
171 * equal rather than aborting.
172 */
173#define TRY_CHECK_ARRAYS_EQ(actual_, expected_, num_items_, ...) \
174 TRY(CHECK_ARRAYS_IMPL(true, actual_, expected_, num_items_, ##__VA_ARGS__))
175
176/**
177 * Same as `CHECK_ARRAYS_NE` above but returns `kInternal` if the arrays are not
178 * equal rather than aborting.
179 */
180#define TRY_CHECK_ARRAYS_NE(actual_, expected_, num_items_, ...) \
181 TRY(CHECK_ARRAYS_IMPL(false, actual_, expected_, num_items_, ##__VA_ARGS__))
182
183/**
184 * Compare `num_items_` of `actual_` against `not_expected_` buffer.
185 *
186 * Prints matches between `actual_` and `not_expected_` before logging an error.
187 *
188 * @param actual_ Buffer containing actual values.
189 * @param not_expected_ Buffer containing not expected values.
190 * @param num_items_ Number of items to compare.
191 * @param ... Arguments to a LOG_* macro, which are evaluated if the check.
192 */
193#define CHECK_ARRAYS_NE(actual_, not_expected_, num_items_, ...) \
194 do { \
195 if (status_err(CHECK_ARRAYS_IMPL(false, actual_, not_expected_, \
196 num_items_, ##__VA_ARGS__))) { \
197 /* Currently, this macro will call into the test failure code, which \
198 logs "FAIL" and aborts. In the future, we will try to condition on \
199 whether or not this is a test.*/ \
200 test_status_set(kTestStatusFailed); \
201 } \
202 } while (false)
203
204/**
205 * Checks the characters of two strings are the same, up to and including the
206 * first null character. The CHECK macro is called on each character pair.
207 *
208 * @param actual_ The first string in the comparison.
209 * @param expected_ The second string in the comparison.
210 */
211#define CHECK_STR_EQ(actual_, expected_) \
212 do { \
213 size_t i = 0; \
214 const char *expected = (expected_); \
215 const char *actual = (actual_); \
216 do { \
217 CHECK(actual[i] == expected[i], \
218 "Strings differ at char %d, so \"%s\" != \"%s\".", i, actual, \
219 expected); \
220 ++i; \
221 } while (actual[i] != '\0' || expected[i] != '\0'); \
222 } while (false)
223
224/**
225 * Checks that the given DIF call returns kDifOk. If the DIF call returns a
226 * different dif_result_t value (defined in sw/device/lib/dif/dif_base.h), this
227 * function logs and then aborts.
228 *
229 * @param dif_call DIF call to invoke and check its return value.
230 * @param ... Arguments to a LOG_* macro, which are evaluated if the check
231 * fails.
232 */
233#define CHECK_DIF_OK(dif_call, ...) \
234 do { \
235 dif_result_t dif_result = dif_call; \
236 if (dif_result != kDifOk) { \
237 /* NOTE: because the condition in this if \
238 statement can be statically determined, \
239 only one of the below string constants \
240 will be included in the final binary.*/ \
241 if (OT_VA_ARGS_COUNT(_, ##__VA_ARGS__) == 0) { \
242 LOG_ERROR("DIF-fail: " #dif_call " returns %d", dif_result); \
243 } else { \
244 LOG_ERROR("DIF-fail: " __VA_ARGS__); \
245 } \
246 /* Currently, this macro will call into \
247 the test failure code, which logs \
248 "FAIL" and aborts. In the future, \
249 we will try to condition on whether \
250 or not this is a test.*/ \
251 test_status_set(kTestStatusFailed); \
252 } \
253 } while (false)
254
255/**
256 * Prints `status_t` using a format compatible with DV.
257 *
258 * The %r specifier supported by the software print module is no compatible with
259 * the DV environment.
260 *
261 * If you landed here after reviewing a DV error log: Please read the status.h
262 * documentation for more details on how `status_t` encodes the module id, line
263 * number and error code.
264 *
265 * @param expr An expression which evaluates to a `status_t`.
266 *
267 */
268#define _LOG_ERROR_STATUS_DV(expr) \
269 do { \
270 status_t status_ = expr; \
271 const char *msg; \
272 char mod_id[3] = {0}; \
273 int line; \
274 if (status_extract(status_, &msg, &line, mod_id)) { \
275 LOG_ERROR("CHECK-STATUS-fail: %c%c%c:%d = %s", mod_id[0], mod_id[1], \
276 mod_id[2], line, msg); \
277 } else { \
278 LOG_ERROR("CHECK-STATUS-fail: 0x%08x", status_); \
279 } \
280 } while (false)
281
282/**
283 * Unwrap a `status_t` when it represents a non-error value, otherwise prints a
284 * human-readable error message and abort.
285 *
286 * @param expr An expression which evaluates to a `status_t`.
287 */
288#define UNWRAP(expr, ...) \
289 ({ \
290 status_t status_ = expr; \
291 if (!status_ok(status_)) { \
292 if (device_log_bypass_uart_address()) { \
293 _LOG_ERROR_STATUS_DV(status_); \
294 } else { \
295 LOG_ERROR("CHECK-STATUS-fail: %r", status_); \
296 } \
297 test_status_set(kTestStatusFailed); \
298 } \
299 status_.value; \
300 })
301
302/**
303 * Checks that the `status_t` represents a non-error value.
304 *
305 * Prints a human-readable error message if the status represents an error.
306 *
307 * @param expr An expression which evaluates to a `status_t`.
308 */
309#define CHECK_STATUS_OK(expr, ...) \
310 do { \
311 status_t status_ = expr; \
312 if (!status_ok(status_)) { \
313 if (device_log_bypass_uart_address()) { \
314 _LOG_ERROR_STATUS_DV(status_); \
315 } else { \
316 LOG_ERROR("CHECK-STATUS-fail: %r", status_); \
317 } \
318 test_status_set(kTestStatusFailed); \
319 } \
320 } while (false)
321
322/**
323 * Checks that the `status_t` represents a error value.
324 *
325 * Prints a human-readable error message if the status represents an non-error.
326 *
327 * @param expr An expression which evaluates to a `status_t`.
328 */
329#define CHECK_STATUS_NOT_OK(expr, ...) \
330 do { \
331 status_t status_ = expr; \
332 if (status_ok(status_)) { \
333 if (device_log_bypass_uart_address()) { \
334 _LOG_ERROR_STATUS_DV(status_); \
335 } else { \
336 LOG_ERROR("CHECK-STATUS-fail: %r", status_); \
337 } \
338 test_status_set(kTestStatusFailed); \
339 } \
340 } while (false)
341
342#endif // OPENTITAN_SW_DEVICE_LIB_TESTING_TEST_FRAMEWORK_CHECK_H_