1 /* SPDX-License-Identifier: GPL-2.0+ */ 2 /* 3 * Simple unit test library 4 * 5 * Copyright (c) 2013 Google, Inc 6 */ 7 8 #ifndef __TEST_UT_H 9 #define __TEST_UT_H 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; 17 18 /** 19 * ut_fail() - Record failure of a unit test 20 * 21 * @uts: Test state 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 26 */ 27 void ut_fail(struct unit_test_state *uts, const char *fname, int line, 28 const char *func, const char *cond); 29 30 /** 31 * ut_failf() - Record failure of a unit test 32 * 33 * @uts: Test state 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 39 */ 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))); 43 44 /** 45 * ut_check_console_line() - Check the next console line against expectations 46 * 47 * This creates a string and then checks it against the next line of console 48 * output obtained with console_record_readline(). 49 * 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. 52 * 53 * @uts: Test state 54 * @fmt: printf() format string for the error, followed by args 55 * Return: 0 if OK, other value on error 56 */ 57 int ut_check_console_line(struct unit_test_state *uts, const char *fmt, ...) 58 __attribute__ ((format (__printf__, 2, 3))); 59 60 /** 61 * ut_check_console_linen() - Check part of the next console line 62 * 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 65 * string is checked 66 * 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. 69 * 70 * @uts: Test state 71 * @fmt: printf() format string for the error, followed by args 72 * Return: 0 if OK, other value on error 73 */ 74 int ut_check_console_linen(struct unit_test_state *uts, const char *fmt, ...) 75 __attribute__ ((format (__printf__, 2, 3))); 76 77 /** 78 * ut_check_skipline() - Check that the next console line exists and skip it 79 * 80 * @uts: Test state 81 * Return: 0 if OK, other value on error 82 */ 83 int ut_check_skipline(struct unit_test_state *uts); 84 85 /** 86 * ut_check_skip_to_line() - skip output until a line is found 87 * 88 * This creates a string and then checks it against the following lines of 89 * console output obtained with console_record_readline() until it is found. 90 * 91 * After the function returns, uts->expect_str holds the expected string and 92 * uts->actual_str holds the actual string read from the console. 93 * 94 * @uts: Test state 95 * @fmt: printf() format string to look for, followed by args 96 * Return: 0 if OK, -ENOENT if not found, other value on error 97 */ 98 int ut_check_skip_to_line(struct unit_test_state *uts, const char *fmt, ...); 99 100 /** 101 * ut_check_skip_to_linen() - skip output until a partial line is found 102 * 103 * This creates a string and then checks it against the following lines of 104 * console output obtained with console_record_readline() until it is found. 105 * Only the characters up to the length of the string are checked, so the line 106 * may extend further 107 * 108 * After the function returns, uts->expect_str holds the expected string and 109 * uts->actual_str holds the actual string read from the console. 110 * 111 * @uts: Test state 112 * @fmt: printf() format string to look for, followed by args 113 * Return: 0 if OK, -ENOENT if not found, other value on error 114 */ 115 int ut_check_skip_to_linen(struct unit_test_state *uts, const char *fmt, ...); 116 117 /** 118 * ut_check_console_end() - Check there is no more console output 119 * 120 * After the function returns, uts->actual_str holds the actual string read 121 * from the console 122 * 123 * @uts: Test state 124 * Return: 0 if OK (console has no output), other value on error 125 */ 126 int ut_check_console_end(struct unit_test_state *uts); 127 128 /** 129 * ut_check_console_dump() - Check that next lines have a print_buffer() dump 130 * 131 * This only supports a byte dump. 132 * 133 * @total_bytes: Size of the expected dump in bytes` 134 * Return: 0 if OK (looks like a dump and the length matches), other value on 135 * error 136 */ 137 int ut_check_console_dump(struct unit_test_state *uts, int total_bytes); 138 139 /* Report a failure, with printf() string */ 140 #define ut_reportf(fmt, args...) \ 141 ut_failf(uts, __FILE__, __LINE__, __func__, "report", \ 142 fmt, ##args) 143 144 /* Assert that a condition is non-zero */ 145 #define ut_assert(cond) ({ \ 146 int __ret = 0; \ 147 \ 148 if (!(cond)) { \ 149 ut_fail(uts, __FILE__, __LINE__, __func__, #cond); \ 150 return CMD_RET_FAILURE; \ 151 } \ 152 __ret; \ 153 }) 154 155 /* Assert that a condition is non-zero, with printf() string */ 156 #define ut_assertf(cond, fmt, args...) ({ \ 157 int __ret = 0; \ 158 \ 159 if (!(cond)) { \ 160 ut_failf(uts, __FILE__, __LINE__, __func__, #cond, \ 161 fmt, ##args); \ 162 return CMD_RET_FAILURE; \ 163 } \ 164 __ret; \ 165 }) 166 167 /* Assert that two int expressions are equal */ 168 #define ut_asserteq(expr1, expr2) ({ \ 169 unsigned int _val1 = (expr1), _val2 = (expr2); \ 170 int __ret = 0; \ 171 \ 172 if (_val1 != _val2) { \ 173 ut_failf(uts, __FILE__, __LINE__, __func__, \ 174 #expr1 " == " #expr2, \ 175 "Expected %#x (%d), got %#x (%d)", \ 176 _val1, _val1, _val2, _val2); \ 177 return CMD_RET_FAILURE; \ 178 } \ 179 __ret; \ 180 }) 181 182 /* Assert that two 64 int expressions are equal */ 183 #define ut_asserteq_64(expr1, expr2) ({ \ 184 u64 _val1 = (expr1), _val2 = (expr2); \ 185 int __ret = 0; \ 186 \ 187 if (_val1 != _val2) { \ 188 ut_failf(uts, __FILE__, __LINE__, __func__, \ 189 #expr1 " == " #expr2, \ 190 "Expected %#llx (%lld), got %#llx (%lld)", \ 191 (unsigned long long)_val1, \ 192 (unsigned long long)_val1, \ 193 (unsigned long long)_val2, \ 194 (unsigned long long)_val2); \ 195 return CMD_RET_FAILURE; \ 196 } \ 197 __ret; \ 198 }) 199 200 /* Assert that two string expressions are equal */ 201 #define ut_asserteq_str(expr1, expr2) ({ \ 202 const char *_val1 = (expr1), *_val2 = (expr2); \ 203 int __ret = 0; \ 204 \ 205 if (strcmp(_val1, _val2)) { \ 206 ut_failf(uts, __FILE__, __LINE__, __func__, \ 207 #expr1 " = " #expr2, \ 208 "Expected \"%s\", got \"%s\"", _val1, _val2); \ 209 return CMD_RET_FAILURE; \ 210 } \ 211 __ret; \ 212 }) 213 214 /* 215 * Assert that two string expressions are equal, up to length of the 216 * first 217 */ 218 #define ut_asserteq_strn(expr1, expr2) ({ \ 219 const char *_val1 = (expr1), *_val2 = (expr2); \ 220 int _len = strlen(_val1); \ 221 int __ret = 0; \ 222 \ 223 if (memcmp(_val1, _val2, _len)) { \ 224 ut_failf(uts, __FILE__, __LINE__, __func__, \ 225 #expr1 " = " #expr2, \ 226 "Expected \"%.*s\", got \"%.*s\"", \ 227 _len, _val1, _len, _val2); \ 228 return CMD_RET_FAILURE; \ 229 } \ 230 __ret; \ 231 }) 232 233 /* Assert that two memory areas are equal */ 234 #define ut_asserteq_mem(expr1, expr2, len) ({ \ 235 const u8 *_val1 = (u8 *)(expr1), *_val2 = (u8 *)(expr2); \ 236 const uint __len = len; \ 237 int __ret = 0; \ 238 \ 239 if (memcmp(_val1, _val2, __len)) { \ 240 char __buf1[64 + 1] = "\0"; \ 241 char __buf2[64 + 1] = "\0"; \ 242 bin2hex(__buf1, _val1, min(__len, (uint)32)); \ 243 bin2hex(__buf2, _val2, min(__len, (uint)32)); \ 244 ut_failf(uts, __FILE__, __LINE__, __func__, \ 245 #expr1 " = " #expr2, \ 246 "Expected \"%s\", got \"%s\"", \ 247 __buf1, __buf2); \ 248 return CMD_RET_FAILURE; \ 249 } \ 250 __ret; \ 251 }) 252 253 /* Assert that two pointers are equal */ 254 #define ut_asserteq_ptr(expr1, expr2) ({ \ 255 const void *_val1 = (expr1), *_val2 = (expr2); \ 256 int __ret = 0; \ 257 \ 258 if (_val1 != _val2) { \ 259 ut_failf(uts, __FILE__, __LINE__, __func__, \ 260 #expr1 " = " #expr2, \ 261 "Expected %p, got %p", _val1, _val2); \ 262 return CMD_RET_FAILURE; \ 263 } \ 264 __ret; \ 265 }) 266 267 /* Assert that two addresses (converted from pointers) are equal */ 268 #define ut_asserteq_addr(expr1, expr2) ({ \ 269 ulong _val1 = map_to_sysmem(expr1); \ 270 ulong _val2 = map_to_sysmem(expr2); \ 271 int __ret = 0; \ 272 \ 273 if (_val1 != _val2) { \ 274 ut_failf(uts, __FILE__, __LINE__, __func__, \ 275 #expr1 " = " #expr2, \ 276 "Expected %lx, got %lx", _val1, _val2); \ 277 return CMD_RET_FAILURE; \ 278 } \ 279 __ret; \ 280 }) 281 282 /* Assert that a pointer is NULL */ 283 #define ut_assertnull(expr) ({ \ 284 const void *_val = (expr); \ 285 int __ret = 0; \ 286 \ 287 if (_val) { \ 288 ut_failf(uts, __FILE__, __LINE__, __func__, \ 289 #expr " != NULL", \ 290 "Expected NULL, got %p", _val); \ 291 return CMD_RET_FAILURE; \ 292 } \ 293 __ret; \ 294 }) 295 296 /* Assert that a pointer is not NULL */ 297 #define ut_assertnonnull(expr) ({ \ 298 const void *_val = (expr); \ 299 int __ret = 0; \ 300 \ 301 if (!_val) { \ 302 ut_failf(uts, __FILE__, __LINE__, __func__, \ 303 #expr " = NULL", \ 304 "Expected non-null, got NULL"); \ 305 return CMD_RET_FAILURE; \ 306 } \ 307 __ret; \ 308 }) 309 310 /* Assert that a pointer is not an error pointer */ 311 #define ut_assertok_ptr(expr) ({ \ 312 const void *_val = (expr); \ 313 int __ret = 0; \ 314 \ 315 if (IS_ERR(_val)) { \ 316 ut_failf(uts, __FILE__, __LINE__, __func__, \ 317 #expr " = NULL", \ 318 "Expected pointer, got error %ld", \ 319 PTR_ERR(_val)); \ 320 return CMD_RET_FAILURE; \ 321 } \ 322 __ret; \ 323 }) 324 325 /* Assert that an operation succeeds (returns 0) */ 326 #define ut_assertok(cond) ut_asserteq(0, cond) 327 328 /* Assert that the next console output line matches */ 329 #define ut_assert_nextline(fmt, args...) ({ \ 330 int __ret = 0; \ 331 \ 332 if (ut_check_console_line(uts, fmt, ##args)) { \ 333 ut_failf(uts, __FILE__, __LINE__, __func__, \ 334 "console", "\nExpected '%s',\n got '%s'", \ 335 uts->expect_str, uts->actual_str); \ 336 return CMD_RET_FAILURE; \ 337 } \ 338 __ret; \ 339 }) 340 341 /* Assert that the next console output line matches up to the length */ 342 #define ut_assert_nextlinen(fmt, args...) ({ \ 343 int __ret = 0; \ 344 \ 345 if (ut_check_console_linen(uts, fmt, ##args)) { \ 346 ut_failf(uts, __FILE__, __LINE__, __func__, \ 347 "console", "\nExpected '%s',\n got '%s'", \ 348 uts->expect_str, uts->actual_str); \ 349 return CMD_RET_FAILURE; \ 350 } \ 351 __ret; \ 352 }) 353 354 /* Assert that there is a 'next' console output line, and skip it */ 355 #define ut_assert_skipline() ({ \ 356 int __ret = 0; \ 357 \ 358 if (ut_check_skipline(uts)) { \ 359 ut_failf(uts, __FILE__, __LINE__, __func__, \ 360 "console", "\nExpected a line, got end"); \ 361 return CMD_RET_FAILURE; \ 362 } \ 363 __ret; \ 364 }) 365 366 /* Assert that a following console output line matches */ 367 #define ut_assert_skip_to_line(fmt, args...) ({ \ 368 int __ret = 0; \ 369 \ 370 if (ut_check_skip_to_line(uts, fmt, ##args)) { \ 371 ut_failf(uts, __FILE__, __LINE__, __func__, \ 372 "console", "\nExpected '%s',\n got to '%s'", \ 373 uts->expect_str, uts->actual_str); \ 374 return CMD_RET_FAILURE; \ 375 } \ 376 __ret; \ 377 }) 378 379 /* Assert that a following console output line matches */ 380 #define ut_assert_skip_to_linen(fmt, args...) ({ \ 381 int __ret = 0; \ 382 \ 383 if (ut_check_skip_to_linen(uts, fmt, ##args)) { \ 384 ut_failf(uts, __FILE__, __LINE__, __func__, \ 385 "console", "\nExpected '%s',\n got to '%s'", \ 386 uts->expect_str, uts->actual_str); \ 387 return CMD_RET_FAILURE; \ 388 } \ 389 __ret; \ 390 }) 391 392 /* Assert that there is no more console output */ 393 #define ut_assert_console_end() ({ \ 394 int __ret = 0; \ 395 \ 396 if (ut_check_console_end(uts)) { \ 397 ut_failf(uts, __FILE__, __LINE__, __func__, \ 398 "console", "Expected no more output, got '%s'",\ 399 uts->actual_str); \ 400 return CMD_RET_FAILURE; \ 401 } \ 402 __ret; \ 403 }) 404 405 /* Assert that the next lines are print_buffer() dump at an address */ 406 #define ut_assert_nextlines_are_dump(total_bytes) ({ \ 407 int __ret = 0; \ 408 \ 409 if (ut_check_console_dump(uts, total_bytes)) { \ 410 ut_failf(uts, __FILE__, __LINE__, __func__, \ 411 "console", \ 412 "Expected dump of length %x bytes, got '%s'", \ 413 total_bytes, uts->actual_str); \ 414 return CMD_RET_FAILURE; \ 415 } \ 416 __ret; \ 417 }) 418 419 /* Assert that the next console output line is empty */ 420 #define ut_assert_nextline_empty() \ 421 ut_assert_nextline("%s", "") 422 423 /** 424 * ut_check_free() - Return the number of bytes free in the malloc() pool 425 * 426 * Return: bytes free 427 */ 428 ulong ut_check_free(void); 429 430 /** 431 * ut_check_delta() - Return the number of bytes allocated/freed 432 * 433 * @last: Last value from ut_check_free 434 * Return: free memory delta from @last; positive means more memory has been 435 * allocated, negative means less has been allocated (i.e. some is freed) 436 */ 437 long ut_check_delta(ulong last); 438 439 /** 440 * ut_silence_console() - Silence the console if requested by the user 441 * 442 * This stops test output from appear on the console. It is the default on 443 * sandbox, unless the -v flag is given. For other boards, this does nothing. 444 * 445 * @uts: Test state (in case in future we want to keep state here) 446 */ 447 void ut_silence_console(struct unit_test_state *uts); 448 449 /** 450 * ut_unsilence_console() - Unsilence the console after a test 451 * 452 * This restarts console output again and turns off console recording. This 453 * happens on all boards, including sandbox. 454 */ 455 void ut_unsilence_console(struct unit_test_state *uts); 456 457 /** 458 * ut_set_skip_delays() - Sets whether delays should be skipped 459 * 460 * Normally functions like mdelay() cause U-Boot to wait for a while. This 461 * allows all such delays to be skipped on sandbox, to speed up tests 462 * 463 * @uts: Test state (in case in future we want to keep state here) 464 * @skip_delays: true to skip delays, false to process them normally 465 */ 466 void ut_set_skip_delays(struct unit_test_state *uts, bool skip_delays); 467 468 /** 469 * ut_state_get() - Get the active test state 470 * 471 * Return: the currently active test state, or NULL if none 472 */ 473 struct unit_test_state *ut_get_state(void); 474 475 /** 476 * ut_set_state() - Set the active test state 477 * 478 * @uts: Test state to use as currently active test state, or NULL if none 479 */ 480 void ut_set_state(struct unit_test_state *uts); 481 482 /** 483 * ut_init_state() - Set up a new test state 484 * 485 * This must be called before using the test state with ut_run_tests() 486 * 487 * @uts: Test state to init 488 */ 489 void ut_init_state(struct unit_test_state *uts); 490 491 /** 492 * ut_uninit_state() - Free memory used by test state 493 * 494 * This must be called before after the test state with ut_run_tests(). To later 495 * reuse the test state to run more tests, call test_state_init() first 496 * 497 * @uts: Test state to uninit 498 */ 499 void ut_uninit_state(struct unit_test_state *uts); 500 501 /** 502 * ut_run_tests() - Run a set of tests 503 * 504 * This runs the test, handling any preparation and clean-up needed. It prints 505 * the name of each test before running it. 506 * 507 * @uts: Unit-test state, which must be ready for use, i.e. ut_init_state() 508 * has been called. The caller is responsible for calling 509 * ut_uninit_state() after this function returns 510 * @category: Category of these tests. This is a string printed at the start to 511 * announce the the number of tests 512 * @prefix: String prefix for the tests. Any tests that have this prefix will be 513 * printed without the prefix, so that it is easier to see the unique part 514 * of the test name. If NULL, no prefix processing is done 515 * @tests: List of tests to run 516 * @count: Number of tests to run 517 * @select_name: Name of a single test to run (from the list provided). If NULL 518 * then all tests are run 519 * @runs_per_test: Number of times to run each test (typically 1) 520 * @force_run: Run tests that are marked as manual-only (UTF_MANUAL) 521 * @test_insert: String describing a test to run after n other tests run, in the 522 * format n:name where n is the number of tests to run before this one and 523 * name is the name of the test to run. This is used to find which test causes 524 * another test to fail. If the one test fails, testing stops immediately. 525 * Pass NULL to disable this 526 * Return: 0 if all tests passed, -1 if any failed 527 */ 528 int ut_run_list(struct unit_test_state *uts, const char *category, 529 const char *prefix, struct unit_test *tests, int count, 530 const char *select_name, int runs_per_test, bool force_run, 531 const char *test_insert); 532 533 /** 534 * ut_report() - Report stats on a test run 535 * 536 * @stats: Stats to show 537 * @run_count: Number of suites that were run 538 */ 539 void ut_report(struct ut_stats *stats, int run_count); 540 541 #endif 542