Darren Hart | 2aa8470 | 2015-05-12 21:07:52 -0700 | [diff] [blame] | 1 | Futex Test |
| 2 | ========== |
| 3 | Futex Test is intended to thoroughly test the Linux kernel futex system call |
| 4 | API. |
| 5 | |
| 6 | Functional tests shall test the documented behavior of the futex operation |
| 7 | code under test. This includes checking for proper behavior under normal use, |
| 8 | odd corner cases, regression tests, and abject abuse and misuse. |
| 9 | |
| 10 | Futextest will also provide example implementation of mutual exclusion |
| 11 | primitives. These can be used as is in user applications or can serve as |
| 12 | examples for system libraries. These will likely be added to either a new lib/ |
| 13 | directory or purely as header files under include/, I'm leaning toward the |
| 14 | latter. |
| 15 | |
| 16 | Quick Start |
| 17 | ----------- |
| 18 | # make |
| 19 | # ./run.sh |
| 20 | |
| 21 | Design and Implementation Goals |
| 22 | ------------------------------- |
| 23 | o 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. |
| 25 | o The build system shall remain as simple as possible, avoiding any archive or |
| 26 | shared object building and linking. |
| 27 | o 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. |
Wei Jiangang | 9e5b8a6 | 2015-11-09 14:26:39 +0800 | [diff] [blame] | 30 | o External dependencies shall remain as minimal as possible. Currently gcc |
Darren Hart | 2aa8470 | 2015-05-12 21:07:52 -0700 | [diff] [blame] | 31 | and glibc are the only dependencies. |
| 32 | o Tests return 0 for success and < 0 for failure. |
| 33 | |
| 34 | Output Formatting |
| 35 | ----------------- |
| 36 | Test output shall be easily parsable by both human and machine. Title and |
| 37 | results are printed to stdout, while intermediate ERROR or FAIL messages are |
| 38 | sent to stderr. Tests shall support the -c option to print PASS, FAIL, and |
| 39 | ERROR strings in color for easy visual parsing. Output shall conform to the |
| 40 | following format: |
| 41 | |
| 42 | test_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 |
| 49 | Result: (PASS|FAIL|ERROR) |
| 50 | |
| 51 | Naming |
| 52 | ------ |
| 53 | o 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 | |
| 59 | Coding Style |
| 60 | ------------ |
| 61 | o The Futex Test project adheres to the coding standards set forth by Linux |
| 62 | kernel as defined in the Linux source Documentation/CodingStyle. |