1 /* SPDX-License-Identifier: GPL-2.0+ */
3 * Simple unit test library
5 * Copyright (c) 2013 Google, Inc
13 #include <linux/err.h>
14 #include <test/test.h>
16 struct unit_test_state;
19 * ut_fail() - Record failure of a unit test
22 * @fname: Filename where the error occurred
23 * @line: Line number where the error occurred
24 * @func: Function name where the error occurred
25 * @cond: The condition that failed
27 void ut_fail(struct unit_test_state *uts, const char *fname, int line,
28 const char *func, const char *cond);
31 * ut_failf() - Record failure of a unit test
34 * @fname: Filename where the error occurred
35 * @line: Line number where the error occurred
36 * @func: Function name where the error occurred
37 * @cond: The condition that failed
38 * @fmt: printf() format string for the error, followed by args
40 void ut_failf(struct unit_test_state *uts, const char *fname, int line,
41 const char *func, const char *cond, const char *fmt, ...)
42 __attribute__ ((format (__printf__, 6, 7)));
45 * ut_check_console_line() - Check the next console line against expectations
47 * This creates a string and then checks it against the next line of console
48 * output obtained with console_record_readline().
50 * After the function returns, uts->expect_str holds the expected string and
51 * uts->actual_str holds the actual string read from the console.
54 * @fmt: printf() format string for the error, followed by args
55 * @return 0 if OK, other value on error
57 int ut_check_console_line(struct unit_test_state *uts, const char *fmt, ...)
58 __attribute__ ((format (__printf__, 2, 3)));
61 * ut_check_console_linen() - Check part of the next console line
63 * This creates a string and then checks it against the next line of console
64 * output obtained with console_record_readline(). Only the length of the
67 * After the function returns, uts->expect_str holds the expected string and
68 * uts->actual_str holds the actual string read from the console.
71 * @fmt: printf() format string for the error, followed by args
72 * @return 0 if OK, other value on error
74 int ut_check_console_linen(struct unit_test_state *uts, const char *fmt, ...)
75 __attribute__ ((format (__printf__, 2, 3)));
78 * ut_check_skipline() - Check that the next console line exists and skip it
81 * @return 0 if OK, other value on error
83 int ut_check_skipline(struct unit_test_state *uts);
86 * ut_check_console_end() - Check there is no more console output
88 * After the function returns, uts->actual_str holds the actual string read
92 * @return 0 if OK (console has no output), other value on error
94 int ut_check_console_end(struct unit_test_state *uts);
97 * ut_check_console_dump() - Check that next lines have a print_buffer() dump
99 * This only supports a byte dump.
101 * @total_bytes: Size of the expected dump in bytes`
102 * @return 0 if OK (looks like a dump and the length matches), other value on
105 int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
107 /* Assert that a condition is non-zero */
108 #define ut_assert(cond) \
110 ut_fail(uts, __FILE__, __LINE__, __func__, #cond); \
111 return CMD_RET_FAILURE; \
114 /* Assert that a condition is non-zero, with printf() string */
115 #define ut_assertf(cond, fmt, args...) \
117 ut_failf(uts, __FILE__, __LINE__, __func__, #cond, \
119 return CMD_RET_FAILURE; \
122 /* Assert that two int expressions are equal */
123 #define ut_asserteq(expr1, expr2) { \
124 unsigned int _val1 = (expr1), _val2 = (expr2); \
126 if (_val1 != _val2) { \
127 ut_failf(uts, __FILE__, __LINE__, __func__, \
128 #expr1 " == " #expr2, \
129 "Expected %#x (%d), got %#x (%d)", \
130 _val1, _val1, _val2, _val2); \
131 return CMD_RET_FAILURE; \
135 /* Assert that two 64 int expressions are equal */
136 #define ut_asserteq_64(expr1, expr2) { \
137 u64 _val1 = (expr1), _val2 = (expr2); \
139 if (_val1 != _val2) { \
140 ut_failf(uts, __FILE__, __LINE__, __func__, \
141 #expr1 " == " #expr2, \
142 "Expected %#llx (%lld), got %#llx (%lld)", \
143 (unsigned long long)_val1, \
144 (unsigned long long)_val1, \
145 (unsigned long long)_val2, \
146 (unsigned long long)_val2); \
147 return CMD_RET_FAILURE; \
151 /* Assert that two string expressions are equal */
152 #define ut_asserteq_str(expr1, expr2) { \
153 const char *_val1 = (expr1), *_val2 = (expr2); \
155 if (strcmp(_val1, _val2)) { \
156 ut_failf(uts, __FILE__, __LINE__, __func__, \
157 #expr1 " = " #expr2, \
158 "Expected \"%s\", got \"%s\"", _val1, _val2); \
159 return CMD_RET_FAILURE; \
164 * Assert that two string expressions are equal, up to length of the
167 #define ut_asserteq_strn(expr1, expr2) { \
168 const char *_val1 = (expr1), *_val2 = (expr2); \
169 int _len = strlen(_val1); \
171 if (memcmp(_val1, _val2, _len)) { \
172 ut_failf(uts, __FILE__, __LINE__, __func__, \
173 #expr1 " = " #expr2, \
174 "Expected \"%.*s\", got \"%.*s\"", \
175 _len, _val1, _len, _val2); \
176 return CMD_RET_FAILURE; \
181 * Assert that two string expressions are equal, up to length of the
184 #define ut_asserteq_strn(expr1, expr2) { \
185 const char *_val1 = (expr1), *_val2 = (expr2); \
186 int _len = strlen(_val1); \
188 if (memcmp(_val1, _val2, _len)) { \
189 ut_failf(uts, __FILE__, __LINE__, __func__, \
190 #expr1 " = " #expr2, \
191 "Expected \"%.*s\", got \"%.*s\"", \
192 _len, _val1, _len, _val2); \
193 return CMD_RET_FAILURE; \
197 /* Assert that two memory areas are equal */
198 #define ut_asserteq_mem(expr1, expr2, len) { \
199 const u8 *_val1 = (u8 *)(expr1), *_val2 = (u8 *)(expr2); \
200 const uint __len = len; \
202 if (memcmp(_val1, _val2, __len)) { \
203 char __buf1[64 + 1] = "\0"; \
204 char __buf2[64 + 1] = "\0"; \
205 bin2hex(__buf1, _val1, min(__len, (uint)32)); \
206 bin2hex(__buf2, _val2, min(__len, (uint)32)); \
207 ut_failf(uts, __FILE__, __LINE__, __func__, \
208 #expr1 " = " #expr2, \
209 "Expected \"%s\", got \"%s\"", \
211 return CMD_RET_FAILURE; \
215 /* Assert that two pointers are equal */
216 #define ut_asserteq_ptr(expr1, expr2) { \
217 const void *_val1 = (expr1), *_val2 = (expr2); \
219 if (_val1 != _val2) { \
220 ut_failf(uts, __FILE__, __LINE__, __func__, \
221 #expr1 " = " #expr2, \
222 "Expected %p, got %p", _val1, _val2); \
223 return CMD_RET_FAILURE; \
227 /* Assert that two addresses (converted from pointers) are equal */
228 #define ut_asserteq_addr(expr1, expr2) { \
229 ulong _val1 = map_to_sysmem(expr1); \
230 ulong _val2 = map_to_sysmem(expr2); \
232 if (_val1 != _val2) { \
233 ut_failf(uts, __FILE__, __LINE__, __func__, \
234 #expr1 " = " #expr2, \
235 "Expected %lx, got %lx", _val1, _val2); \
236 return CMD_RET_FAILURE; \
240 /* Assert that a pointer is NULL */
241 #define ut_assertnull(expr) { \
242 const void *_val = (expr); \
245 ut_failf(uts, __FILE__, __LINE__, __func__, \
247 "Expected NULL, got %p", _val); \
248 return CMD_RET_FAILURE; \
252 /* Assert that a pointer is not NULL */
253 #define ut_assertnonnull(expr) { \
254 const void *_val = (expr); \
257 ut_failf(uts, __FILE__, __LINE__, __func__, \
259 "Expected non-null, got NULL"); \
260 return CMD_RET_FAILURE; \
264 /* Assert that a pointer is not an error pointer */
265 #define ut_assertok_ptr(expr) { \
266 const void *_val = (expr); \
268 if (IS_ERR(_val)) { \
269 ut_failf(uts, __FILE__, __LINE__, __func__, \
271 "Expected pointer, got error %ld", \
273 return CMD_RET_FAILURE; \
277 /* Assert that an operation succeeds (returns 0) */
278 #define ut_assertok(cond) ut_asserteq(0, cond)
280 /* Assert that the next console output line matches */
281 #define ut_assert_nextline(fmt, args...) \
282 if (ut_check_console_line(uts, fmt, ##args)) { \
283 ut_failf(uts, __FILE__, __LINE__, __func__, \
284 "console", "\nExpected '%s',\n got '%s'", \
285 uts->expect_str, uts->actual_str); \
286 return CMD_RET_FAILURE; \
289 /* Assert that the next console output line matches up to the length */
290 #define ut_assert_nextlinen(fmt, args...) \
291 if (ut_check_console_linen(uts, fmt, ##args)) { \
292 ut_failf(uts, __FILE__, __LINE__, __func__, \
293 "console", "\nExpected '%s',\n got '%s'", \
294 uts->expect_str, uts->actual_str); \
295 return CMD_RET_FAILURE; \
298 /* Assert that there is a 'next' console output line, and skip it */
299 #define ut_assert_skipline() \
300 if (ut_check_skipline(uts)) { \
301 ut_failf(uts, __FILE__, __LINE__, __func__, \
302 "console", "\nExpected a line, got end"); \
303 return CMD_RET_FAILURE; \
306 /* Assert that there is no more console output */
307 #define ut_assert_console_end() \
308 if (ut_check_console_end(uts)) { \
309 ut_failf(uts, __FILE__, __LINE__, __func__, \
310 "console", "Expected no more output, got '%s'",\
312 return CMD_RET_FAILURE; \
315 /* Assert that the next lines are print_buffer() dump at an address */
316 #define ut_assert_nextlines_are_dump(total_bytes) \
317 if (ut_check_console_dump(uts, total_bytes)) { \
318 ut_failf(uts, __FILE__, __LINE__, __func__, \
320 "Expected dump of length %x bytes, got '%s'", \
321 total_bytes, uts->actual_str); \
322 return CMD_RET_FAILURE; \
326 * ut_check_free() - Return the number of bytes free in the malloc() pool
330 ulong ut_check_free(void);
333 * ut_check_delta() - Return the number of bytes allocated/freed
335 * @last: Last value from ut_check_free
336 * @return free memory delta from @last; positive means more memory has been
337 * allocated, negative means less has been allocated (i.e. some is freed)
339 long ut_check_delta(ulong last);
342 * ut_silence_console() - Silence the console if requested by the user
344 * This stops test output from appear on the console. It is the default on
345 * sandbox, unless the -v flag is given. For other boards, this does nothing.
347 * @uts: Test state (in case in future we want to keep state here)
349 void ut_silence_console(struct unit_test_state *uts);
352 * ut_unsilence_console() - Unsilence the console after a test
354 * This restarts console output again and turns off console recording. This
355 * happens on all boards, including sandbox.
357 void ut_unsilence_console(struct unit_test_state *uts);
360 * ut_run_tests() - Run a set of tests
362 * This runs the tests, handling any preparation and clean-up needed. It prints
363 * the name of each test before running it.
365 * @uts: Test state to update. The caller should ensure that this is zeroed for
366 * the first call to this function. On exit, @uts->fail_count is
367 * incremented by the number of failures (0, one hopes)
368 * @prefix: String prefix for the tests. Any tests that have this prefix will be
369 * printed without the prefix, so that it is easier to see the unique part
370 * of the test name. If NULL, no prefix processing is done
371 * @tests: List of tests to run
372 * @count: Number of tests to run
373 * @select_name: Name of a single test to run (from the list provided). If NULL
374 * then all tests are run
375 * @return 0 if all tests passed, -ENOENT if test @select_name was not found,
376 * -EBADF if any failed
378 int ut_run_tests(struct unit_test_state *uts, const char *prefix,
379 struct unit_test *tests, int count, const char *select_name);
382 * ut_run_tests() - Run a set of tests
384 * This runs the test, handling any preparation and clean-up needed. It prints
385 * the name of each test before running it.
387 * @category: Category of these tests. This is a string printed at the start to
388 * announce the the number of tests
389 * @prefix: String prefix for the tests. Any tests that have this prefix will be
390 * printed without the prefix, so that it is easier to see the unique part
391 * of the test name. If NULL, no prefix processing is done
392 * @tests: List of tests to run
393 * @count: Number of tests to run
394 * @select_name: Name of a single test to run (from the list provided). If NULL
395 * then all tests are run
396 * @return 0 if all tests passed, -1 if any failed
398 int ut_run_list(const char *name, const char *prefix, struct unit_test *tests,
399 int count, const char *select_name);