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

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


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. Run "make" from the "lib" directory first, and then run "make"
in this directory in order to build the tests.

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.  Note that this script assumes that there is a "doi"
program or script that allows root permissions, which are needed for the
clock_settime test.  You can remove "doi" if you run "do_tests" with
root permissions, or just understand that the test will fail (with
proper red line error reporting).

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

Run "2timer_test". You will see several timer expiration messages. The
number of messages you seen 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.



