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