README
1Futex Test
2==========
3Futex Test is intended to thoroughly test the Linux kernel futex system call
4API.
5
6Functional tests shall test the documented behavior of the futex operation
7code under test. This includes checking for proper behavior under normal use,
8odd corner cases, regression tests, and abject abuse and misuse.
9
10Futextest will also provide example implementation of mutual exclusion
11primitives. These can be used as is in user applications or can serve as
12examples for system libraries. These will likely be added to either a new lib/
13directory or purely as header files under include/, I'm leaning toward the
14latter.
15
16Quick Start
17-----------
18# make
19# ./run.sh
20
21Design and Implementation Goals
22-------------------------------
23o Tests should be as self contained as is practical so as to facilitate sharing
24 the individual tests on mailing list discussions and bug reports.
25o The build system shall remain as simple as possible, avoiding any archive or
26 shared object building and linking.
27o Where possible, any helper functions or other package-wide code shall be
28 implemented in header files, avoiding the need to compile intermediate object
29 files.
30o External dependencies shall remain as minimal as possible. Currently gcc
31 and glibc are the only dependencies.
32o Tests return 0 for success and < 0 for failure.
33
34Output Formatting
35-----------------
36Test output shall be easily parsable by both human and machine. Title and
37results are printed to stdout, while intermediate ERROR or FAIL messages are
38sent to stderr. Tests shall support the -c option to print PASS, FAIL, and
39ERROR strings in color for easy visual parsing. Output shall conform to the
40following format:
41
42test_name: Description of the test
43 Arguments: arg1=val1 #units specified for clarity where appropriate
44 ERROR: Description of unexpected error
45 FAIL: Reason for test failure
46 # FIXME: Perhaps an " INFO: informational message" option would be
47 # useful here. Using -v to toggle it them on and off, as with -c.
48 # there may be multiple ERROR or FAIL messages
49Result: (PASS|FAIL|ERROR)
50
51Naming
52------
53o FIXME: decide on a sane test naming scheme. Currently the tests are named
54 based on the primary futex operation they test. Eventually this will become a
55 problem as we intend to write multiple tests which collide in this namespace.
56 Perhaps something like "wait-wake-1" "wait-wake-2" is adequate, leaving the
57 detailed description in the test source and the output.
58
59Coding Style
60------------
61o The Futex Test project adheres to the coding standards set forth by Linux
62 kernel as defined in the Linux source Documentation/process/coding-style.rst.
63
