testcases/open_posix_testsuite/functional/threads/pi_test/README - platform/external/ltp - Gitiles

 Real Time NPTL(rt-nptl) test suite README
 =========================================

 The document describes what rt-nptl tests are, how they are created,
 how to make and run the tests and how to analysis the result.

 rt-nptl tests include two parts, one is robust mutex tests, the other
 is priority inheritance(pi) mutex tests.

 In the document, <rtnptl-tests> stands for the directory where
 rtnptl-tests was extracted.


 Building the tests
 -------------------
 If you use the build method outlined in INSTALL-rtnptl, then just
 change the top Makefile and the two Makefile under pi_test and
 robust_test to include the Makefile.inc generated by INSTALL-rtnptl.

 Otherwise, you need to set the CFLAGS and LDFLAGS of the Makefile to
 point to where your copy of glibc+RTNPTL is built.

 Run the tests
 ----------------
 Use ./run.sh to run the tests; this makes sure there is a basic
 watchdog timer to kill the pi mutex tests if they fail.

 For different tests, there are different result analysis methods. The
 following two sections will describe this in detail.

 Robust Mutex Tests
 ------------------------
 The tests are under <rtnptl-tests>/robust_test directory.

 rt-nptl supports 'robust' behavior, there will be two robust modes,
 one is PTHREAD_MUTEX_ROBUST_NP mode, the other is
 PTHREAD_MUTEX_ROBUST_SUN_NP mode. When the owner of a mutex dies in
 the first mode, the waiter will set the mutex to ENOTRECOVERABLE
 state, while in the second mode, the waiter needs to call
 pthread_mutex_setconsistency_np to change the state manually.

 The tests with name robust*-sun are used to test the
 PTHREAD_MUTEX_ROBUST_NP mode, other tests with name robust*-mode2 are
 used to test the PTHREAD_MUTEX_ROBUST_SUN_NP mode. Please refer to the
 description in the tests for the detailed information.

 Using run.sh under <rtnptl-tests>/robust_test to run the robust mutex
 tests automatically, the PASS or FAIL result can be obtained from the
 stdout.

 Priority Inheritance Mutex Tests
 --------------------------
 The tests are under <rtnptl-tests>/pi_test directory.

 rt-nptl supports priority inheritance, if task TL with priority P(TL)
 held a mutex, task TB with priority P(TB) claims the mutex and becomes
 a waiter, P(TB)>P(TL), TL will boost to TB's priority until it
 releases the lock. The pi mutex tests create several scenarios to test
 this functionality. Please refer to the description in the tests for
 the detailed information.

 Currently pi mutex tests don't provide automatic PASS or FAIL result
 display. Although users can use run.sh under <rtnptl-tests>/pi_test to
 run the pi mutex tests, they need to analyze the output to get the
 PASS or FAIL test result manually. After executing run.sh, the output
 files will be generated with the name output.<testcasename>, such as
 output.pitest-1.

 If users use run.sh from ssh, to avoid the priority inversion
 problem happened occasionally, users can use "chrt -p -f $PRIORITY
 $$PPID" to increase the priority of sshd, if use run.sh from console,
 users can use "chrt -p -f $PRIORITY $$" to increase the shell priority
 before executing run.sh.

 A sampling thread will sample the progress of working threads (TL, TPs
 and TFs) at a specified interval and print out an integer value.
 Progress of TL and TP is measured by how many times they execute a
 busy loop; the output of this count indicates how far they progress
 with respect to each other.

 The first column of the output is the time when sampling happens. The
 second column indicates the progress of TL thread at that time. The
 third column indicates the progress of TP at that time. For pitest-2
 and pitest-3, the second column is TP1 and the third column is TP2.
 The remaining columns indicate the progress of TF (if any).

 If the priority of TL is higher than (or equal to) the priority of TP,
 TP will make not progress (the output of TP will not increase, since
 it will not be scheduled to execute). Otherwise, TP and TL will both
 make progress. As a result, Users can observe the priority change of
 TL by the progress of TP.

 Users can also use 'do-plot' utility under <rtnptl-tests>/pi_test to
 generate a diagram using the output of test case. To do so:

 1. Redirect the output of test case into a file, e.g:
 	pitest-1 > output.pitest-1

 2. Under X term, run:
 	do-plot output.pitest-1

 do-plot will invoke 'gnuplot' to generate a diagram showing the
 progress of TL and TP. ('gnuplot has to be installed in the system').

 Given pitest-1 as an example:
 If the pi function works, TF's progress should be a straight line
 constantly going up; TP's progress should start at about 10 seconds
 and should be parallel to TF's until ten seconds later (20 seconds)
 when TL is created; at this time TP's slope should go down a wee bit
 and TL's slope should not be zero. After 10 seconds (30 seconds), TB
 is created and TL boosted. At this moment, TP's slope should go down
 to zero and TL's should be parallel to TF's. After TB timeouts on
 waiting the mutex (50 seconds), TL and TP's slope will change back to
 the original trend during 20~30 seconds.

 You can refer to
 http://developer.osdl.org/dev/robustmutexes/pitest-1-0.5.png for the
 diagram generated by do-plot for pitest-1.
	Real Time NPTL(rt-nptl) test suite README
	=========================================

	The document describes what rt-nptl tests are, how they are created,
	how to make and run the tests and how to analysis the result.

	rt-nptl tests include two parts, one is robust mutex tests, the other
	is priority inheritance(pi) mutex tests.

	In the document, <rtnptl-tests> stands for the directory where
	rtnptl-tests was extracted.


	Building the tests
	-------------------
	If you use the build method outlined in INSTALL-rtnptl, then just
	change the top Makefile and the two Makefile under pi_test and
	robust_test to include the Makefile.inc generated by INSTALL-rtnptl.

	Otherwise, you need to set the CFLAGS and LDFLAGS of the Makefile to
	point to where your copy of glibc+RTNPTL is built.

	Run the tests
	----------------
	Use ./run.sh to run the tests; this makes sure there is a basic
	watchdog timer to kill the pi mutex tests if they fail.

	For different tests, there are different result analysis methods. The
	following two sections will describe this in detail.

	Robust Mutex Tests
	------------------------
	The tests are under <rtnptl-tests>/robust_test directory.

	rt-nptl supports 'robust' behavior, there will be two robust modes,
	one is PTHREAD_MUTEX_ROBUST_NP mode, the other is
	PTHREAD_MUTEX_ROBUST_SUN_NP mode. When the owner of a mutex dies in
	the first mode, the waiter will set the mutex to ENOTRECOVERABLE
	state, while in the second mode, the waiter needs to call
	pthread_mutex_setconsistency_np to change the state manually.

	The tests with name robust*-sun are used to test the
	PTHREAD_MUTEX_ROBUST_NP mode, other tests with name robust*-mode2 are
	used to test the PTHREAD_MUTEX_ROBUST_SUN_NP mode. Please refer to the
	description in the tests for the detailed information.

	Using run.sh under <rtnptl-tests>/robust_test to run the robust mutex
	tests automatically, the PASS or FAIL result can be obtained from the
	stdout.

	Priority Inheritance Mutex Tests
	--------------------------
	The tests are under <rtnptl-tests>/pi_test directory.

	rt-nptl supports priority inheritance, if task TL with priority P(TL)
	held a mutex, task TB with priority P(TB) claims the mutex and becomes
	a waiter, P(TB)>P(TL), TL will boost to TB's priority until it
	releases the lock. The pi mutex tests create several scenarios to test
	this functionality. Please refer to the description in the tests for
	the detailed information.

	Currently pi mutex tests don't provide automatic PASS or FAIL result
	display. Although users can use run.sh under <rtnptl-tests>/pi_test to
	run the pi mutex tests, they need to analyze the output to get the
	PASS or FAIL test result manually. After executing run.sh, the output
	files will be generated with the name output.<testcasename>, such as
	output.pitest-1.

	If users use run.sh from ssh, to avoid the priority inversion
	problem happened occasionally, users can use "chrt -p -f $PRIORITY
	$$PPID" to increase the priority of sshd, if use run.sh from console,
	users can use "chrt -p -f $PRIORITY $$" to increase the shell priority
	before executing run.sh.

	A sampling thread will sample the progress of working threads (TL, TPs
	and TFs) at a specified interval and print out an integer value.
	Progress of TL and TP is measured by how many times they execute a
	busy loop; the output of this count indicates how far they progress
	with respect to each other.

	The first column of the output is the time when sampling happens. The
	second column indicates the progress of TL thread at that time. The
	third column indicates the progress of TP at that time. For pitest-2
	and pitest-3, the second column is TP1 and the third column is TP2.
	The remaining columns indicate the progress of TF (if any).

	If the priority of TL is higher than (or equal to) the priority of TP,
	TP will make not progress (the output of TP will not increase, since
	it will not be scheduled to execute). Otherwise, TP and TL will both
	make progress. As a result, Users can observe the priority change of
	TL by the progress of TP.

	Users can also use 'do-plot' utility under <rtnptl-tests>/pi_test to
	generate a diagram using the output of test case. To do so:

	1. Redirect the output of test case into a file, e.g:
	pitest-1 > output.pitest-1

	2. Under X term, run:
	do-plot output.pitest-1

	do-plot will invoke 'gnuplot' to generate a diagram showing the
	progress of TL and TP. ('gnuplot has to be installed in the system').

	Given pitest-1 as an example:
	If the pi function works, TF's progress should be a straight line
	constantly going up; TP's progress should start at about 10 seconds
	and should be parallel to TF's until ten seconds later (20 seconds)
	when TL is created; at this time TP's slope should go down a wee bit
	and TL's slope should not be zero. After 10 seconds (30 seconds), TB
	is created and TL boosted. At this moment, TP's slope should go down
	to zero and TL's should be parallel to TF's. After TB timeouts on
	waiting the mutex (50 seconds), TL and TP's slope will change back to
	the original trend during 20~30 seconds.

	You can refer to
	http://developer.osdl.org/dev/robustmutexes/pitest-1-0.5.png for the
	diagram generated by do-plot for pitest-1.