1Real Time NPTL(rt-nptl) test suite README 2========================================= 3 4The document describes what rt-nptl tests are, how they are created, 5how to make and run the tests and how to analysis the result. 6 7rt-nptl tests include two parts, one is robust mutex tests, the other 8is priority inheritance(pi) mutex tests. 9 10In the document, <rtnptl-tests> stands for the directory where 11rtnptl-tests was extracted. 12 13 14Building the tests 15------------------- 16If you use the build method outlined in INSTALL-rtnptl, then just 17change the top Makefile and the two Makefile under pi_test and 18robust_test to include the Makefile.inc generated by INSTALL-rtnptl. 19 20Otherwise, you need to set the CFLAGS and LDFLAGS of the Makefile to 21point to where your copy of glibc+RTNPTL is built. 22 23Run the tests 24---------------- 25Use ./run.sh to run the tests; this makes sure there is a basic 26watchdog timer to kill the pi mutex tests if they fail. 27 28For different tests, there are different result analysis methods. The 29following two sections will describe this in detail. 30 31Robust Mutex Tests 32------------------------ 33The tests are under <rtnptl-tests>/robust_test directory. 34 35rt-nptl supports 'robust' behavior, there will be two robust modes, 36one is PTHREAD_MUTEX_ROBUST_NP mode, the other is 37PTHREAD_MUTEX_ROBUST_SUN_NP mode. When the owner of a mutex dies in 38the first mode, the waiter will set the mutex to ENOTRECOVERABLE 39state, while in the second mode, the waiter needs to call 40pthread_mutex_setconsistency_np to change the state manually. 41 42The tests with name robust*-sun are used to test the 43PTHREAD_MUTEX_ROBUST_NP mode, other tests with name robust*-mode2 are 44used to test the PTHREAD_MUTEX_ROBUST_SUN_NP mode. Please refer to the 45description in the tests for the detailed information. 46 47Using run.sh under <rtnptl-tests>/robust_test to run the robust mutex 48tests automatically, the PASS or FAIL result can be obtained from the 49stdout. 50 51Priority Inheritance Mutex Tests 52-------------------------- 53The tests are under <rtnptl-tests>/pi_test directory. 54 55rt-nptl supports priority inheritance, if task TL with priority P(TL) 56held a mutex, task TB with priority P(TB) claims the mutex and becomes 57a waiter, P(TB)>P(TL), TL will boost to TB's priority until it 58releases the lock. The pi mutex tests create several scenarios to test 59this functionality. Please refer to the description in the tests for 60the detailed information. 61 62Currently pi mutex tests don't provide automatic PASS or FAIL result 63display. Although users can use run.sh under <rtnptl-tests>/pi_test to 64run the pi mutex tests, they need to analyze the output to get the 65PASS or FAIL test result manually. After executing run.sh, the output 66files will be generated with the name output.<testcasename>, such as 67output.pitest-1. 68 69If users use run.sh from ssh, to avoid the priority inversion 70problem happened occasionally, users can use "chrt -p -f $PRIORITY 71$$PPID" to increase the priority of sshd, if use run.sh from console, 72users can use "chrt -p -f $PRIORITY $$" to increase the shell priority 73before executing run.sh. 74 75A sampling thread will sample the progress of working threads (TL, TPs 76and TFs) at a specified interval and print out an integer value. 77Progress of TL and TP is measured by how many times they execute a 78busy loop; the output of this count indicates how far they progress 79with respect to each other. 80 81The first column of the output is the time when sampling happens. The 82second column indicates the progress of TL thread at that time. The 83third column indicates the progress of TP at that time. For pitest-2 84and pitest-3, the second column is TP1 and the third column is TP2. 85The remaining columns indicate the progress of TF (if any). 86 87If the priority of TL is higher than (or equal to) the priority of TP, 88TP will make not progress (the output of TP will not increase, since 89it will not be scheduled to execute). Otherwise, TP and TL will both 90make progress. As a result, Users can observe the priority change of 91TL by the progress of TP. 92 93Users can also use 'do-plot' utility under <rtnptl-tests>/pi_test to 94generate a diagram using the output of test case. To do so: 95 961. Redirect the output of test case into a file, e.g: 97 pitest-1 > output.pitest-1 98 992. Under X term, run: 100 do-plot output.pitest-1 101 102do-plot will invoke 'gnuplot' to generate a diagram showing the 103progress of TL and TP. ('gnuplot has to be installed in the system'). 104 105Given pitest-1 as an example: 106If the pi function works, TF's progress should be a straight line 107constantly going up; TP's progress should start at about 10 seconds 108and should be parallel to TF's until ten seconds later (20 seconds) 109when TL is created; at this time TP's slope should go down a wee bit 110and TL's slope should not be zero. After 10 seconds (30 seconds), TB 111is created and TL boosted. At this moment, TP's slope should go down 112to zero and TL's should be parallel to TF's. After TB timeouts on 113waiting the mutex (50 seconds), TL and TP's slope will change back to 114the original trend during 20~30 seconds. 115 116You can refer to 117http://developer.osdl.org/dev/robustmutexes/pitest-1-0.5.png for the 118diagram generated by do-plot for pitest-1. 119
