selftests: Add futex functional tests

SUBDIRS := functional

.PHONY: all clean

all:

	for DIR in $(SUBDIRS); do $(MAKE) -C $$DIR $@ ; done

run_tests: all

	./run.sh

clean:

	for DIR in $(SUBDIRS); do $(MAKE) -C $$DIR $@ ; done

Futex Test

==========

Futex Test is intended to thoroughly test the Linux kernel futex system call

API.

Functional tests shall test the documented behavior of the futex operation

code under test. This includes checking for proper behavior under normal use,

odd corner cases, regression tests, and abject abuse and misuse.

Futextest will also provide example implementation of mutual exclusion

primitives. These can be used as is in user applications or can serve as

examples for system libraries. These will likely be added to either a new lib/

directory or purely as header files under include/, I'm leaning toward the

latter.

Quick Start

-----------

# make

# ./run.sh

Design and Implementation Goals

-------------------------------

o Tests should be as self contained as is practical so as to facilitate sharing

  the individual tests on mailing list discussions and bug reports.

o The build system shall remain as simple as possible, avoiding any archive or

  shared object building and linking.

o Where possible, any helper functions or other package-wide code shall be

  implemented in header files, avoiding the need to compile intermediate object

  files.

o External dependendencies shall remain as minimal as possible. Currently gcc

  and glibc are the only dependencies.

o Tests return 0 for success and < 0 for failure.

Output Formatting

-----------------

Test output shall be easily parsable by both human and machine. Title and

results are printed to stdout, while intermediate ERROR or FAIL messages are

sent to stderr. Tests shall support the -c option to print PASS, FAIL, and

ERROR strings in color for easy visual parsing. Output shall conform to the

following format:

test_name: Description of the test

	Arguments: arg1=val1 #units specified for clarity where appropriate

	ERROR: Description of unexpected error

	 FAIL: Reason for test failure

	# FIXME: Perhaps an " INFO: informational message" option would be

	#        useful here. Using -v to toggle it them on and off, as with -c.

	# there may be multiple ERROR or FAIL messages

Result: (PASS|FAIL|ERROR)

Naming

------

o FIXME: decide on a sane test naming scheme.  Currently the tests are named

  based on the primary futex operation they test. Eventually this will become a

  problem as we intend to write multiple tests which collide in this namespace.

  Perhaps something like "wait-wake-1" "wait-wake-2" is adequate, leaving the

  detailed description in the test source and the output.

Coding Style

------------

o The Futex Test project adheres to the coding standards set forth by Linux

  kernel as defined in the Linux source Documentation/CodingStyle.

INCLUDES := -I../include

CFLAGS := $(CFLAGS) -g -O2 -Wall -D_GNU_SOURCE -pthread $(INCLUDES)

LDFLAGS := $(LDFLAGS) -pthread -lrt

HEADERS := ../include/futextest.h

TARGETS := \

	futex_wait_timeout \

	futex_wait_wouldblock \

	futex_requeue_pi \

	futex_requeue_pi_signal_restart \

	futex_requeue_pi_mismatched_ops \

	futex_wait_uninitialized_heap \

	futex_wait_private_mapped_file

.PHONY: all clean

all: $(TARGETS)

$(TARGETS): $(HEADERS)

run_tests: all

	./run.sh

clean:

	rm -f $(TARGETS)

/******************************************************************************

 *

 *   Copyright © International Business Machines  Corp., 2006-2008

 *

 *   This program is free software;  you can redistribute it and/or modify

 *   it under the terms of the GNU General Public License as published by

 *   the Free Software Foundation; either version 2 of the License, or

 *   (at your option) any later version.

 *

 * DESCRIPTION

 *      This test excercises the futex syscall op codes needed for requeuing

 *      priority inheritance aware POSIX condition variables and mutexes.

 *

 * AUTHORS

 *      Sripathi Kodi <sripathik@in.ibm.com>

 *      Darren Hart <dvhart@linux.intel.com>

 *

 * HISTORY

 *      2008-Jan-13: Initial version by Sripathi Kodi <sripathik@in.ibm.com>

 *      2009-Nov-6: futex test adaptation by Darren Hart <dvhart@linux.intel.com>

 *

 *****************************************************************************/

#include <errno.h>

#include <limits.h>

#include <pthread.h>

#include <stdio.h>

#include <stdlib.h>

#include <signal.h>

#include <string.h>

#include "atomic.h"

#include "futextest.h"

#include "logging.h"

#define MAX_WAKE_ITERS 1000

#define THREAD_MAX 10

#define SIGNAL_PERIOD_US 100

atomic_t waiters_blocked = ATOMIC_INITIALIZER;

atomic_t waiters_woken = ATOMIC_INITIALIZER;

futex_t f1 = FUTEX_INITIALIZER;

futex_t f2 = FUTEX_INITIALIZER;

futex_t wake_complete = FUTEX_INITIALIZER;

/* Test option defaults */

static long timeout_ns;

static int broadcast;

static int owner;

static int locked;

struct thread_arg {

	long id;

	struct timespec *timeout;

	int lock;

	int ret;

};

#define THREAD_ARG_INITIALIZER { 0, NULL, 0, 0 }

void usage(char *prog)

{

	printf("Usage: %s\n", prog);

	printf("  -b	Broadcast wakeup (all waiters)\n");

	printf("  -c	Use color\n");

	printf("  -h	Display this help message\n");

	printf("  -l	Lock the pi futex across requeue\n");

	printf("  -o	Use a third party pi futex owner during requeue (cancels -l)\n");

	printf("  -t N	Timeout in nanoseconds (default: 0)\n");

	printf("  -v L	Verbosity level: %d=QUIET %d=CRITICAL %d=INFO\n",

	       VQUIET, VCRITICAL, VINFO);

}

int create_rt_thread(pthread_t *pth, void*(*func)(void *), void *arg,

		     int policy, int prio)

{

	int ret;

	struct sched_param schedp;

	pthread_attr_t attr;

	pthread_attr_init(&attr);

	memset(&schedp, 0, sizeof(schedp));

	ret = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);

	if (ret) {

		error("pthread_attr_setinheritsched\n", ret);

		return -1;

	}

	ret = pthread_attr_setschedpolicy(&attr, policy);

	if (ret) {

		error("pthread_attr_setschedpolicy\n", ret);

		return -1;

	}

	schedp.sched_priority = prio;

	ret = pthread_attr_setschedparam(&attr, &schedp);

	if (ret) {

		error("pthread_attr_setschedparam\n", ret);

		return -1;

	}

	ret = pthread_create(pth, &attr, func, arg);

	if (ret) {

		error("pthread_create\n", ret);

		return -1;

	}

	return 0;

}

void *waiterfn(void *arg)

{

	struct thread_arg *args = (struct thread_arg *)arg;

	futex_t old_val;

	info("Waiter %ld: running\n", args->id);

	/* Each thread sleeps for a different amount of time

	 * This is to avoid races, because we don't lock the

	 * external mutex here */

	usleep(1000 * (long)args->id);

	old_val = f1;

	atomic_inc(&waiters_blocked);

	info("Calling futex_wait_requeue_pi: %p (%u) -> %p\n",

	     &f1, f1, &f2);

	args->ret = futex_wait_requeue_pi(&f1, old_val, &f2, args->timeout,

					  FUTEX_PRIVATE_FLAG);

	info("waiter %ld woke with %d %s\n", args->id, args->ret,

	     args->ret < 0 ? strerror(errno) : "");

	atomic_inc(&waiters_woken);

	if (args->ret < 0) {

		if (args->timeout && errno == ETIMEDOUT)

			args->ret = 0;

		else {

			args->ret = RET_ERROR;

			error("futex_wait_requeue_pi\n", errno);

		}

		futex_lock_pi(&f2, NULL, 0, FUTEX_PRIVATE_FLAG);

	}

	futex_unlock_pi(&f2, FUTEX_PRIVATE_FLAG);

	info("Waiter %ld: exiting with %d\n", args->id, args->ret);

	pthread_exit((void *)&args->ret);

}

void *broadcast_wakerfn(void *arg)

{

	struct thread_arg *args = (struct thread_arg *)arg;

	int nr_requeue = INT_MAX;

	int task_count = 0;

	futex_t old_val;

	int nr_wake = 1;

	int i = 0;

	info("Waker: waiting for waiters to block\n");

	while (waiters_blocked.val < THREAD_MAX)

		usleep(1000);

	usleep(1000);

	info("Waker: Calling broadcast\n");

	if (args->lock) {

		info("Calling FUTEX_LOCK_PI on mutex=%x @ %p\n", f2, &f2);

		futex_lock_pi(&f2, NULL, 0, FUTEX_PRIVATE_FLAG);

	}

 continue_requeue:

	old_val = f1;

	args->ret = futex_cmp_requeue_pi(&f1, old_val, &f2, nr_wake, nr_requeue,

				   FUTEX_PRIVATE_FLAG);

	if (args->ret < 0) {

		args->ret = RET_ERROR;

		error("FUTEX_CMP_REQUEUE_PI failed\n", errno);

	} else if (++i < MAX_WAKE_ITERS) {

		task_count += args->ret;

		if (task_count < THREAD_MAX - waiters_woken.val)

			goto continue_requeue;

	} else {

		error("max broadcast iterations (%d) reached with %d/%d tasks woken or requeued\n",

		       0, MAX_WAKE_ITERS, task_count, THREAD_MAX);

		args->ret = RET_ERROR;

	}

	futex_wake(&wake_complete, 1, FUTEX_PRIVATE_FLAG);

	if (args->lock)

		futex_unlock_pi(&f2, FUTEX_PRIVATE_FLAG);

	if (args->ret > 0)

		args->ret = task_count;

	info("Waker: exiting with %d\n", args->ret);

	pthread_exit((void *)&args->ret);

}

void *signal_wakerfn(void *arg)

{

	struct thread_arg *args = (struct thread_arg *)arg;

	unsigned int old_val;

	int nr_requeue = 0;

	int task_count = 0;

	int nr_wake = 1;

	int i = 0;

	info("Waker: waiting for waiters to block\n");

	while (waiters_blocked.val < THREAD_MAX)

		usleep(1000);

	usleep(1000);

	while (task_count < THREAD_MAX && waiters_woken.val < THREAD_MAX) {

		info("task_count: %d, waiters_woken: %d\n",

		     task_count, waiters_woken.val);

		if (args->lock) {

			info("Calling FUTEX_LOCK_PI on mutex=%x @ %p\n",

			     f2, &f2);

			futex_lock_pi(&f2, NULL, 0, FUTEX_PRIVATE_FLAG);

		}

		info("Waker: Calling signal\n");

		/* cond_signal */

		old_val = f1;

		args->ret = futex_cmp_requeue_pi(&f1, old_val, &f2,

						 nr_wake, nr_requeue,

						 FUTEX_PRIVATE_FLAG);

		if (args->ret < 0)

			args->ret = -errno;

		info("futex: %x\n", f2);

		if (args->lock) {

			info("Calling FUTEX_UNLOCK_PI on mutex=%x @ %p\n",

			     f2, &f2);

			futex_unlock_pi(&f2, FUTEX_PRIVATE_FLAG);

		}

		info("futex: %x\n", f2);

		if (args->ret < 0) {

			error("FUTEX_CMP_REQUEUE_PI failed\n", errno);

			args->ret = RET_ERROR;

			break;

		}

		task_count += args->ret;

		usleep(SIGNAL_PERIOD_US);

		i++;

		/* we have to loop at least THREAD_MAX times */

		if (i > MAX_WAKE_ITERS + THREAD_MAX) {

			error("max signaling iterations (%d) reached, giving up on pending waiters.\n",

			      0, MAX_WAKE_ITERS + THREAD_MAX);

			args->ret = RET_ERROR;

			break;

		}

	}

	futex_wake(&wake_complete, 1, FUTEX_PRIVATE_FLAG);

	if (args->ret >= 0)

		args->ret = task_count;

	info("Waker: exiting with %d\n", args->ret);

	info("Waker: waiters_woken: %d\n", waiters_woken.val);

	pthread_exit((void *)&args->ret);

}

void *third_party_blocker(void *arg)

{

	struct thread_arg *args = (struct thread_arg *)arg;

	int ret2 = 0;

	args->ret = futex_lock_pi(&f2, NULL, 0, FUTEX_PRIVATE_FLAG);

	if (args->ret)

		goto out;

	args->ret = futex_wait(&wake_complete, wake_complete, NULL,

			       FUTEX_PRIVATE_FLAG);

	ret2 = futex_unlock_pi(&f2, FUTEX_PRIVATE_FLAG);

 out:

	if (args->ret || ret2) {

		error("third_party_blocker() futex error", 0);

		args->ret = RET_ERROR;

	}

	pthread_exit((void *)&args->ret);

}

int unit_test(int broadcast, long lock, int third_party_owner, long timeout_ns)

{

	void *(*wakerfn)(void *) = signal_wakerfn;

	struct thread_arg blocker_arg = THREAD_ARG_INITIALIZER;

	struct thread_arg waker_arg = THREAD_ARG_INITIALIZER;

	pthread_t waiter[THREAD_MAX], waker, blocker;

	struct timespec ts, *tsp = NULL;

	struct thread_arg args[THREAD_MAX];

	int *waiter_ret;

	int i, ret = RET_PASS;

	if (timeout_ns) {

		time_t secs;

		info("timeout_ns = %ld\n", timeout_ns);

		ret = clock_gettime(CLOCK_MONOTONIC, &ts);

		secs = (ts.tv_nsec + timeout_ns) / 1000000000;

		ts.tv_nsec = ((int64_t)ts.tv_nsec + timeout_ns) % 1000000000;

		ts.tv_sec += secs;

		info("ts.tv_sec  = %ld\n", ts.tv_sec);

		info("ts.tv_nsec = %ld\n", ts.tv_nsec);

		tsp = &ts;

	}

	if (broadcast)

		wakerfn = broadcast_wakerfn;

	if (third_party_owner) {

		if (create_rt_thread(&blocker, third_party_blocker,

				     (void *)&blocker_arg, SCHED_FIFO, 1)) {

			error("Creating third party blocker thread failed\n",

			      errno);

			ret = RET_ERROR;

			goto out;

		}

	}

	atomic_set(&waiters_woken, 0);

	for (i = 0; i < THREAD_MAX; i++) {

		args[i].id = i;

		args[i].timeout = tsp;

		info("Starting thread %d\n", i);

		if (create_rt_thread(&waiter[i], waiterfn, (void *)&args[i],

				     SCHED_FIFO, 1)) {

			error("Creating waiting thread failed\n", errno);

			ret = RET_ERROR;

			goto out;

		}

	}

	waker_arg.lock = lock;

	if (create_rt_thread(&waker, wakerfn, (void *)&waker_arg,

			     SCHED_FIFO, 1)) {

		error("Creating waker thread failed\n", errno);

		ret = RET_ERROR;

		goto out;

	}

	/* Wait for threads to finish */

	/* Store the first error or failure encountered in waiter_ret */

	waiter_ret = &args[0].ret;

	for (i = 0; i < THREAD_MAX; i++)

		pthread_join(waiter[i],

			     *waiter_ret ? NULL : (void **)&waiter_ret);

	if (third_party_owner)

		pthread_join(blocker, NULL);

	pthread_join(waker, NULL);

out:

	if (!ret) {

		if (*waiter_ret)

			ret = *waiter_ret;

		else if (waker_arg.ret < 0)

			ret = waker_arg.ret;

		else if (blocker_arg.ret)

			ret = blocker_arg.ret;

	}

	return ret;

}

int main(int argc, char *argv[])

{

	int c, ret;

	while ((c = getopt(argc, argv, "bchlot:v:")) != -1) {

		switch (c) {

		case 'b':

			broadcast = 1;

			break;

		case 'c':

			log_color(1);

			break;

		case 'h':

			usage(basename(argv[0]));

			exit(0);

		case 'l':

			locked = 1;

			break;

		case 'o':

			owner = 1;

			locked = 0;

			break;

		case 't':

			timeout_ns = atoi(optarg);

			break;

		case 'v':

			log_verbosity(atoi(optarg));

			break;

		default:

			usage(basename(argv[0]));

			exit(1);

		}

	}

	printf("%s: Test requeue functionality\n", basename(argv[0]));

	printf("\tArguments: broadcast=%d locked=%d owner=%d timeout=%ldns\n",

	       broadcast, locked, owner, timeout_ns);

	/*

	 * FIXME: unit_test is obsolete now that we parse options and the

	 * various style of runs are done by run.sh - simplify the code and move

	 * unit_test into main()

	 */

	ret = unit_test(broadcast, locked, owner, timeout_ns);

	print_result(ret);

	return ret;

}

/******************************************************************************

 *

 *   Copyright © International Business Machines  Corp., 2009

 *

 *   This program is free software;  you can redistribute it and/or modify

 *   it under the terms of the GNU General Public License as published by

 *   the Free Software Foundation; either version 2 of the License, or

 *   (at your option) any later version.

 *

 * DESCRIPTION

 *      1. Block a thread using FUTEX_WAIT

 *      2. Attempt to use FUTEX_CMP_REQUEUE_PI on the futex from 1.

 *      3. The kernel must detect the mismatch and return -EINVAL.

 *

 * AUTHOR

 *      Darren Hart <dvhart@linux.intel.com>

 *

 * HISTORY

 *      2009-Nov-9: Initial version by Darren Hart <dvhart@linux.intel.com>

 *

 *****************************************************************************/

#include <errno.h>

#include <getopt.h>

#include <pthread.h>

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <time.h>

#include "futextest.h"

#include "logging.h"

futex_t f1 = FUTEX_INITIALIZER;

futex_t f2 = FUTEX_INITIALIZER;

int child_ret = 0;

void usage(char *prog)

{

	printf("Usage: %s\n", prog);

	printf("  -c	Use color\n");

	printf("  -h	Display this help message\n");

	printf("  -v L	Verbosity level: %d=QUIET %d=CRITICAL %d=INFO\n",

	       VQUIET, VCRITICAL, VINFO);

}

void *blocking_child(void *arg)

{

	child_ret = futex_wait(&f1, f1, NULL, FUTEX_PRIVATE_FLAG);

	if (child_ret < 0) {

		child_ret = -errno;

		error("futex_wait\n", errno);

	}

	return (void *)&child_ret;

}

int main(int argc, char *argv[])

{

	int ret = RET_PASS;

	pthread_t child;

	int c;

	while ((c = getopt(argc, argv, "chv:")) != -1) {

		switch (c) {

		case 'c':

			log_color(1);

			break;

		case 'h':

			usage(basename(argv[0]));

			exit(0);

		case 'v':

			log_verbosity(atoi(optarg));

			break;

		default:

			usage(basename(argv[0]));

			exit(1);

		}

	}

	printf("%s: Detect mismatched requeue_pi operations\n",

	       basename(argv[0]));

	if (pthread_create(&child, NULL, blocking_child, NULL)) {

		error("pthread_create\n", errno);

		ret = RET_ERROR;

		goto out;

	}

	/* Allow the child to block in the kernel. */

	sleep(1);

	/*

	 * The kernel should detect the waiter did not setup the

	 * q->requeue_pi_key and return -EINVAL. If it does not,

	 * it likely gave the lock to the child, which is now hung

	 * in the kernel.

	 */

	ret = futex_cmp_requeue_pi(&f1, f1, &f2, 1, 0, FUTEX_PRIVATE_FLAG);

	if (ret < 0) {

		if (errno == EINVAL) {

			/*

			 * The kernel correctly detected the mismatched

			 * requeue_pi target and aborted. Wake the child with

			 * FUTEX_WAKE.

			 */

			ret = futex_wake(&f1, 1, FUTEX_PRIVATE_FLAG);

			if (ret == 1) {

				ret = RET_PASS;

			} else if (ret < 0) {

				error("futex_wake\n", errno);

				ret = RET_ERROR;

			} else {

				error("futex_wake did not wake the child\n", 0);

				ret = RET_ERROR;

			}

		} else {

			error("futex_cmp_requeue_pi\n", errno);

			ret = RET_ERROR;

		}

	} else if (ret > 0) {

		fail("futex_cmp_requeue_pi failed to detect the mismatch\n");

		ret = RET_FAIL;

	} else {

		error("futex_cmp_requeue_pi found no waiters\n", 0);

		ret = RET_ERROR;

	}

	pthread_join(child, NULL);

	if (!ret)

		ret = child_ret;

 out:

	/* If the kernel crashes, we shouldn't return at all. */

	print_result(ret);

	return ret;

}