12aa8470fSDarren HartFutex Test 22aa8470fSDarren Hart========== 32aa8470fSDarren HartFutex Test is intended to thoroughly test the Linux kernel futex system call 42aa8470fSDarren HartAPI. 52aa8470fSDarren Hart 62aa8470fSDarren HartFunctional tests shall test the documented behavior of the futex operation 72aa8470fSDarren Hartcode under test. This includes checking for proper behavior under normal use, 82aa8470fSDarren Hartodd corner cases, regression tests, and abject abuse and misuse. 92aa8470fSDarren Hart 102aa8470fSDarren HartFutextest will also provide example implementation of mutual exclusion 112aa8470fSDarren Hartprimitives. These can be used as is in user applications or can serve as 122aa8470fSDarren Hartexamples for system libraries. These will likely be added to either a new lib/ 132aa8470fSDarren Hartdirectory or purely as header files under include/, I'm leaning toward the 142aa8470fSDarren Hartlatter. 152aa8470fSDarren Hart 162aa8470fSDarren HartQuick Start 172aa8470fSDarren Hart----------- 182aa8470fSDarren Hart# make 192aa8470fSDarren Hart# ./run.sh 202aa8470fSDarren Hart 212aa8470fSDarren HartDesign and Implementation Goals 222aa8470fSDarren Hart------------------------------- 232aa8470fSDarren Harto Tests should be as self contained as is practical so as to facilitate sharing 242aa8470fSDarren Hart the individual tests on mailing list discussions and bug reports. 252aa8470fSDarren Harto The build system shall remain as simple as possible, avoiding any archive or 262aa8470fSDarren Hart shared object building and linking. 272aa8470fSDarren Harto Where possible, any helper functions or other package-wide code shall be 282aa8470fSDarren Hart implemented in header files, avoiding the need to compile intermediate object 292aa8470fSDarren Hart files. 309e5b8a6eSWei Jiangango External dependencies shall remain as minimal as possible. Currently gcc 312aa8470fSDarren Hart and glibc are the only dependencies. 322aa8470fSDarren Harto Tests return 0 for success and < 0 for failure. 332aa8470fSDarren Hart 342aa8470fSDarren HartOutput Formatting 352aa8470fSDarren Hart----------------- 362aa8470fSDarren HartTest output shall be easily parsable by both human and machine. Title and 372aa8470fSDarren Hartresults are printed to stdout, while intermediate ERROR or FAIL messages are 382aa8470fSDarren Hartsent to stderr. Tests shall support the -c option to print PASS, FAIL, and 392aa8470fSDarren HartERROR strings in color for easy visual parsing. Output shall conform to the 402aa8470fSDarren Hartfollowing format: 412aa8470fSDarren Hart 422aa8470fSDarren Harttest_name: Description of the test 432aa8470fSDarren Hart Arguments: arg1=val1 #units specified for clarity where appropriate 442aa8470fSDarren Hart ERROR: Description of unexpected error 452aa8470fSDarren Hart FAIL: Reason for test failure 462aa8470fSDarren Hart # FIXME: Perhaps an " INFO: informational message" option would be 472aa8470fSDarren Hart # useful here. Using -v to toggle it them on and off, as with -c. 482aa8470fSDarren Hart # there may be multiple ERROR or FAIL messages 492aa8470fSDarren HartResult: (PASS|FAIL|ERROR) 502aa8470fSDarren Hart 512aa8470fSDarren HartNaming 522aa8470fSDarren Hart------ 532aa8470fSDarren Harto FIXME: decide on a sane test naming scheme. Currently the tests are named 542aa8470fSDarren Hart based on the primary futex operation they test. Eventually this will become a 552aa8470fSDarren Hart problem as we intend to write multiple tests which collide in this namespace. 562aa8470fSDarren Hart Perhaps something like "wait-wake-1" "wait-wake-2" is adequate, leaving the 572aa8470fSDarren Hart detailed description in the test source and the output. 582aa8470fSDarren Hart 592aa8470fSDarren HartCoding Style 602aa8470fSDarren Hart------------ 612aa8470fSDarren Harto The Futex Test project adheres to the coding standards set forth by Linux 62*8c27ceffSMauro Carvalho Chehab kernel as defined in the Linux source Documentation/process/coding-style.rst. 63