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_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_console_end() - Check there is no more console output
 102  *
 103  * After the function returns, uts->actual_str holds the actual string read
 104  * from the console
 105  *
 106  * @uts: Test state
 107  * Return: 0 if OK (console has no output), other value on error
 108  */
 109 int ut_check_console_end(struct unit_test_state *uts);
 110
 111 /**
 112  * ut_check_console_dump() - Check that next lines have a print_buffer() dump
 113  *
 114  * This only supports a byte dump.
 115  *
 116  * @total_bytes: Size of the expected dump in bytes`
 117  * Return: 0 if OK (looks like a dump and the length matches), other value on
 118  *      error
 119  */
 120 int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
 121
 122 /* Report a failure, with printf() string */
 123 #define ut_reportf(fmt, args...)                                        \
 124         ut_failf(uts, __FILE__, __LINE__, __func__, "report",           \
 125                  fmt, ##args)
 126
 127 /* Assert that a condition is non-zero */
 128 #define ut_assert(cond) ({                                              \
 129         int __ret = 0;                                                  \
 130                                                                         \
 131         if (!(cond)) {                                                  \
 132                 ut_fail(uts, __FILE__, __LINE__, __func__, #cond);      \
 133                 __ret = CMD_RET_FAILURE;                                \
 134         }                                                               \
 135         __ret;                                                          \
 136 })
 137
 138 /* Assert that a condition is non-zero, with printf() string */
 139 #define ut_assertf(cond, fmt, args...) ({                               \
 140         int __ret = 0;                                                  \
 141                                                                         \
 142         if (!(cond)) {                                                  \
 143                 ut_failf(uts, __FILE__, __LINE__, __func__, #cond,      \
 144                          fmt, ##args);                                  \
 145                 __ret = CMD_RET_FAILURE;                                \
 146         }                                                               \
 147         __ret;                                                          \
 148 })
 149
 150 /* Assert that two int expressions are equal */
 151 #define ut_asserteq(expr1, expr2) ({                                    \
 152         unsigned int _val1 = (expr1), _val2 = (expr2);                  \
 153         int __ret = 0;                                                  \
 154                                                                         \
 155         if (_val1 != _val2) {                                           \
 156                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 157                          #expr1 " == " #expr2,                          \
 158                          "Expected %#x (%d), got %#x (%d)",             \
 159                          _val1, _val1, _val2, _val2);                   \
 160                 __ret = CMD_RET_FAILURE;                                \
 161         }                                                               \
 162         __ret;                                                          \
 163 })
 164
 165 /* Assert that two 64 int expressions are equal */
 166 #define ut_asserteq_64(expr1, expr2) ({                                 \
 167         u64 _val1 = (expr1), _val2 = (expr2);                           \
 168         int __ret = 0;                                                  \
 169                                                                         \
 170         if (_val1 != _val2) {                                           \
 171                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 172                          #expr1 " == " #expr2,                          \
 173                          "Expected %#llx (%lld), got %#llx (%lld)",     \
 174                          (unsigned long long)_val1,                     \
 175                          (unsigned long long)_val1,                     \
 176                          (unsigned long long)_val2,                     \
 177                          (unsigned long long)_val2);                    \
 178                 __ret = CMD_RET_FAILURE;                                \
 179         }                                                               \
 180         __ret;                                                          \
 181 })
 182
 183 /* Assert that two string expressions are equal */
 184 #define ut_asserteq_str(expr1, expr2) ({                                \
 185         const char *_val1 = (expr1), *_val2 = (expr2);                  \
 186         int __ret = 0;                                                  \
 187                                                                         \
 188         if (strcmp(_val1, _val2)) {                                     \
 189                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 190                          #expr1 " = " #expr2,                           \
 191                          "Expected \"%s\", got \"%s\"", _val1, _val2);  \
 192                 __ret = CMD_RET_FAILURE;                                \
 193         }                                                               \
 194         __ret;                                                          \
 195 })
 196
 197 /*
 198  * Assert that two string expressions are equal, up to length of the
 199  * first
 200  */
 201 #define ut_asserteq_strn(expr1, expr2) ({                               \
 202         const char *_val1 = (expr1), *_val2 = (expr2);                  \
 203         int _len = strlen(_val1);                                       \
 204         int __ret = 0;                                                  \
 205                                                                         \
 206         if (memcmp(_val1, _val2, _len)) {                               \
 207                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 208                          #expr1 " = " #expr2,                           \
 209                          "Expected \"%.*s\", got \"%.*s\"",             \
 210                          _len, _val1, _len, _val2);                     \
 211                 __ret = CMD_RET_FAILURE;                                \
 212         }                                                               \
 213         __ret;                                                          \
 214 })
 215
 216 /* Assert that two memory areas are equal */
 217 #define ut_asserteq_mem(expr1, expr2, len) ({                           \
 218         const u8 *_val1 = (u8 *)(expr1), *_val2 = (u8 *)(expr2);        \
 219         const uint __len = len;                                         \
 220         int __ret = 0;                                                  \
 221                                                                         \
 222         if (memcmp(_val1, _val2, __len)) {                              \
 223                 char __buf1[64 + 1] = "\0";                             \
 224                 char __buf2[64 + 1] = "\0";                             \
 225                 bin2hex(__buf1, _val1, min(__len, (uint)32));           \
 226                 bin2hex(__buf2, _val2, min(__len, (uint)32));           \
 227                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 228                          #expr1 " = " #expr2,                           \
 229                          "Expected \"%s\", got \"%s\"",                 \
 230                          __buf1, __buf2);                               \
 231                 __ret = CMD_RET_FAILURE;                                \
 232         }                                                               \
 233         __ret;                                                          \
 234 })
 235
 236 /* Assert that two pointers are equal */
 237 #define ut_asserteq_ptr(expr1, expr2) ({                                \
 238         const void *_val1 = (expr1), *_val2 = (expr2);                  \
 239         int __ret = 0;                                                  \
 240                                                                         \
 241         if (_val1 != _val2) {                                           \
 242                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 243                          #expr1 " = " #expr2,                           \
 244                          "Expected %p, got %p", _val1, _val2);          \
 245                 __ret = CMD_RET_FAILURE;                                \
 246         }                                                               \
 247         __ret;                                                          \
 248 })
 249
 250 /* Assert that two addresses (converted from pointers) are equal */
 251 #define ut_asserteq_addr(expr1, expr2) ({                               \
 252         ulong _val1 = map_to_sysmem(expr1);                             \
 253         ulong _val2 = map_to_sysmem(expr2);                             \
 254         int __ret = 0;                                                  \
 255                                                                         \
 256         if (_val1 != _val2) {                                           \
 257                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 258                          #expr1 " = " #expr2,                           \
 259                          "Expected %lx, got %lx", _val1, _val2);        \
 260                 __ret = CMD_RET_FAILURE;                                \
 261         }                                                               \
 262         __ret;                                                          \
 263 })
 264
 265 /* Assert that a pointer is NULL */
 266 #define ut_assertnull(expr) ({                                          \
 267         const void *_val = (expr);                                      \
 268         int __ret = 0;                                                  \
 269                                                                         \
 270         if (_val) {                                                     \
 271                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 272                          #expr " != NULL",                              \
 273                          "Expected NULL, got %p", _val);                \
 274                 __ret = CMD_RET_FAILURE;                                \
 275         }                                                               \
 276         __ret;                                                          \
 277 })
 278
 279 /* Assert that a pointer is not NULL */
 280 #define ut_assertnonnull(expr) ({                                       \
 281         const void *_val = (expr);                                      \
 282         int __ret = 0;                                                  \
 283                                                                         \
 284         if (!_val) {                                                    \
 285                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 286                          #expr " = NULL",                               \
 287                          "Expected non-null, got NULL");                \
 288                 __ret = CMD_RET_FAILURE;                                \
 289         }                                                               \
 290         __ret;                                                          \
 291 })
 292
 293 /* Assert that a pointer is not an error pointer */
 294 #define ut_assertok_ptr(expr) ({                                        \
 295         const void *_val = (expr);                                      \
 296         int __ret = 0;                                                  \
 297                                                                         \
 298         if (IS_ERR(_val)) {                                             \
 299                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 300                          #expr " = NULL",                               \
 301                          "Expected pointer, got error %ld",             \
 302                          PTR_ERR(_val));                                \
 303                 __ret = CMD_RET_FAILURE;                                \
 304         }                                                               \
 305         __ret;                                                          \
 306 })
 307
 308 /* Assert that an operation succeeds (returns 0) */
 309 #define ut_assertok(cond)       ut_asserteq(0, cond)
 310
 311 /* Assert that the next console output line matches */
 312 #define ut_assert_nextline(fmt, args...) ({                             \
 313         int __ret = 0;                                                  \
 314                                                                         \
 315         if (ut_check_console_line(uts, fmt, ##args)) {                  \
 316                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 317                          "console", "\nExpected '%s',\n     got '%s'",  \
 318                          uts->expect_str, uts->actual_str);             \
 319                 __ret = CMD_RET_FAILURE;                                \
 320         }                                                               \
 321         __ret;                                                          \
 322 })
 323
 324 /* Assert that the next console output line matches up to the length */
 325 #define ut_assert_nextlinen(fmt, args...) ({                            \
 326         int __ret = 0;                                                  \
 327                                                                         \
 328         if (ut_check_console_linen(uts, fmt, ##args)) {                 \
 329                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 330                          "console", "\nExpected '%s',\n     got '%s'",  \
 331                          uts->expect_str, uts->actual_str);             \
 332                 __ret = CMD_RET_FAILURE;                                \
 333         }                                                               \
 334         __ret;                                                          \
 335 })
 336
 337 /* Assert that there is a 'next' console output line, and skip it */
 338 #define ut_assert_skipline() ({                                         \
 339         int __ret = 0;                                                  \
 340                                                                         \
 341         if (ut_check_skipline(uts)) {                                   \
 342                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 343                          "console", "\nExpected a line, got end");      \
 344                 __ret = CMD_RET_FAILURE;                                \
 345         }                                                               \
 346         __ret;                                                          \
 347 })
 348
 349 /* Assert that a following console output line matches */
 350 #define ut_assert_skip_to_line(fmt, args...) ({                         \
 351         int __ret = 0;                                                  \
 352                                                                         \
 353         if (ut_check_skip_to_line(uts, fmt, ##args)) {                  \
 354                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 355                          "console", "\nExpected '%s',\n     got to '%s'", \
 356                          uts->expect_str, uts->actual_str);             \
 357                 __ret = CMD_RET_FAILURE;                                \
 358         }                                                               \
 359         __ret;                                                          \
 360 })
 361
 362 /* Assert that there is no more console output */
 363 #define ut_assert_console_end() ({                                      \
 364         int __ret = 0;                                                  \
 365                                                                         \
 366         if (ut_check_console_end(uts)) {                                \
 367                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 368                          "console", "Expected no more output, got '%s'",\
 369                          uts->actual_str);                              \
 370                 __ret = CMD_RET_FAILURE;                                \
 371         }                                                               \
 372         __ret;                                                          \
 373 })
 374
 375 /* Assert that the next lines are print_buffer() dump at an address */
 376 #define ut_assert_nextlines_are_dump(total_bytes) ({                    \
 377         int __ret = 0;                                                  \
 378                                                                         \
 379         if (ut_check_console_dump(uts, total_bytes)) {                  \
 380                 ut_failf(uts, __FILE__, __LINE__, __func__,             \
 381                          "console",                                     \
 382                         "Expected dump of length %x bytes, got '%s'",   \
 383                          total_bytes, uts->actual_str);                 \
 384                 __ret = CMD_RET_FAILURE;                                \
 385         }                                                               \
 386         __ret;                                                          \
 387 })
 388
 389 /* Assert that the next console output line is empty */
 390 #define ut_assert_nextline_empty()                                      \
 391         ut_assert_nextline("%s", "")
 392
 393 /**
 394  * ut_check_free() - Return the number of bytes free in the malloc() pool
 395  *
 396  * Return: bytes free
 397  */
 398 ulong ut_check_free(void);
 399
 400 /**
 401  * ut_check_delta() - Return the number of bytes allocated/freed
 402  *
 403  * @last: Last value from ut_check_free
 404  * Return: free memory delta from @last; positive means more memory has been
 405  *      allocated, negative means less has been allocated (i.e. some is freed)
 406  */
 407 long ut_check_delta(ulong last);
 408
 409 /**
 410  * ut_silence_console() - Silence the console if requested by the user
 411  *
 412  * This stops test output from appear on the console. It is the default on
 413  * sandbox, unless the -v flag is given. For other boards, this does nothing.
 414  *
 415  * @uts: Test state (in case in future we want to keep state here)
 416  */
 417 void ut_silence_console(struct unit_test_state *uts);
 418
 419 /**
 420  * ut_unsilence_console() - Unsilence the console after a test
 421  *
 422  * This restarts console output again and turns off console recording. This
 423  * happens on all boards, including sandbox.
 424  */
 425 void ut_unsilence_console(struct unit_test_state *uts);
 426
 427 /**
 428  * ut_set_skip_delays() - Sets whether delays should be skipped
 429  *
 430  * Normally functions like mdelay() cause U-Boot to wait for a while. This
 431  * allows all such delays to be skipped on sandbox, to speed up tests
 432  *
 433  * @uts: Test state (in case in future we want to keep state here)
 434  * @skip_delays: true to skip delays, false to process them normally
 435  */
 436 void ut_set_skip_delays(struct unit_test_state *uts, bool skip_delays);
 437
 438 /**
 439  * test_get_state() - Get the active test state
 440  *
 441  * Return: the currently active test state, or NULL if none
 442  */
 443 struct unit_test_state *test_get_state(void);
 444
 445 /**
 446  * test_set_state() - Set the active test state
 447  *
 448  * @uts: Test state to use as currently active test state, or NULL if none
 449  */
 450 void test_set_state(struct unit_test_state *uts);
 451
 452 /**
 453  * ut_run_tests() - Run a set of tests
 454  *
 455  * This runs the test, handling any preparation and clean-up needed. It prints
 456  * the name of each test before running it.
 457  *
 458  * @category: Category of these tests. This is a string printed at the start to
 459  *      announce the the number of tests
 460  * @prefix: String prefix for the tests. Any tests that have this prefix will be
 461  *      printed without the prefix, so that it is easier to see the unique part
 462  *      of the test name. If NULL, no prefix processing is done
 463  * @tests: List of tests to run
 464  * @count: Number of tests to run
 465  * @select_name: Name of a single test to run (from the list provided). If NULL
 466  *      then all tests are run
 467  * @runs_per_test: Number of times to run each test (typically 1)
 468  * @force_run: Run tests that are marked as manual-only (UT_TESTF_MANUAL)
 469  * @test_insert: String describing a test to run after n other tests run, in the
 470  * format n:name where n is the number of tests to run before this one and
 471  * name is the name of the test to run. This is used to find which test causes
 472  * another test to fail. If the one test fails, testing stops immediately.
 473  * Pass NULL to disable this
 474  * Return: 0 if all tests passed, -1 if any failed
 475  */
 476 int ut_run_list(const char *name, const char *prefix, struct unit_test *tests,
 477                 int count, const char *select_name, int runs_per_test,
 478                 bool force_run, const char *test_insert);
 479
 480 #endif