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