include/test/ut.h

   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_console_end() - Check there is no more console output
  87  *
  88  * After the function returns, uts->actual_str holds the actual string read
  89  * from the console
  90  *
  91  * @uts: Test state
  92  * @return 0 if OK (console has no output), other value on error
  93  */
  94 int ut_check_console_end(struct unit_test_state *uts);
  95
  96 /**
  97  * ut_check_console_dump() - Check that next lines have a print_buffer() dump
  98  *
  99  * This only supports a byte dump.
 100  *
 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
 103  *      error
 104  */
 105 int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
 106
 107 /* Assert that a condition is non-zero */
 108 #define ut_assert(cond)                                                 \
 109         if (!(cond)) {                                                  \
 110                 ut_fail(uts, __FILE__, __LINE__, __func__, #cond);      \
 111                 return CMD_RET_FAILURE;                                 \
 112         }
 113
 114 /* Assert that a condition is non-zero, with printf() string */
 115 #define ut_assertf(cond, fmt, args...)                                  \
 116         if (!(cond)) {                                                  \
 117                 ut_failf(uts, __FILE__, __LINE__, __func__, #cond,      \
 118                          fmt, ##args);                                  \
 119                 return CMD_RET_FAILURE;                                 \
 120         }
 121
 122 /* Assert that two int expressions are equal */
 123 #define ut_asserteq(expr1, expr2) {                                     \
 124         unsigned int _val1 = (expr1), _val2 = (expr2);                  \
 125                                                                         \
 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;                                 \
 132         }                                                               \
 133 }
 134
 135 /* Assert that two 64 int expressions are equal */
 136 #define ut_asserteq_64(expr1, expr2) {                                  \
 137         u64 _val1 = (expr1), _val2 = (expr2);                           \
 138                                                                         \
 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;                                 \
 148         }                                                               \
 149 }
 150
 151 /* Assert that two string expressions are equal */
 152 #define ut_asserteq_str(expr1, expr2) {                                 \
 153         const char *_val1 = (expr1), *_val2 = (expr2);                  \
 154                                                                         \
 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;                                 \
 160         }                                                               \
 161 }
 162
 163 /*
 164  * Assert that two string expressions are equal, up to length of the
 165  * first
 166  */
 167 #define ut_asserteq_strn(expr1, expr2) {                                \
 168         const char *_val1 = (expr1), *_val2 = (expr2);                  \
 169         int _len = strlen(_val1);                                       \
 170                                                                         \
 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;                                 \
 177         }                                                               \
 178 }
 179
 180 /*
 181  * Assert that two string expressions are equal, up to length of the
 182  * first
 183  */
 184 #define ut_asserteq_strn(expr1, expr2) {                                \
 185         const char *_val1 = (expr1), *_val2 = (expr2);                  \
 186         int _len = strlen(_val1);                                       \
 187                                                                         \
 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;                                 \
 194         }                                                               \
 195 }
 196
 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;                                         \
 201                                                                         \
 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\"",                 \
 210                          __buf1, __buf2);                               \
 211                 return CMD_RET_FAILURE;                                 \
 212         }                                                               \
 213 }
 214
 215 /* Assert that two pointers are equal */
 216 #define ut_asserteq_ptr(expr1, expr2) {                                 \
 217         const void *_val1 = (expr1), *_val2 = (expr2);                  \
 218                                                                         \
 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;                                 \
 224         }                                                               \
 225 }
 226
 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);                             \
 231                                                                         \
 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;                                 \
 237         }                                                               \
 238 }
 239
 240 /* Assert that a pointer is NULL */
 241 #define ut_assertnull(expr) {                                   \
 242         const void *_val = (expr);                                      \
 243                                                                         \
 244         if (_val) {                                             \
 245                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 246                          #expr " != NULL",                              \
 247                          "Expected NULL, got %p", _val);                \
 248                 return CMD_RET_FAILURE;                                 \
 249         }                                                               \
 250 }
 251
 252 /* Assert that a pointer is not NULL */
 253 #define ut_assertnonnull(expr) {                                        \
 254         const void *_val = (expr);                                      \
 255                                                                         \
 256         if (!_val) {                                            \
 257                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 258                          #expr " = NULL",                               \
 259                          "Expected non-null, got NULL");                \
 260                 return CMD_RET_FAILURE;                                 \
 261         }                                                               \
 262 }
 263
 264 /* Assert that a pointer is not an error pointer */
 265 #define ut_assertok_ptr(expr) {                                         \
 266         const void *_val = (expr);                                      \
 267                                                                         \
 268         if (IS_ERR(_val)) {                                             \
 269                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 270                          #expr " = NULL",                               \
 271                          "Expected pointer, got error %ld",             \
 272                          PTR_ERR(_val));                                \
 273                 return CMD_RET_FAILURE;                                 \
 274         }                                                               \
 275 }
 276
 277 /* Assert that an operation succeeds (returns 0) */
 278 #define ut_assertok(cond)       ut_asserteq(0, cond)
 279
 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;                                 \
 287         }                                                               \
 288
 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;                                 \
 296         }                                                               \
 297
 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;                                 \
 304         }                                                               \
 305
 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'",\
 311                          uts->actual_str);                              \
 312                 return CMD_RET_FAILURE;                                 \
 313         }                                                               \
 314
 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__,             \
 319                          "console",                                     \
 320                         "Expected dump of length %x bytes, got '%s'",   \
 321                          total_bytes, uts->actual_str);                 \
 322                 return CMD_RET_FAILURE;                                 \
 323         }                                                               \
 324
 325 /**
 326  * ut_check_free() - Return the number of bytes free in the malloc() pool
 327  *
 328  * @return bytes free
 329  */
 330 ulong ut_check_free(void);
 331
 332 /**
 333  * ut_check_delta() - Return the number of bytes allocated/freed
 334  *
 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)
 338  */
 339 long ut_check_delta(ulong last);
 340
 341 /**
 342  * ut_silence_console() - Silence the console if requested by the user
 343  *
 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.
 346  *
 347  * @uts: Test state (in case in future we want to keep state here)
 348  */
 349 void ut_silence_console(struct unit_test_state *uts);
 350
 351 /**
 352  * ut_unsilence_console() - Unsilence the console after a test
 353  *
 354  * This restarts console output again and turns off console recording. This
 355  * happens on all boards, including sandbox.
 356  */
 357 void ut_unsilence_console(struct unit_test_state *uts);
 358
 359 /**
 360  * ut_set_skip_delays() - Sets whether delays should be skipped
 361  *
 362  * Normally functions like mdelay() cause U-Boot to wait for a while. This
 363  * allows all such delays to be skipped on sandbox, to speed up tests
 364  *
 365  * @uts: Test state (in case in future we want to keep state here)
 366  * @skip_delays: true to skip delays, false to process them normally
 367  */
 368 void ut_set_skip_delays(struct unit_test_state *uts, bool skip_delays);
 369
 370 /**
 371  * test_pre_run() - Handle any preparation needed to run a test
 372  *
 373  * @uts: Test state
 374  * @test: Test to prepare for
 375  * @return 0 if OK, -EAGAIN to skip this test since some required feature is not
 376  *      available, other -ve on error (meaning that testing cannot likely
 377  *      continue)
 378  */
 379 int test_pre_run(struct unit_test_state *uts, struct unit_test *test);
 380
 381 /**
 382  * test_post_run() - Handle cleaning up after a test
 383  *
 384  * @uts: Test state
 385  * @test: Test to clean up after
 386  * @return 0 if OK, -ve on error (meaning that testing cannot likely continue)
 387  */
 388 int test_post_run(struct unit_test_state *uts, struct unit_test *test);
 389
 390 /**
 391  * ut_run_test() - Run a single test
 392  *
 393  * This runs the test, handling any preparation and clean-up needed. It prints
 394  * the name of each test before running it.
 395  *
 396  * @uts: Test state to update. The caller should ensure that this is zeroed for
 397  *      the first call to this function. On exit, @uts->fail_count is
 398  *      incremented by the number of failures (0, one hopes)
 399  * @test: Test to run
 400  * @name: Name of test, possibly skipping a prefix that should not be displayed
 401  * @return 0 if all tests passed, -EAGAIN if the test should be skipped, -1 if
 402  *      any failed
 403  */
 404 int ut_run_test(struct unit_test_state *uts, struct unit_test *test,
 405                 const char *name);
 406
 407 /**
 408  * ut_run_tests() - Run a set of tests
 409  *
 410  * This runs the tests, handling any preparation and clean-up needed. It prints
 411  * the name of each test before running it.
 412  *
 413  * @uts: Test state to update. The caller should ensure that this is zeroed for
 414  *      the first call to this function. On exit, @uts->fail_count is
 415  *      incremented by the number of failures (0, one hopes)
 416  * @prefix: String prefix for the tests. Any tests that have this prefix will be
 417  *      printed without the prefix, so that it is easier to see the unique part
 418  *      of the test name. If NULL, no prefix processing is done
 419  * @tests: List of tests to run
 420  * @count: Number of tests to run
 421  * @select_name: Name of a single test to run (from the list provided). If NULL
 422  *      then all tests are run
 423  * @return 0 if all tests passed, -ENOENT if test @select_name was not found,
 424  *      -EBADF if any failed
 425  */
 426 int ut_run_tests(struct unit_test_state *uts, const char *prefix,
 427                  struct unit_test *tests, int count, const char *select_name);
 428
 429 /**
 430  * ut_run_tests() - Run a set of tests
 431  *
 432  * This runs the test, handling any preparation and clean-up needed. It prints
 433  * the name of each test before running it.
 434  *
 435  * @category: Category of these tests. This is a string printed at the start to
 436  *      announce the the number of tests
 437  * @prefix: String prefix for the tests. Any tests that have this prefix will be
 438  *      printed without the prefix, so that it is easier to see the unique part
 439  *      of the test name. If NULL, no prefix processing is done
 440  * @tests: List of tests to run
 441  * @count: Number of tests to run
 442  * @select_name: Name of a single test to run (from the list provided). If NULL
 443  *      then all tests are run
 444  * @return 0 if all tests passed, -1 if any failed
 445  */
 446 int ut_run_list(const char *name, const char *prefix, struct unit_test *tests,
 447                 int count, const char *select_name);
 448
 449 #endif