ut.h 12.9 KB
Newer Older
1
/* SPDX-License-Identifier: GPL-2.0+ */
Simon Glass's avatar
Simon Glass committed
2
/*
3
 * Simple unit test library
Simon Glass's avatar
Simon Glass committed
4
5
6
7
 *
 * Copyright (c) 2013 Google, Inc
 */

8
9
#ifndef __TEST_UT_H
#define __TEST_UT_H
Simon Glass's avatar
Simon Glass committed
10

11
#include <command.h>
12
#include <hexdump.h>
13
#include <linux/err.h>
14
#include <test/test.h>
15

16
struct unit_test_state;
Simon Glass's avatar
Simon Glass committed
17
18
19
20

/**
 * ut_fail() - Record failure of a unit test
 *
21
 * @uts: Test state
22
23
24
 * @fname: Filename where the error occurred
 * @line: Line number where the error occurred
 * @func: Function name where the error occurred
Simon Glass's avatar
Simon Glass committed
25
26
 * @cond: The condition that failed
 */
27
void ut_fail(struct unit_test_state *uts, const char *fname, int line,
Simon Glass's avatar
Simon Glass committed
28
29
30
31
32
	     const char *func, const char *cond);

/**
 * ut_failf() - Record failure of a unit test
 *
33
 * @uts: Test state
34
35
36
 * @fname: Filename where the error occurred
 * @line: Line number where the error occurred
 * @func: Function name where the error occurred
Simon Glass's avatar
Simon Glass committed
37
38
39
 * @cond: The condition that failed
 * @fmt: printf() format string for the error, followed by args
 */
40
void ut_failf(struct unit_test_state *uts, const char *fname, int line,
Simon Glass's avatar
Simon Glass committed
41
42
43
	      const char *func, const char *cond, const char *fmt, ...)
			__attribute__ ((format (__printf__, 6, 7)));

44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
/**
 * ut_check_console_line() - Check the next console line against expectations
 *
 * This creates a string and then checks it against the next line of console
 * output obtained with console_record_readline().
 *
 * After the function returns, uts->expect_str holds the expected string and
 * uts->actual_str holds the actual string read from the console.
 *
 * @uts: Test state
 * @fmt: printf() format string for the error, followed by args
 * @return 0 if OK, other value on error
 */
int ut_check_console_line(struct unit_test_state *uts, const char *fmt, ...)
			__attribute__ ((format (__printf__, 2, 3)));

60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
/**
 * ut_check_console_linen() - Check part of the next console line
 *
 * This creates a string and then checks it against the next line of console
 * output obtained with console_record_readline(). Only the length of the
 * string is checked
 *
 * After the function returns, uts->expect_str holds the expected string and
 * uts->actual_str holds the actual string read from the console.
 *
 * @uts: Test state
 * @fmt: printf() format string for the error, followed by args
 * @return 0 if OK, other value on error
 */
int ut_check_console_linen(struct unit_test_state *uts, const char *fmt, ...)
			__attribute__ ((format (__printf__, 2, 3)));

/**
 * ut_check_skipline() - Check that the next console line exists and skip it
 *
 * @uts: Test state
 * @return 0 if OK, other value on error
 */
int ut_check_skipline(struct unit_test_state *uts);

85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
/**
 * ut_check_skip_to_line() - skip output until a line is found
 *
 * This creates a string and then checks it against the following lines of
 * console output obtained with console_record_readline() until it is found.
 *
 * After the function returns, uts->expect_str holds the expected string and
 * uts->actual_str holds the actual string read from the console.
 *
 * @uts: Test state
 * @fmt: printf() format string to look for, followed by args
 * @return 0 if OK, -ENOENT if not found, other value on error
 */
int ut_check_skip_to_line(struct unit_test_state *uts, const char *fmt, ...);

100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
/**
 * ut_check_console_end() - Check there is no more console output
 *
 * After the function returns, uts->actual_str holds the actual string read
 * from the console
 *
 * @uts: Test state
 * @return 0 if OK (console has no output), other value on error
 */
int ut_check_console_end(struct unit_test_state *uts);

/**
 * ut_check_console_dump() - Check that next lines have a print_buffer() dump
 *
 * This only supports a byte dump.
 *
 * @total_bytes: Size of the expected dump in bytes`
 * @return 0 if OK (looks like a dump and the length matches), other value on
 *	error
 */
int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
Simon Glass's avatar
Simon Glass committed
121
122
123
124

/* Assert that a condition is non-zero */
#define ut_assert(cond)							\
	if (!(cond)) {							\
125
		ut_fail(uts, __FILE__, __LINE__, __func__, #cond);	\
126
		return CMD_RET_FAILURE;					\
Simon Glass's avatar
Simon Glass committed
127
128
129
130
131
	}

/* Assert that a condition is non-zero, with printf() string */
#define ut_assertf(cond, fmt, args...)					\
	if (!(cond)) {							\
132
		ut_failf(uts, __FILE__, __LINE__, __func__, #cond,	\
Simon Glass's avatar
Simon Glass committed
133
			 fmt, ##args);					\
134
		return CMD_RET_FAILURE;					\
Simon Glass's avatar
Simon Glass committed
135
136
137
138
	}

/* Assert that two int expressions are equal */
#define ut_asserteq(expr1, expr2) {					\
139
	unsigned int _val1 = (expr1), _val2 = (expr2);			\
Simon Glass's avatar
Simon Glass committed
140
									\
141
	if (_val1 != _val2) {						\
142
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
Simon Glass's avatar
Simon Glass committed
143
			 #expr1 " == " #expr2,				\
144
145
			 "Expected %#x (%d), got %#x (%d)",		\
			 _val1, _val1, _val2, _val2);			\
146
		return CMD_RET_FAILURE;					\
Simon Glass's avatar
Simon Glass committed
147
148
149
	}								\
}

150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
/* Assert that two 64 int expressions are equal */
#define ut_asserteq_64(expr1, expr2) {					\
	u64 _val1 = (expr1), _val2 = (expr2);				\
									\
	if (_val1 != _val2) {						\
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 #expr1 " == " #expr2,				\
			 "Expected %#llx (%lld), got %#llx (%lld)",	\
			 (unsigned long long)_val1,			\
			 (unsigned long long)_val1,			\
			 (unsigned long long)_val2,			\
			 (unsigned long long)_val2);			\
		return CMD_RET_FAILURE;					\
	}								\
}

Simon Glass's avatar
Simon Glass committed
166
167
/* Assert that two string expressions are equal */
#define ut_asserteq_str(expr1, expr2) {					\
168
	const char *_val1 = (expr1), *_val2 = (expr2);			\
Simon Glass's avatar
Simon Glass committed
169
									\
170
	if (strcmp(_val1, _val2)) {					\
171
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
Simon Glass's avatar
Simon Glass committed
172
			 #expr1 " = " #expr2,				\
173
			 "Expected \"%s\", got \"%s\"", _val1, _val2);	\
174
		return CMD_RET_FAILURE;					\
Simon Glass's avatar
Simon Glass committed
175
176
177
	}								\
}

178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
/*
 * Assert that two string expressions are equal, up to length of the
 * first
 */
#define ut_asserteq_strn(expr1, expr2) {				\
	const char *_val1 = (expr1), *_val2 = (expr2);			\
	int _len = strlen(_val1);					\
									\
	if (memcmp(_val1, _val2, _len)) {				\
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 #expr1 " = " #expr2,				\
			 "Expected \"%.*s\", got \"%.*s\"",		\
			 _len, _val1, _len, _val2);			\
		return CMD_RET_FAILURE;					\
	}								\
}

Mario Six's avatar
Mario Six committed
195
196
/* Assert that two memory areas are equal */
#define ut_asserteq_mem(expr1, expr2, len) {				\
197
	const u8 *_val1 = (u8 *)(expr1), *_val2 = (u8 *)(expr2);	\
Mario Six's avatar
Mario Six committed
198
199
	const uint __len = len;						\
									\
200
	if (memcmp(_val1, _val2, __len)) {				\
Mario Six's avatar
Mario Six committed
201
202
		char __buf1[64 + 1] = "\0";				\
		char __buf2[64 + 1] = "\0";				\
203
204
		bin2hex(__buf1, _val1, min(__len, (uint)32));		\
		bin2hex(__buf2, _val2, min(__len, (uint)32));		\
Mario Six's avatar
Mario Six committed
205
206
207
208
209
210
211
212
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 #expr1 " = " #expr2,				\
			 "Expected \"%s\", got \"%s\"",			\
			 __buf1, __buf2);				\
		return CMD_RET_FAILURE;					\
	}								\
}

Simon Glass's avatar
Simon Glass committed
213
214
/* Assert that two pointers are equal */
#define ut_asserteq_ptr(expr1, expr2) {					\
215
	const void *_val1 = (expr1), *_val2 = (expr2);			\
Simon Glass's avatar
Simon Glass committed
216
									\
217
	if (_val1 != _val2) {						\
218
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
Simon Glass's avatar
Simon Glass committed
219
			 #expr1 " = " #expr2,				\
220
			 "Expected %p, got %p", _val1, _val2);		\
221
		return CMD_RET_FAILURE;					\
Simon Glass's avatar
Simon Glass committed
222
223
224
	}								\
}

225
226
227
228
229
230
231
232
233
234
235
236
237
/* Assert that two addresses (converted from pointers) are equal */
#define ut_asserteq_addr(expr1, expr2) {				\
	ulong _val1 = map_to_sysmem(expr1);				\
	ulong _val2 = map_to_sysmem(expr2);				\
									\
	if (_val1 != _val2) {						\
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 #expr1 " = " #expr2,				\
			 "Expected %lx, got %lx", _val1, _val2);	\
		return CMD_RET_FAILURE;					\
	}								\
}

Ramon Fried's avatar
Ramon Fried committed
238
239
/* Assert that a pointer is NULL */
#define ut_assertnull(expr) {					\
240
	const void *_val = (expr);					\
Ramon Fried's avatar
Ramon Fried committed
241
									\
242
	if (_val) {						\
Ramon Fried's avatar
Ramon Fried committed
243
244
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 #expr " != NULL",				\
245
			 "Expected NULL, got %p", _val);		\
Ramon Fried's avatar
Ramon Fried committed
246
247
248
249
		return CMD_RET_FAILURE;					\
	}								\
}

Simon Glass's avatar
Simon Glass committed
250
251
/* Assert that a pointer is not NULL */
#define ut_assertnonnull(expr) {					\
252
	const void *_val = (expr);					\
Simon Glass's avatar
Simon Glass committed
253
									\
254
	if (!_val) {						\
255
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
Simon Glass's avatar
Simon Glass committed
256
257
			 #expr " = NULL",				\
			 "Expected non-null, got NULL");		\
258
		return CMD_RET_FAILURE;					\
Simon Glass's avatar
Simon Glass committed
259
260
261
	}								\
}

262
/* Assert that a pointer is not an error pointer */
263
#define ut_assertok_ptr(expr) {						\
264
	const void *_val = (expr);					\
265
									\
266
	if (IS_ERR(_val)) {						\
267
268
269
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 #expr " = NULL",				\
			 "Expected pointer, got error %ld",		\
270
			 PTR_ERR(_val));				\
271
272
273
274
		return CMD_RET_FAILURE;					\
	}								\
}

Simon Glass's avatar
Simon Glass committed
275
276
277
/* Assert that an operation succeeds (returns 0) */
#define ut_assertok(cond)	ut_asserteq(0, cond)

278
279
280
281
282
283
284
285
286
/* Assert that the next console output line matches */
#define ut_assert_nextline(fmt, args...)				\
	if (ut_check_console_line(uts, fmt, ##args)) {			\
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 "console", "\nExpected '%s',\n     got '%s'",	\
			 uts->expect_str, uts->actual_str);		\
		return CMD_RET_FAILURE;					\
	}								\

287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
/* Assert that the next console output line matches up to the length */
#define ut_assert_nextlinen(fmt, args...)				\
	if (ut_check_console_linen(uts, fmt, ##args)) {			\
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 "console", "\nExpected '%s',\n     got '%s'",	\
			 uts->expect_str, uts->actual_str);		\
		return CMD_RET_FAILURE;					\
	}								\

/* Assert that there is a 'next' console output line, and skip it */
#define ut_assert_skipline()						\
	if (ut_check_skipline(uts)) {					\
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 "console", "\nExpected a line, got end");	\
		return CMD_RET_FAILURE;					\
	}								\

304
305
306
307
308
309
310
311
312
/* Assert that a following console output line matches */
#define ut_assert_skip_to_line(fmt, args...)				\
	if (ut_check_skip_to_line(uts, fmt, ##args)) {			\
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 "console", "\nExpected '%s',\n     got to '%s'", \
			 uts->expect_str, uts->actual_str);		\
		return CMD_RET_FAILURE;					\
	}								\

313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
/* Assert that there is no more console output */
#define ut_assert_console_end()						\
	if (ut_check_console_end(uts)) {				\
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 "console", "Expected no more output, got '%s'",\
			 uts->actual_str);				\
		return CMD_RET_FAILURE;					\
	}								\

/* Assert that the next lines are print_buffer() dump at an address */
#define ut_assert_nextlines_are_dump(total_bytes)			\
	if (ut_check_console_dump(uts, total_bytes)) {			\
		ut_failf(uts, __FILE__, __LINE__, __func__,		\
			 "console",					\
			"Expected dump of length %x bytes, got '%s'",	\
			 total_bytes, uts->actual_str);			\
		return CMD_RET_FAILURE;					\
	}								\

332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
/**
 * ut_check_free() - Return the number of bytes free in the malloc() pool
 *
 * @return bytes free
 */
ulong ut_check_free(void);

/**
 * ut_check_delta() - Return the number of bytes allocated/freed
 *
 * @last: Last value from ut_check_free
 * @return free memory delta from @last; positive means more memory has been
 *	allocated, negative means less has been allocated (i.e. some is freed)
 */
long ut_check_delta(ulong last);

348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
/**
 * ut_silence_console() - Silence the console if requested by the user
 *
 * This stops test output from appear on the console. It is the default on
 * sandbox, unless the -v flag is given. For other boards, this does nothing.
 *
 * @uts: Test state (in case in future we want to keep state here)
 */
void ut_silence_console(struct unit_test_state *uts);

/**
 * ut_unsilence_console() - Unsilence the console after a test
 *
 * This restarts console output again and turns off console recording. This
 * happens on all boards, including sandbox.
 */
void ut_unsilence_console(struct unit_test_state *uts);

366
367
368
369
370
371
372
373
374
375
376
/**
 * ut_set_skip_delays() - Sets whether delays should be skipped
 *
 * Normally functions like mdelay() cause U-Boot to wait for a while. This
 * allows all such delays to be skipped on sandbox, to speed up tests
 *
 * @uts: Test state (in case in future we want to keep state here)
 * @skip_delays: true to skip delays, false to process them normally
 */
void ut_set_skip_delays(struct unit_test_state *uts, bool skip_delays);

377
378
379
380
381
382
383
384
385
386
387
388
389
390
/**
 * test_get_state() - Get the active test state
 *
 * @return the currently active test state, or NULL if none
 */
struct unit_test_state *test_get_state(void);

/**
 * test_set_state() - Set the active test state
 *
 * @uts: Test state to use as currently active test state, or NULL if none
 */
void test_set_state(struct unit_test_state *uts);

Simon Glass's avatar
Simon Glass committed
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
/**
 * ut_run_tests() - Run a set of tests
 *
 * This runs the test, handling any preparation and clean-up needed. It prints
 * the name of each test before running it.
 *
 * @category: Category of these tests. This is a string printed at the start to
 *	announce the the number of tests
 * @prefix: String prefix for the tests. Any tests that have this prefix will be
 *	printed without the prefix, so that it is easier to see the unique part
 *	of the test name. If NULL, no prefix processing is done
 * @tests: List of tests to run
 * @count: Number of tests to run
 * @select_name: Name of a single test to run (from the list provided). If NULL
 *	then all tests are run
 * @return 0 if all tests passed, -1 if any failed
 */
int ut_run_list(const char *name, const char *prefix, struct unit_test *tests,
		int count, const char *select_name);

Simon Glass's avatar
Simon Glass committed
411
#endif