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