kselftest_harness.h

   1/* SPDX-License-Identifier: GPL-2.0-only */
   2/*
   3 * Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
   4 *
   5 * kselftest_harness.h: simple C unit test helper.
   6 *
   7 * See documentation in Documentation/dev-tools/kselftest.rst
   8 *
   9 * API inspired by code.google.com/p/googletest
  10 */
  11
  12/**
  13 * DOC: example
  14 *
  15 * .. code-block:: c
  16 *
  17 *    #include "kselftest_harness.h"
  18 *
  19 *    TEST(standalone_test) {
  20 *      do_some_stuff;
  21 *      EXPECT_GT(10, stuff) {
  22 *         stuff_state_t state;
  23 *         enumerate_stuff_state(&state);
  24 *         TH_LOG("expectation failed with state: %s", state.msg);
  25 *      }
  26 *      more_stuff;
  27 *      ASSERT_NE(some_stuff, NULL) TH_LOG("how did it happen?!");
  28 *      last_stuff;
  29 *      EXPECT_EQ(0, last_stuff);
  30 *    }
  31 *
  32 *    FIXTURE(my_fixture) {
  33 *      mytype_t *data;
  34 *      int awesomeness_level;
  35 *    };
  36 *    FIXTURE_SETUP(my_fixture) {
  37 *      self->data = mytype_new();
  38 *      ASSERT_NE(NULL, self->data);
  39 *    }
  40 *    FIXTURE_TEARDOWN(my_fixture) {
  41 *      mytype_free(self->data);
  42 *    }
  43 *    TEST_F(my_fixture, data_is_good) {
  44 *      EXPECT_EQ(1, is_my_data_good(self->data));
  45 *    }
  46 *
  47 *    TEST_HARNESS_MAIN
  48 */
  49
  50#ifndef __KSELFTEST_HARNESS_H
  51#define __KSELFTEST_HARNESS_H
  52
  53#ifndef _GNU_SOURCE
  54#define _GNU_SOURCE
  55#endif
  56#include <asm/types.h>
  57#include <ctype.h>
  58#include <errno.h>
  59#include <linux/unistd.h>
  60#include <poll.h>
  61#include <stdbool.h>
  62#include <stdint.h>
  63#include <stdio.h>
  64#include <stdlib.h>
  65#include <string.h>
  66#include <sys/mman.h>
  67#include <sys/types.h>
  68#include <sys/wait.h>
  69#include <unistd.h>
  70
  71#include "kselftest.h"
  72
  73static inline void __kselftest_memset_safe(void *s, int c, size_t n)
  74{
  75	if (n > 0)
  76		memset(s, c, n);
  77}
  78
  79#define KSELFTEST_PRIO_TEST_F  20000
  80#define KSELFTEST_PRIO_XFAIL   20001
  81
  82#define TEST_TIMEOUT_DEFAULT 30
  83
  84/* Utilities exposed to the test definitions */
  85#ifndef TH_LOG_STREAM
  86#  define TH_LOG_STREAM stderr
  87#endif
  88
  89#ifndef TH_LOG_ENABLED
  90#  define TH_LOG_ENABLED 1
  91#endif
  92
  93/**
  94 * TH_LOG()
  95 *
  96 * @fmt: format string
  97 * @...: optional arguments
  98 *
  99 * .. code-block:: c
 100 *
 101 *     TH_LOG(format, ...)
 102 *
 103 * Optional debug logging function available for use in tests.
 104 * Logging may be enabled or disabled by defining TH_LOG_ENABLED.
 105 * E.g., #define TH_LOG_ENABLED 1
 106 *
 107 * If no definition is provided, logging is enabled by default.
 108 */
 109#define TH_LOG(fmt, ...) do { \
 110	if (TH_LOG_ENABLED) \
 111		__TH_LOG(fmt, ##__VA_ARGS__); \
 112} while (0)
 113
 114/* Unconditional logger for internal use. */
 115#define __TH_LOG(fmt, ...) \
 116		fprintf(TH_LOG_STREAM, "# %s:%d:%s:" fmt "\n", \
 117			__FILE__, __LINE__, _metadata->name, ##__VA_ARGS__)
 118
 119/**
 120 * SKIP()
 121 *
 122 * @statement: statement to run after reporting SKIP
 123 * @fmt: format string
 124 * @...: optional arguments
 125 *
 126 * .. code-block:: c
 127 *
 128 *     SKIP(statement, fmt, ...);
 129 *
 130 * This forces a "pass" after reporting why something is being skipped
 131 * and runs "statement", which is usually "return" or "goto skip".
 132 */
 133#define SKIP(statement, fmt, ...) do { \
 134	snprintf(_metadata->results->reason, \
 135		 sizeof(_metadata->results->reason), fmt, ##__VA_ARGS__); \
 136	if (TH_LOG_ENABLED) { \
 137		fprintf(TH_LOG_STREAM, "#      SKIP      %s\n", \
 138			_metadata->results->reason); \
 139	} \
 140	_metadata->exit_code = KSFT_SKIP; \
 141	_metadata->trigger = 0; \
 142	statement; \
 143} while (0)
 144
 145/**
 146 * TEST() - Defines the test function and creates the registration
 147 * stub
 148 *
 149 * @test_name: test name
 150 *
 151 * .. code-block:: c
 152 *
 153 *     TEST(name) { implementation }
 154 *
 155 * Defines a test by name.
 156 * Names must be unique and tests must not be run in parallel.  The
 157 * implementation containing block is a function and scoping should be treated
 158 * as such.  Returning early may be performed with a bare "return;" statement.
 159 *
 160 * EXPECT_* and ASSERT_* are valid in a TEST() { } context.
 161 */
 162#define TEST(test_name) __TEST_IMPL(test_name, -1)
 163
 164/**
 165 * TEST_SIGNAL()
 166 *
 167 * @test_name: test name
 168 * @signal: signal number
 169 *
 170 * .. code-block:: c
 171 *
 172 *     TEST_SIGNAL(name, signal) { implementation }
 173 *
 174 * Defines a test by name and the expected term signal.
 175 * Names must be unique and tests must not be run in parallel.  The
 176 * implementation containing block is a function and scoping should be treated
 177 * as such.  Returning early may be performed with a bare "return;" statement.
 178 *
 179 * EXPECT_* and ASSERT_* are valid in a TEST() { } context.
 180 */
 181#define TEST_SIGNAL(test_name, signal) __TEST_IMPL(test_name, signal)
 182
 183#define __TEST_IMPL(test_name, _signal) \
 184	static void test_name(struct __test_metadata *_metadata); \
 185	static void wrapper_##test_name( \
 186		struct __test_metadata *_metadata, \
 187		struct __fixture_variant_metadata __attribute__((unused)) *variant) \
 188	{ \
 189		test_name(_metadata); \
 190	} \
 191	static struct __test_metadata _##test_name##_object = \
 192		{ .name = #test_name, \
 193		  .fn = &wrapper_##test_name, \
 194		  .fixture = &_fixture_global, \
 195		  .termsig = _signal, \
 196		  .timeout = TEST_TIMEOUT_DEFAULT, }; \
 197	static void __attribute__((constructor)) _register_##test_name(void) \
 198	{ \
 199		__register_test(&_##test_name##_object); \
 200	} \
 201	static void test_name( \
 202		struct __test_metadata __attribute__((unused)) *_metadata)
 203
 204/**
 205 * FIXTURE_DATA() - Wraps the struct name so we have one less
 206 * argument to pass around
 207 *
 208 * @datatype_name: datatype name
 209 *
 210 * .. code-block:: c
 211 *
 212 *     FIXTURE_DATA(datatype_name)
 213 *
 214 * Almost always, you want just FIXTURE() instead (see below).
 215 * This call may be used when the type of the fixture data
 216 * is needed.  In general, this should not be needed unless
 217 * the *self* is being passed to a helper directly.
 218 */
 219#define FIXTURE_DATA(datatype_name) struct _test_data_##datatype_name
 220
 221/**
 222 * FIXTURE() - Called once per fixture to setup the data and
 223 * register
 224 *
 225 * @fixture_name: fixture name
 226 *
 227 * .. code-block:: c
 228 *
 229 *     FIXTURE(fixture_name) {
 230 *       type property1;
 231 *       ...
 232 *     };
 233 *
 234 * Defines the data provided to TEST_F()-defined tests as *self*.  It should be
 235 * populated and cleaned up using FIXTURE_SETUP() and FIXTURE_TEARDOWN().
 236 */
 237#define FIXTURE(fixture_name) \
 238	FIXTURE_VARIANT(fixture_name); \
 239	static struct __fixture_metadata _##fixture_name##_fixture_object = \
 240		{ .name =  #fixture_name, }; \
 241	static void __attribute__((constructor)) \
 242	_register_##fixture_name##_data(void) \
 243	{ \
 244		__register_fixture(&_##fixture_name##_fixture_object); \
 245	} \
 246	FIXTURE_DATA(fixture_name)
 247
 248/**
 249 * FIXTURE_SETUP() - Prepares the setup function for the fixture.
 250 * *_metadata* is included so that EXPECT_*, ASSERT_* etc. work correctly.
 251 *
 252 * @fixture_name: fixture name
 253 *
 254 * .. code-block:: c
 255 *
 256 *     FIXTURE_SETUP(fixture_name) { implementation }
 257 *
 258 * Populates the required "setup" function for a fixture.  An instance of the
 259 * datatype defined with FIXTURE_DATA() will be exposed as *self* for the
 260 * implementation.
 261 *
 262 * ASSERT_* are valid for use in this context and will prempt the execution
 263 * of any dependent fixture tests.
 264 *
 265 * A bare "return;" statement may be used to return early.
 266 */
 267#define FIXTURE_SETUP(fixture_name) \
 268	static void fixture_name##_setup( \
 269		struct __test_metadata __attribute__((unused)) *_metadata, \
 270		FIXTURE_DATA(fixture_name) __attribute__((unused)) *self, \
 271		const FIXTURE_VARIANT(fixture_name) \
 272			__attribute__((unused)) *variant)
 273
 274/**
 275 * FIXTURE_TEARDOWN()
 276 * *_metadata* is included so that EXPECT_*, ASSERT_* etc. work correctly.
 277 *
 278 * @fixture_name: fixture name
 279 *
 280 * .. code-block:: c
 281 *
 282 *     FIXTURE_TEARDOWN(fixture_name) { implementation }
 283 *
 284 * Populates the required "teardown" function for a fixture.  An instance of the
 285 * datatype defined with FIXTURE_DATA() will be exposed as *self* for the
 286 * implementation to clean up.
 287 *
 288 * A bare "return;" statement may be used to return early.
 289 */
 290#define FIXTURE_TEARDOWN(fixture_name) \
 291	static const bool fixture_name##_teardown_parent; \
 292	__FIXTURE_TEARDOWN(fixture_name)
 293
 294/**
 295 * FIXTURE_TEARDOWN_PARENT()
 296 * *_metadata* is included so that EXPECT_*, ASSERT_* etc. work correctly.
 297 *
 298 * @fixture_name: fixture name
 299 *
 300 * .. code-block:: c
 301 *
 302 *     FIXTURE_TEARDOWN_PARENT(fixture_name) { implementation }
 303 *
 304 * Same as FIXTURE_TEARDOWN() but run this code in a parent process.  This
 305 * enables the test process to drop its privileges without impacting the
 306 * related FIXTURE_TEARDOWN_PARENT() (e.g. to remove files from a directory
 307 * where write access was dropped).
 308 *
 309 * To make it possible for the parent process to use *self*, share (MAP_SHARED)
 310 * the fixture data between all forked processes.
 311 */
 312#define FIXTURE_TEARDOWN_PARENT(fixture_name) \
 313	static const bool fixture_name##_teardown_parent = true; \
 314	__FIXTURE_TEARDOWN(fixture_name)
 315
 316#define __FIXTURE_TEARDOWN(fixture_name) \
 317	static void fixture_name##_teardown( \
 318		struct __test_metadata __attribute__((unused)) *_metadata, \
 319		FIXTURE_DATA(fixture_name) __attribute__((unused)) *self, \
 320		const FIXTURE_VARIANT(fixture_name) \
 321			__attribute__((unused)) *variant)
 322
 323/**
 324 * FIXTURE_VARIANT() - Optionally called once per fixture
 325 * to declare fixture variant
 326 *
 327 * @fixture_name: fixture name
 328 *
 329 * .. code-block:: c
 330 *
 331 *     FIXTURE_VARIANT(fixture_name) {
 332 *       type property1;
 333 *       ...
 334 *     };
 335 *
 336 * Defines type of constant parameters provided to FIXTURE_SETUP(), TEST_F() and
 337 * FIXTURE_TEARDOWN as *variant*. Variants allow the same tests to be run with
 338 * different arguments.
 339 */
 340#define FIXTURE_VARIANT(fixture_name) struct _fixture_variant_##fixture_name
 341
 342/**
 343 * FIXTURE_VARIANT_ADD() - Called once per fixture
 344 * variant to setup and register the data
 345 *
 346 * @fixture_name: fixture name
 347 * @variant_name: name of the parameter set
 348 *
 349 * .. code-block:: c
 350 *
 351 *     FIXTURE_VARIANT_ADD(fixture_name, variant_name) {
 352 *       .property1 = val1,
 353 *       ...
 354 *     };
 355 *
 356 * Defines a variant of the test fixture, provided to FIXTURE_SETUP() and
 357 * TEST_F() as *variant*. Tests of each fixture will be run once for each
 358 * variant.
 359 */
 360#define FIXTURE_VARIANT_ADD(fixture_name, variant_name) \
 361	extern const FIXTURE_VARIANT(fixture_name) \
 362		_##fixture_name##_##variant_name##_variant; \
 363	static struct __fixture_variant_metadata \
 364		_##fixture_name##_##variant_name##_object = \
 365		{ .name = #variant_name, \
 366		  .data = &_##fixture_name##_##variant_name##_variant}; \
 367	static void __attribute__((constructor)) \
 368		_register_##fixture_name##_##variant_name(void) \
 369	{ \
 370		__register_fixture_variant(&_##fixture_name##_fixture_object, \
 371			&_##fixture_name##_##variant_name##_object);	\
 372	} \
 373	const FIXTURE_VARIANT(fixture_name) \
 374		_##fixture_name##_##variant_name##_variant =
 375
 376/**
 377 * TEST_F() - Emits test registration and helpers for
 378 * fixture-based test cases
 379 *
 380 * @fixture_name: fixture name
 381 * @test_name: test name
 382 *
 383 * .. code-block:: c
 384 *
 385 *     TEST_F(fixture, name) { implementation }
 386 *
 387 * Defines a test that depends on a fixture (e.g., is part of a test case).
 388 * Very similar to TEST() except that *self* is the setup instance of fixture's
 389 * datatype exposed for use by the implementation.
 390 *
 391 * The _metadata object is shared (MAP_SHARED) with all the potential forked
 392 * processes, which enables them to use EXCEPT_*() and ASSERT_*().
 393 *
 394 * The *self* object is only shared with the potential forked processes if
 395 * FIXTURE_TEARDOWN_PARENT() is used instead of FIXTURE_TEARDOWN().
 396 */
 397#define TEST_F(fixture_name, test_name) \
 398	__TEST_F_IMPL(fixture_name, test_name, -1, TEST_TIMEOUT_DEFAULT)
 399
 400#define TEST_F_SIGNAL(fixture_name, test_name, signal) \
 401	__TEST_F_IMPL(fixture_name, test_name, signal, TEST_TIMEOUT_DEFAULT)
 402
 403#define TEST_F_TIMEOUT(fixture_name, test_name, timeout) \
 404	__TEST_F_IMPL(fixture_name, test_name, -1, timeout)
 405
 406#define __TEST_F_IMPL(fixture_name, test_name, signal, tmout) \
 407	static void fixture_name##_##test_name( \
 408		struct __test_metadata *_metadata, \
 409		FIXTURE_DATA(fixture_name) *self, \
 410		const FIXTURE_VARIANT(fixture_name) *variant); \
 411	static void wrapper_##fixture_name##_##test_name( \
 412		struct __test_metadata *_metadata, \
 413		struct __fixture_variant_metadata *variant) \
 414	{ \
 415		/* fixture data is alloced, setup, and torn down per call. */ \
 416		FIXTURE_DATA(fixture_name) self_private, *self = NULL; \
 417		pid_t child = 1; \
 418		int status = 0; \
 419		/* Makes sure there is only one teardown, even when child forks again. */ \
 420		_metadata->no_teardown = mmap(NULL, sizeof(*_metadata->no_teardown), \
 421			PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANONYMOUS, -1, 0); \
 422		*_metadata->no_teardown = true; \
 423		if (sizeof(*self) > 0) { \
 424			if (fixture_name##_teardown_parent) { \
 425				self = mmap(NULL, sizeof(*self), PROT_READ | PROT_WRITE, \
 426					MAP_SHARED | MAP_ANONYMOUS, -1, 0); \
 427			} else { \
 428				__kselftest_memset_safe(&self_private, 0, sizeof(self_private)); \
 429				self = &self_private; \
 430			} \
 431		} \
 432		_metadata->variant = variant->data; \
 433		_metadata->self = self; \
 434		/* _metadata and potentially self are shared with all forks. */ \
 435		child = fork(); \
 436		if (child == 0) { \
 437			fixture_name##_setup(_metadata, self, variant->data); \
 438			/* Let setup failure terminate early. */ \
 439			if (_metadata->exit_code) \
 440				_exit(0); \
 441			*_metadata->no_teardown = false; \
 442			fixture_name##_##test_name(_metadata, self, variant->data); \
 443			_metadata->teardown_fn(false, _metadata, self, variant->data); \
 444			_exit(0); \
 445		} else if (child < 0 || child != waitpid(child, &status, 0)) { \
 446			ksft_print_msg("ERROR SPAWNING TEST GRANDCHILD\n"); \
 447			_metadata->exit_code = KSFT_FAIL; \
 448		} \
 449		_metadata->teardown_fn(true, _metadata, self, variant->data); \
 450		munmap(_metadata->no_teardown, sizeof(*_metadata->no_teardown)); \
 451		_metadata->no_teardown = NULL; \
 452		if (self && fixture_name##_teardown_parent) \
 453			munmap(self, sizeof(*self)); \
 454		if (WIFEXITED(status)) { \
 455			if (WEXITSTATUS(status)) \
 456				_metadata->exit_code = WEXITSTATUS(status); \
 457		} else if (WIFSIGNALED(status)) { \
 458			/* Forward signal to __wait_for_test(). */ \
 459			kill(getpid(), WTERMSIG(status)); \
 460		} \
 461	} \
 462	static void wrapper_##fixture_name##_##test_name##_teardown( \
 463		bool in_parent, struct __test_metadata *_metadata, \
 464		void *self, const void *variant) \
 465	{ \
 466		if (fixture_name##_teardown_parent == in_parent && \
 467				!__atomic_test_and_set(_metadata->no_teardown, __ATOMIC_RELAXED)) \
 468			fixture_name##_teardown(_metadata, self, variant); \
 469	} \
 470	static struct __test_metadata *_##fixture_name##_##test_name##_object; \
 471	static void __attribute__((constructor(KSELFTEST_PRIO_TEST_F))) \
 472			_register_##fixture_name##_##test_name(void) \
 473	{ \
 474		struct __test_metadata *object = mmap(NULL, sizeof(*object), \
 475			PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANONYMOUS, -1, 0); \
 476		object->name = #test_name; \
 477		object->fn = &wrapper_##fixture_name##_##test_name; \
 478		object->fixture = &_##fixture_name##_fixture_object; \
 479		object->teardown_fn = &wrapper_##fixture_name##_##test_name##_teardown; \
 480		object->termsig = signal; \
 481		object->timeout = tmout; \
 482		_##fixture_name##_##test_name##_object = object; \
 483		__register_test(object); \
 484	} \
 485	static void fixture_name##_##test_name( \
 486		struct __test_metadata __attribute__((unused)) *_metadata, \
 487		FIXTURE_DATA(fixture_name) __attribute__((unused)) *self, \
 488		const FIXTURE_VARIANT(fixture_name) \
 489			__attribute__((unused)) *variant)
 490
 491/**
 492 * TEST_HARNESS_MAIN - Simple wrapper to run the test harness
 493 *
 494 * .. code-block:: c
 495 *
 496 *     TEST_HARNESS_MAIN
 497 *
 498 * Use once to append a main() to the test file.
 499 */
 500#define TEST_HARNESS_MAIN \
 501	int main(int argc, char **argv) { \
 502		return test_harness_run(argc, argv); \
 503	}
 504
 505/**
 506 * DOC: operators
 507 *
 508 * Operators for use in TEST() and TEST_F().
 509 * ASSERT_* calls will stop test execution immediately.
 510 * EXPECT_* calls will emit a failure warning, note it, and continue.
 511 */
 512
 513/**
 514 * ASSERT_EQ()
 515 *
 516 * @expected: expected value
 517 * @seen: measured value
 518 *
 519 * ASSERT_EQ(expected, measured): expected == measured
 520 */
 521#define ASSERT_EQ(expected, seen) \
 522	__EXPECT(expected, #expected, seen, #seen, ==, 1)
 523
 524/**
 525 * ASSERT_NE()
 526 *
 527 * @expected: expected value
 528 * @seen: measured value
 529 *
 530 * ASSERT_NE(expected, measured): expected != measured
 531 */
 532#define ASSERT_NE(expected, seen) \
 533	__EXPECT(expected, #expected, seen, #seen, !=, 1)
 534
 535/**
 536 * ASSERT_LT()
 537 *
 538 * @expected: expected value
 539 * @seen: measured value
 540 *
 541 * ASSERT_LT(expected, measured): expected < measured
 542 */
 543#define ASSERT_LT(expected, seen) \
 544	__EXPECT(expected, #expected, seen, #seen, <, 1)
 545
 546/**
 547 * ASSERT_LE()
 548 *
 549 * @expected: expected value
 550 * @seen: measured value
 551 *
 552 * ASSERT_LE(expected, measured): expected <= measured
 553 */
 554#define ASSERT_LE(expected, seen) \
 555	__EXPECT(expected, #expected, seen, #seen, <=, 1)
 556
 557/**
 558 * ASSERT_GT()
 559 *
 560 * @expected: expected value
 561 * @seen: measured value
 562 *
 563 * ASSERT_GT(expected, measured): expected > measured
 564 */
 565#define ASSERT_GT(expected, seen) \
 566	__EXPECT(expected, #expected, seen, #seen, >, 1)
 567
 568/**
 569 * ASSERT_GE()
 570 *
 571 * @expected: expected value
 572 * @seen: measured value
 573 *
 574 * ASSERT_GE(expected, measured): expected >= measured
 575 */
 576#define ASSERT_GE(expected, seen) \
 577	__EXPECT(expected, #expected, seen, #seen, >=, 1)
 578
 579/**
 580 * ASSERT_NULL()
 581 *
 582 * @seen: measured value
 583 *
 584 * ASSERT_NULL(measured): NULL == measured
 585 */
 586#define ASSERT_NULL(seen) \
 587	__EXPECT(NULL, "NULL", seen, #seen, ==, 1)
 588
 589/**
 590 * ASSERT_TRUE()
 591 *
 592 * @seen: measured value
 593 *
 594 * ASSERT_TRUE(measured): measured != 0
 595 */
 596#define ASSERT_TRUE(seen) \
 597	__EXPECT(0, "0", seen, #seen, !=, 1)
 598
 599/**
 600 * ASSERT_FALSE()
 601 *
 602 * @seen: measured value
 603 *
 604 * ASSERT_FALSE(measured): measured == 0
 605 */
 606#define ASSERT_FALSE(seen) \
 607	__EXPECT(0, "0", seen, #seen, ==, 1)
 608
 609/**
 610 * ASSERT_STREQ()
 611 *
 612 * @expected: expected value
 613 * @seen: measured value
 614 *
 615 * ASSERT_STREQ(expected, measured): !strcmp(expected, measured)
 616 */
 617#define ASSERT_STREQ(expected, seen) \
 618	__EXPECT_STR(expected, seen, ==, 1)
 619
 620/**
 621 * ASSERT_STRNE()
 622 *
 623 * @expected: expected value
 624 * @seen: measured value
 625 *
 626 * ASSERT_STRNE(expected, measured): strcmp(expected, measured)
 627 */
 628#define ASSERT_STRNE(expected, seen) \
 629	__EXPECT_STR(expected, seen, !=, 1)
 630
 631/**
 632 * EXPECT_EQ()
 633 *
 634 * @expected: expected value
 635 * @seen: measured value
 636 *
 637 * EXPECT_EQ(expected, measured): expected == measured
 638 */
 639#define EXPECT_EQ(expected, seen) \
 640	__EXPECT(expected, #expected, seen, #seen, ==, 0)
 641
 642/**
 643 * EXPECT_NE()
 644 *
 645 * @expected: expected value
 646 * @seen: measured value
 647 *
 648 * EXPECT_NE(expected, measured): expected != measured
 649 */
 650#define EXPECT_NE(expected, seen) \
 651	__EXPECT(expected, #expected, seen, #seen, !=, 0)
 652
 653/**
 654 * EXPECT_LT()
 655 *
 656 * @expected: expected value
 657 * @seen: measured value
 658 *
 659 * EXPECT_LT(expected, measured): expected < measured
 660 */
 661#define EXPECT_LT(expected, seen) \
 662	__EXPECT(expected, #expected, seen, #seen, <, 0)
 663
 664/**
 665 * EXPECT_LE()
 666 *
 667 * @expected: expected value
 668 * @seen: measured value
 669 *
 670 * EXPECT_LE(expected, measured): expected <= measured
 671 */
 672#define EXPECT_LE(expected, seen) \
 673	__EXPECT(expected, #expected, seen, #seen, <=, 0)
 674
 675/**
 676 * EXPECT_GT()
 677 *
 678 * @expected: expected value
 679 * @seen: measured value
 680 *
 681 * EXPECT_GT(expected, measured): expected > measured
 682 */
 683#define EXPECT_GT(expected, seen) \
 684	__EXPECT(expected, #expected, seen, #seen, >, 0)
 685
 686/**
 687 * EXPECT_GE()
 688 *
 689 * @expected: expected value
 690 * @seen: measured value
 691 *
 692 * EXPECT_GE(expected, measured): expected >= measured
 693 */
 694#define EXPECT_GE(expected, seen) \
 695	__EXPECT(expected, #expected, seen, #seen, >=, 0)
 696
 697/**
 698 * EXPECT_NULL()
 699 *
 700 * @seen: measured value
 701 *
 702 * EXPECT_NULL(measured): NULL == measured
 703 */
 704#define EXPECT_NULL(seen) \
 705	__EXPECT(NULL, "NULL", seen, #seen, ==, 0)
 706
 707/**
 708 * EXPECT_TRUE()
 709 *
 710 * @seen: measured value
 711 *
 712 * EXPECT_TRUE(measured): 0 != measured
 713 */
 714#define EXPECT_TRUE(seen) \
 715	__EXPECT(0, "0", seen, #seen, !=, 0)
 716
 717/**
 718 * EXPECT_FALSE()
 719 *
 720 * @seen: measured value
 721 *
 722 * EXPECT_FALSE(measured): 0 == measured
 723 */
 724#define EXPECT_FALSE(seen) \
 725	__EXPECT(0, "0", seen, #seen, ==, 0)
 726
 727/**
 728 * EXPECT_STREQ()
 729 *
 730 * @expected: expected value
 731 * @seen: measured value
 732 *
 733 * EXPECT_STREQ(expected, measured): !strcmp(expected, measured)
 734 */
 735#define EXPECT_STREQ(expected, seen) \
 736	__EXPECT_STR(expected, seen, ==, 0)
 737
 738/**
 739 * EXPECT_STRNE()
 740 *
 741 * @expected: expected value
 742 * @seen: measured value
 743 *
 744 * EXPECT_STRNE(expected, measured): strcmp(expected, measured)
 745 */
 746#define EXPECT_STRNE(expected, seen) \
 747	__EXPECT_STR(expected, seen, !=, 0)
 748
 749#ifndef ARRAY_SIZE
 750#define ARRAY_SIZE(a)	(sizeof(a) / sizeof(a[0]))
 751#endif
 752
 753/* Support an optional handler after and ASSERT_* or EXPECT_*.  The approach is
 754 * not thread-safe, but it should be fine in most sane test scenarios.
 755 *
 756 * Using __bail(), which optionally abort()s, is the easiest way to early
 757 * return while still providing an optional block to the API consumer.
 758 */
 759#define OPTIONAL_HANDLER(_assert) \
 760	for (; _metadata->trigger; _metadata->trigger = \
 761			__bail(_assert, _metadata))
 762
 763#define is_signed_var(var)	(!!(((__typeof__(var))(-1)) < (__typeof__(var))1))
 764
 765#define __EXPECT(_expected, _expected_str, _seen, _seen_str, _t, _assert) do { \
 766	/* Avoid multiple evaluation of the cases */ \
 767	__typeof__(_expected) __exp = (_expected); \
 768	__typeof__(_seen) __seen = (_seen); \
 769	if (!(__exp _t __seen)) { \
 770		/* Report with actual signedness to avoid weird output. */ \
 771		switch (is_signed_var(__exp) * 2 + is_signed_var(__seen)) { \
 772		case 0: { \
 773			uintmax_t __exp_print = (uintmax_t)__exp; \
 774			uintmax_t __seen_print = (uintmax_t)__seen; \
 775			__TH_LOG("Expected %s (%ju) %s %s (%ju)", \
 776				 _expected_str, __exp_print, #_t, \
 777				 _seen_str, __seen_print); \
 778			break; \
 779			} \
 780		case 1: { \
 781			uintmax_t __exp_print = (uintmax_t)__exp; \
 782			intmax_t  __seen_print = (intmax_t)__seen; \
 783			__TH_LOG("Expected %s (%ju) %s %s (%jd)", \
 784				 _expected_str, __exp_print, #_t, \
 785				 _seen_str, __seen_print); \
 786			break; \
 787			} \
 788		case 2: { \
 789			intmax_t  __exp_print = (intmax_t)__exp; \
 790			uintmax_t __seen_print = (uintmax_t)__seen; \
 791			__TH_LOG("Expected %s (%jd) %s %s (%ju)", \
 792				 _expected_str, __exp_print, #_t, \
 793				 _seen_str, __seen_print); \
 794			break; \
 795			} \
 796		case 3: { \
 797			intmax_t  __exp_print = (intmax_t)__exp; \
 798			intmax_t  __seen_print = (intmax_t)__seen; \
 799			__TH_LOG("Expected %s (%jd) %s %s (%jd)", \
 800				 _expected_str, __exp_print, #_t, \
 801				 _seen_str, __seen_print); \
 802			break; \
 803			} \
 804		} \
 805		_metadata->exit_code = KSFT_FAIL; \
 806		/* Ensure the optional handler is triggered */ \
 807		_metadata->trigger = 1; \
 808	} \
 809} while (0); OPTIONAL_HANDLER(_assert)
 810
 811#define __EXPECT_STR(_expected, _seen, _t, _assert) do { \
 812	const char *__exp = (_expected); \
 813	const char *__seen = (_seen); \
 814	if (!(strcmp(__exp, __seen) _t 0))  { \
 815		__TH_LOG("Expected '%s' %s '%s'.", __exp, #_t, __seen); \
 816		_metadata->exit_code = KSFT_FAIL; \
 817		_metadata->trigger = 1; \
 818	} \
 819} while (0); OPTIONAL_HANDLER(_assert)
 820
 821/* List helpers */
 822#define __LIST_APPEND(head, item) \
 823{ \
 824	/* Circular linked list where only prev is circular. */ \
 825	if (head == NULL) { \
 826		head = item; \
 827		item->next = NULL; \
 828		item->prev = item; \
 829		return;	\
 830	} \
 831	if (__constructor_order_forward) { \
 832		item->next = NULL; \
 833		item->prev = head->prev; \
 834		item->prev->next = item; \
 835		head->prev = item; \
 836	} else { \
 837		item->next = head; \
 838		item->next->prev = item; \
 839		item->prev = item; \
 840		head = item; \
 841	} \
 842}
 843
 844struct __test_results {
 845	char reason[1024];	/* Reason for test result */
 846};
 847
 848struct __test_metadata;
 849struct __fixture_variant_metadata;
 850
 851/* Contains all the information about a fixture. */
 852struct __fixture_metadata {
 853	const char *name;
 854	struct __test_metadata *tests;
 855	struct __fixture_variant_metadata *variant;
 856	struct __fixture_metadata *prev, *next;
 857} _fixture_global __attribute__((unused)) = {
 858	.name = "global",
 859	.prev = &_fixture_global,
 860};
 861
 862struct __test_xfail {
 863	struct __fixture_metadata *fixture;
 864	struct __fixture_variant_metadata *variant;
 865	struct __test_metadata *test;
 866	struct __test_xfail *prev, *next;
 867};
 868
 869/**
 870 * XFAIL_ADD() - mark variant + test case combination as expected to fail
 871 * @fixture_name: name of the fixture
 872 * @variant_name: name of the variant
 873 * @test_name: name of the test case
 874 *
 875 * Mark a combination of variant + test case for a given fixture as expected
 876 * to fail. Tests marked this way will report XPASS / XFAIL return codes,
 877 * instead of PASS / FAIL,and use respective counters.
 878 */
 879#define XFAIL_ADD(fixture_name, variant_name, test_name) \
 880	static struct __test_xfail \
 881		_##fixture_name##_##variant_name##_##test_name##_xfail = \
 882	{ \
 883		.fixture = &_##fixture_name##_fixture_object, \
 884		.variant = &_##fixture_name##_##variant_name##_object, \
 885	}; \
 886	static void __attribute__((constructor(KSELFTEST_PRIO_XFAIL))) \
 887		_register_##fixture_name##_##variant_name##_##test_name##_xfail(void) \
 888	{ \
 889		_##fixture_name##_##variant_name##_##test_name##_xfail.test = \
 890			_##fixture_name##_##test_name##_object; \
 891		__register_xfail(&_##fixture_name##_##variant_name##_##test_name##_xfail); \
 892	}
 893
 894static struct __fixture_metadata *__fixture_list = &_fixture_global;
 895static bool __constructor_order_forward;
 896
 897static inline void __register_fixture(struct __fixture_metadata *f)
 898{
 899	__LIST_APPEND(__fixture_list, f);
 900}
 901
 902struct __fixture_variant_metadata {
 903	const char *name;
 904	const void *data;
 905	struct __test_xfail *xfails;
 906	struct __fixture_variant_metadata *prev, *next;
 907};
 908
 909static inline void
 910__register_fixture_variant(struct __fixture_metadata *f,
 911			   struct __fixture_variant_metadata *variant)
 912{
 913	__LIST_APPEND(f->variant, variant);
 914}
 915
 916/* Contains all the information for test execution and status checking. */
 917struct __test_metadata {
 918	const char *name;
 919	void (*fn)(struct __test_metadata *,
 920		   struct __fixture_variant_metadata *);
 921	pid_t pid;	/* pid of test when being run */
 922	struct __fixture_metadata *fixture;
 923	void (*teardown_fn)(bool in_parent, struct __test_metadata *_metadata,
 924			    void *self, const void *variant);
 925	int termsig;
 926	int exit_code;
 927	int trigger; /* extra handler after the evaluation */
 928	int timeout;	/* seconds to wait for test timeout */
 929	bool aborted;	/* stopped test due to failed ASSERT */
 930	bool *no_teardown; /* fixture needs teardown */
 931	void *self;
 932	const void *variant;
 933	struct __test_results *results;
 934	struct __test_metadata *prev, *next;
 935};
 936
 937static inline bool __test_passed(struct __test_metadata *metadata)
 938{
 939	return metadata->exit_code != KSFT_FAIL &&
 940	       metadata->exit_code <= KSFT_SKIP;
 941}
 942
 943/*
 944 * Since constructors are called in reverse order, reverse the test
 945 * list so tests are run in source declaration order.
 946 * https://gcc.gnu.org/onlinedocs/gccint/Initialization.html
 947 * However, it seems not all toolchains do this correctly, so use
 948 * __constructor_order_foward to detect which direction is called first
 949 * and adjust list building logic to get things running in the right
 950 * direction.
 951 */
 952static inline void __register_test(struct __test_metadata *t)
 953{
 954	__LIST_APPEND(t->fixture->tests, t);
 955}
 956
 957static inline void __register_xfail(struct __test_xfail *xf)
 958{
 959	__LIST_APPEND(xf->variant->xfails, xf);
 960}
 961
 962static inline int __bail(int for_realz, struct __test_metadata *t)
 963{
 964	/* if this is ASSERT, return immediately. */
 965	if (for_realz) {
 966		if (t->teardown_fn)
 967			t->teardown_fn(false, t, t->self, t->variant);
 968		abort();
 969	}
 970	/* otherwise, end the for loop and continue. */
 971	return 0;
 972}
 973
 974static void __wait_for_test(struct __test_metadata *t)
 975{
 976	/*
 977	 * Sets status so that WIFEXITED(status) returns true and
 978	 * WEXITSTATUS(status) returns KSFT_FAIL.  This safe default value
 979	 * should never be evaluated because of the waitpid(2) check and
 980	 * timeout handling.
 981	 */
 982	int status = KSFT_FAIL << 8;
 983	struct pollfd poll_child;
 984	int ret, child, childfd;
 985	bool timed_out = false;
 986
 987	childfd = syscall(__NR_pidfd_open, t->pid, 0);
 988	if (childfd == -1) {
 989		t->exit_code = KSFT_FAIL;
 990		fprintf(TH_LOG_STREAM,
 991			"# %s: unable to open pidfd\n",
 992			t->name);
 993		return;
 994	}
 995
 996	poll_child.fd = childfd;
 997	poll_child.events = POLLIN;
 998	ret = poll(&poll_child, 1, t->timeout * 1000);
 999	if (ret == -1) {
1000		t->exit_code = KSFT_FAIL;
1001		fprintf(TH_LOG_STREAM,
1002			"# %s: unable to wait on child pidfd\n",
1003			t->name);
1004		return;
1005	} else if (ret == 0) {
1006		timed_out = true;
1007		/* signal process group */
1008		kill(-(t->pid), SIGKILL);
1009	}
1010	child = waitpid(t->pid, &status, WNOHANG);
1011	if (child == -1 && errno != EINTR) {
1012		t->exit_code = KSFT_FAIL;
1013		fprintf(TH_LOG_STREAM,
1014			"# %s: Failed to wait for PID %d (errno: %d)\n",
1015			t->name, t->pid, errno);
1016		return;
1017	}
1018
1019	if (timed_out) {
1020		t->exit_code = KSFT_FAIL;
1021		fprintf(TH_LOG_STREAM,
1022			"# %s: Test terminated by timeout\n", t->name);
1023	} else if (WIFEXITED(status)) {
1024		if (WEXITSTATUS(status) == KSFT_SKIP ||
1025		    WEXITSTATUS(status) == KSFT_XPASS ||
1026		    WEXITSTATUS(status) == KSFT_XFAIL) {
1027			t->exit_code = WEXITSTATUS(status);
1028		} else if (t->termsig != -1) {
1029			t->exit_code = KSFT_FAIL;
1030			fprintf(TH_LOG_STREAM,
1031				"# %s: Test exited normally instead of by signal (code: %d)\n",
1032				t->name,
1033				WEXITSTATUS(status));
1034		} else {
1035			switch (WEXITSTATUS(status)) {
1036			/* Success */
1037			case KSFT_PASS:
1038				t->exit_code = KSFT_PASS;
1039				break;
1040			/* Failure */
1041			default:
1042				t->exit_code = KSFT_FAIL;
1043				fprintf(TH_LOG_STREAM,
1044					"# %s: Test failed\n",
1045					t->name);
1046			}
1047		}
1048	} else if (WIFSIGNALED(status)) {
1049		t->exit_code = KSFT_FAIL;
1050		if (WTERMSIG(status) == SIGABRT) {
1051			fprintf(TH_LOG_STREAM,
1052				"# %s: Test terminated by assertion\n",
1053				t->name);
1054		} else if (WTERMSIG(status) == t->termsig) {
1055			t->exit_code = KSFT_PASS;
1056		} else {
1057			fprintf(TH_LOG_STREAM,
1058				"# %s: Test terminated unexpectedly by signal %d\n",
1059				t->name,
1060				WTERMSIG(status));
1061		}
1062	} else {
1063		t->exit_code = KSFT_FAIL;
1064		fprintf(TH_LOG_STREAM,
1065			"# %s: Test ended in some other way [%u]\n",
1066			t->name,
1067			status);
1068	}
1069}
1070
1071static void test_harness_list_tests(void)
1072{
1073	struct __fixture_variant_metadata *v;
1074	struct __fixture_metadata *f;
1075	struct __test_metadata *t;
1076
1077	for (f = __fixture_list; f; f = f->next) {
1078		v = f->variant;
1079		t = f->tests;
1080
1081		if (f == __fixture_list)
1082			fprintf(stderr, "%-20s %-25s %s\n",
1083				"# FIXTURE", "VARIANT", "TEST");
1084		else
1085			fprintf(stderr, "--------------------------------------------------------------------------------\n");
1086
1087		do {
1088			fprintf(stderr, "%-20s %-25s %s\n",
1089				t == f->tests ? f->name : "",
1090				v ? v->name : "",
1091				t ? t->name : "");
1092
1093			v = v ? v->next : NULL;
1094			t = t ? t->next : NULL;
1095		} while (v || t);
1096	}
1097}
1098
1099static int test_harness_argv_check(int argc, char **argv)
1100{
1101	int opt;
1102
1103	while ((opt = getopt(argc, argv, "dhlF:f:V:v:t:T:r:")) != -1) {
1104		switch (opt) {
1105		case 'f':
1106		case 'F':
1107		case 'v':
1108		case 'V':
1109		case 't':
1110		case 'T':
1111		case 'r':
1112			break;
1113		case 'l':
1114			test_harness_list_tests();
1115			return KSFT_SKIP;
1116		case 'd':
1117			ksft_debug_enabled = true;
1118			break;
1119		case 'h':
1120		default:
1121			fprintf(stderr,
1122				"Usage: %s [-h|-l|-d] [-t|-T|-v|-V|-f|-F|-r name]\n"
1123				"\t-h       print help\n"
1124				"\t-l       list all tests\n"
1125				"\t-d       enable debug prints\n"
1126				"\n"
1127				"\t-t name  include test\n"
1128				"\t-T name  exclude test\n"
1129				"\t-v name  include variant\n"
1130				"\t-V name  exclude variant\n"
1131				"\t-f name  include fixture\n"
1132				"\t-F name  exclude fixture\n"
1133				"\t-r name  run specified test\n"
1134				"\n"
1135				"Test filter options can be specified "
1136				"multiple times. The filtering stops\n"
1137				"at the first match. For example to "
1138				"include all tests from variant 'bla'\n"
1139				"but not test 'foo' specify '-T foo -v bla'.\n"
1140				"", argv[0]);
1141			return opt == 'h' ? KSFT_SKIP : KSFT_FAIL;
1142		}
1143	}
1144
1145	return KSFT_PASS;
1146}
1147
1148static bool test_enabled(int argc, char **argv,
1149			 struct __fixture_metadata *f,
1150			 struct __fixture_variant_metadata *v,
1151			 struct __test_metadata *t)
1152{
1153	unsigned int flen = 0, vlen = 0, tlen = 0;
1154	bool has_positive = false;
1155	int opt;
1156
1157	optind = 1;
1158	while ((opt = getopt(argc, argv, "dF:f:V:v:t:T:r:")) != -1) {
1159		if (opt != 'd')
1160			has_positive |= islower(opt);
1161
1162		switch (tolower(opt)) {
1163		case 't':
1164			if (!strcmp(t->name, optarg))
1165				return islower(opt);
1166			break;
1167		case 'f':
1168			if (!strcmp(f->name, optarg))
1169				return islower(opt);
1170			break;
1171		case 'v':
1172			if (!strcmp(v->name, optarg))
1173				return islower(opt);
1174			break;
1175		case 'r':
1176			if (!tlen) {
1177				flen = strlen(f->name);
1178				vlen = strlen(v->name);
1179				tlen = strlen(t->name);
1180			}
1181			if (strlen(optarg) == flen + 1 + vlen + !!vlen + tlen &&
1182			    !strncmp(f->name, &optarg[0], flen) &&
1183			    !strncmp(v->name, &optarg[flen + 1], vlen) &&
1184			    !strncmp(t->name, &optarg[flen + 1 + vlen + !!vlen], tlen))
1185				return true;
1186			break;
1187		}
1188	}
1189
1190	/*
1191	 * If there are no positive tests then we assume user just wants
1192	 * exclusions and everything else is a pass.
1193	 */
1194	return !has_positive;
1195}
1196
1197static void __run_test(struct __fixture_metadata *f,
1198		       struct __fixture_variant_metadata *variant,
1199		       struct __test_metadata *t)
1200{
1201	struct __test_xfail *xfail;
1202	char test_name[1024];
1203	const char *diagnostic;
1204	int child;
1205
1206	/* reset test struct */
1207	t->exit_code = KSFT_PASS;
1208	t->trigger = 0;
1209	t->aborted = false;
1210	t->no_teardown = NULL;
1211	memset(t->results->reason, 0, sizeof(t->results->reason));
1212
1213	snprintf(test_name, sizeof(test_name), "%s%s%s.%s",
1214		 f->name, variant->name[0] ? "." : "", variant->name, t->name);
1215
1216	ksft_print_msg(" RUN           %s ...\n", test_name);
1217
1218	/* Make sure output buffers are flushed before fork */
1219	fflush(stdout);
1220	fflush(stderr);
1221
1222	child = fork();
1223	if (child < 0) {
1224		ksft_print_msg("ERROR SPAWNING TEST CHILD\n");
1225		t->exit_code = KSFT_FAIL;
1226	} else if (child == 0) {
1227		setpgrp();
1228		t->fn(t, variant);
1229		_exit(t->exit_code);
1230	} else {
1231		t->pid = child;
1232		__wait_for_test(t);
1233	}
1234	ksft_print_msg("         %4s  %s\n",
1235		       __test_passed(t) ? "OK" : "FAIL", test_name);
1236
1237	/* Check if we're expecting this test to fail */
1238	for (xfail = variant->xfails; xfail; xfail = xfail->next)
1239		if (xfail->test == t)
1240			break;
1241	if (xfail)
1242		t->exit_code = __test_passed(t) ? KSFT_XPASS : KSFT_XFAIL;
1243
1244	if (t->results->reason[0])
1245		diagnostic = t->results->reason;
1246	else if (t->exit_code == KSFT_PASS || t->exit_code == KSFT_FAIL)
1247		diagnostic = NULL;
1248	else
1249		diagnostic = "unknown";
1250
1251	ksft_test_result_code(t->exit_code, test_name,
1252			      diagnostic ? "%s" : NULL, diagnostic);
1253}
1254
1255static int test_harness_run(int argc, char **argv)
1256{
1257	struct __fixture_variant_metadata no_variant = { .name = "", };
1258	struct __fixture_variant_metadata *v;
1259	struct __fixture_metadata *f;
1260	struct __test_results *results;
1261	struct __test_metadata *t;
1262	int ret;
1263	unsigned int case_count = 0, test_count = 0;
1264	unsigned int count = 0;
1265	unsigned int pass_count = 0;
1266
1267	ret = test_harness_argv_check(argc, argv);
1268	if (ret != KSFT_PASS)
1269		return ret;
1270
1271	for (f = __fixture_list; f; f = f->next) {
1272		for (v = f->variant ?: &no_variant; v; v = v->next) {
1273			unsigned int old_tests = test_count;
1274
1275			for (t = f->tests; t; t = t->next)
1276				if (test_enabled(argc, argv, f, v, t))
1277					test_count++;
1278
1279			if (old_tests != test_count)
1280				case_count++;
1281		}
1282	}
1283
1284	results = mmap(NULL, sizeof(*results), PROT_READ | PROT_WRITE,
1285		       MAP_SHARED | MAP_ANONYMOUS, -1, 0);
1286
1287	ksft_print_header();
1288	ksft_set_plan(test_count);
1289	ksft_print_msg("Starting %u tests from %u test cases.\n",
1290	       test_count, case_count);
1291	for (f = __fixture_list; f; f = f->next) {
1292		for (v = f->variant ?: &no_variant; v; v = v->next) {
1293			for (t = f->tests; t; t = t->next) {
1294				if (!test_enabled(argc, argv, f, v, t))
1295					continue;
1296				count++;
1297				t->results = results;
1298				__run_test(f, v, t);
1299				t->results = NULL;
1300				if (__test_passed(t))
1301					pass_count++;
1302				else
1303					ret = 1;
1304			}
1305		}
1306	}
1307	munmap(results, sizeof(*results));
1308
1309	ksft_print_msg("%s: %u / %u tests passed.\n", ret ? "FAILED" : "PASSED",
1310			pass_count, count);
1311	ksft_exit(ret == 0);
1312
1313	/* unreachable */
1314	return KSFT_FAIL;
1315}
1316
1317static void __attribute__((constructor)) __constructor_order_first(void)
1318{
1319	__constructor_order_forward = true;
1320}
1321
1322#endif  /* __KSELFTEST_HARNESS_H */