0001 Futex Test
0002 ==========
0003 Futex Test is intended to thoroughly test the Linux kernel futex system call
0004 API.
0005
0006 Functional tests shall test the documented behavior of the futex operation
0007 code under test. This includes checking for proper behavior under normal use,
0008 odd corner cases, regression tests, and abject abuse and misuse.
0009
0010 Futextest will also provide example implementation of mutual exclusion
0011 primitives. These can be used as is in user applications or can serve as
0012 examples for system libraries. These will likely be added to either a new lib/
0013 directory or purely as header files under include/, I'm leaning toward the
0014 latter.
0015
0016 Quick Start
0017 -----------
0018 # make
0019 # ./run.sh
0020
0021 Design and Implementation Goals
0022 -------------------------------
0023 o Tests should be as self contained as is practical so as to facilitate sharing
0024 the individual tests on mailing list discussions and bug reports.
0025 o The build system shall remain as simple as possible, avoiding any archive or
0026 shared object building and linking.
0027 o Where possible, any helper functions or other package-wide code shall be
0028 implemented in header files, avoiding the need to compile intermediate object
0029 files.
0030 o External dependencies shall remain as minimal as possible. Currently gcc
0031 and glibc are the only dependencies.
0032 o Tests return 0 for success and < 0 for failure.
0033
0034 Output Formatting
0035 -----------------
0036 Test output shall be easily parsable by both human and machine. Title and
0037 results are printed to stdout, while intermediate ERROR or FAIL messages are
0038 sent to stderr. Tests shall support the -c option to print PASS, FAIL, and
0039 ERROR strings in color for easy visual parsing. Output shall conform to the
0040 following format:
0041
0042 test_name: Description of the test
0043 Arguments: arg1=val1 #units specified for clarity where appropriate
0044 ERROR: Description of unexpected error
0045 FAIL: Reason for test failure
0046 # FIXME: Perhaps an " INFO: informational message" option would be
0047 # useful here. Using -v to toggle it them on and off, as with -c.
0048 # there may be multiple ERROR or FAIL messages
0049 Result: (PASS|FAIL|ERROR)
0050
0051 Naming
0052 ------
0053 o FIXME: decide on a sane test naming scheme. Currently the tests are named
0054 based on the primary futex operation they test. Eventually this will become a
0055 problem as we intend to write multiple tests which collide in this namespace.
0056 Perhaps something like "wait-wake-1" "wait-wake-2" is adequate, leaving the
0057 detailed description in the test source and the output.
0058
0059 Coding Style
0060 ------------
0061 o The Futex Test project adheres to the coding standards set forth by Linux
0062 kernel as defined in the Linux source Documentation/process/coding-style.rst.
