		 How to use the time test programs
		 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

	       By Shyam Pather (spather@ittc.ukans.edu)
		Updated by George Anzinger (george@mvista.com) 
		last edit: <20040904.1116.39>


See: http://sourceforge.net/projects/high-res-timers/

for more information about this project.

About this document
-------------------

This document describes the use of the test programs supplied with the
high res timing patch. This document does not explain in detail what
each program does. That information is in a comment at the top of each
source file. This document instead explains how to run the tests -
what to type when, what you should expect to see etc.

Building the tests 
------------------ 

These test programs require the "libposixtime.a" library in order to
build. Running the tests make will build that lib if needed.

Most of these tests use the utils.h in the tests directory which defines
various ways of printing results.  We are slowly changing the tests to
keep track of failures and to print error reports in color (red) and
summary reports in yellow if all is OK, other wise this too will be in
red.  The do_test script will run most of the tests and print a summary
of the results.  You must have root permissions to correctly run the
tests that set the clock (clock_nanosleeptest, 1-4, abs_timer_test,
clock_settimetest).  Since "do_tests" runs these tests yous should have
root permissions, or just understand that the test will fail (with
proper red line error reporting).

Running the tests ----------------- 

The tests have been cleaned up a bit and a LOT of verbiage eliminated
from the output.  All errors will still be reported AND you can turn on
the verbiage if you eyes are strong :) Here is the code (as param 1 when
run):

 * Verbose flags are as follows:
 * 0 Really quite.  Print only summary error count and errors.
 * 1 (default) Print above plus descriptive info (i.e. test info)
 * 2 above plus details of test being run
 * 3 above plus debug info.
 


Run "2timer_test". You will see several timer expiration messages. The
number of messages you see varies, depending on whether the program is
being run from the console or from X (this has to do with the speed of
I/O, but is not a "problem" - this is a very simple program that does
not use sophisticated synchronization methods to control the order in
which events occur, and thus the timer can sometimes fire more times
that necessary). You can easily modify this program to run thru various
times and clocks, see the final lines.

The output will be one line for each timer expiration plus a couple for
details on the particular test.

This is sufficient to show that timers can be created, set, and deleted.

			    =-*-=-*-=-*-=

Run "clock_getrestest". The output should look something like:

(Resolution of CLOCK_REALTIME) tv_sec == 0, tv_nsec == 10000000
(Resolution of CLOCK_REALTIME_HR) tv_sec == 0, tv_nsec == 1000

This simply shows the resolution of the two defined system clocks. 

			    =-*-=-*-=-*-=

Run "clock_gettimetest". This program simply calls clock_gettime() in
a loop, and should show a monotonically increasing series of time
values, such as:

(1074169249) tv_sec == 869352130, tv_nsec == 416550000
(1074169250) tv_sec == 869352130, tv_nsec == 416734000
(1074169251) tv_sec == 869352130, tv_nsec == 416917000
(1074169252) tv_sec == 869352130, tv_nsec == 417101000
(1074169253) tv_sec == 869352130, tv_nsec == 417284000
(1074169254) tv_sec == 869352130, tv_nsec == 417469000

			    =-*-=-*-=-*-=

Run "clock_gettimetest2". This program is similar to the one above,
except that it interleaves calls to clock_gettime() with calls to
gettimeofday(), the standard Linux time query system call. Again the
time values should be montonically increasing, and the clock_gettime()
results should have a higher resolution than those of gettimeofday()
(gettimeofday() reports only in terms of microseconds (usec), whereas
clock_gettime() reports in terms of nanoseconds (nsec)). The output
should look something like:

(812) tv_sec == 869352285, tv_usec == 263945
(812) tv_sec == 869352285, tv_nsec == 264101000
(813) tv_sec == 869352285, tv_usec == 264266
(813) tv_sec == 869352285, tv_nsec == 264422000
(814) tv_sec == 869352285, tv_usec == 264586
(814) tv_sec == 869352285, tv_nsec == 264743000

This shows that clock_gettime() returns time values consistent with
those of the standard Linux time querying system call.



