| 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 dependencies 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/process/coding-style.rst. |