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