
This is the readme file for the high-res-timer patch.

For 2004-8-11 release

Work has been done on the make files to allow the make to work in
different environments.  In particular the test make will look for
libposixtime in:

../lib/
lib/
/lib/

in that order.  Also, for the first two cases, it will attempt to do a
make in that directory if the directory exists.  Please see the rules
for that make, below.

The lib make (to make libposixtime.a) now looks for the needed kernel
headers in:

../../../include/
../../linux/include/

This means you can put install the test package in the following way:

somewhere/tests      put the tests here
somewhere/tests/lib  put the lib stuff here
somewhere/linux      This should be a link to the kernel include dir

-OR-

You can leave it as in this patch, i.e.:

somewhere/tests      put the tests here
somewhere/lib  put the lib stuff here
somewhere/linux      This should be a link to the kernel include dir


To build the library and the tests you will must either modify the
bits/siginfo.h file (see the patch at usr_incl/ in the same dir you
found this file) OR supply the version herein and put it here:

somewhere/tests/usr_incl/bits/siginfo.h  (organization 1 above) - OR -
somewhere/usr_incl/bits/siginfo.h  (organization 2 above)

It must be reachable from the lib dir as "../usr_incl"

Additional tests have been added:

abs_timer_test   tests to insure that absolute timers follow the clock setting
4-1              the community version of the same (a bit weak, but...).
nanosleep_jitter gives a good idea of you latencies and just what to expect.

The tests have also 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.
 

For 2004-4-20 release

With the calls in the kernel, you should be seeing newer glibc packages
picking up some or all of the lib code we have here.  I am hoping that
the only thing missing is the two definitions for the high res clocks
(CLOCK_REALTIME_HR and CLOCK_MONOTONIC_HR).  If this is true, all you
will need is to provide these two defines to your build environment.

I welcome feed back on this issue.

New with this release (2.4.20/ 2.5.62):

LibX is now gone.  The stuff in lib will build both libraries.  We also
find the kernel library by using "../../../" so notes below on setting
up links are no longer useful.  If you want to put this patch other than
in the current tree, you will need to modify the lib/Makefile to tell it
where to look for the kernel include files.  This should not be much of
a problem for 2.6 kernels as we now have fixed system call numbers so
you don't really need to use the latest kernel any more.


New with this release (2.4.20):

We have been sending the libX directory with the patch for a while now.
You might like to know what it is good for.  If you rename the "lib" to
something else you can then rename libX to lib.  Using the make file
there you will be making an archive library (the current lib dir makes a
shared library).  Why would you want to do this?  Well the main reason
is the shared lib only builds for arch/i386, while the archive lib
should build for any arch.  To use this you would then need to modify
the tests make file to use the archive lib.  So why the shared lib?
Mainly by using a shared lib you don't need to remake the aps every time
the kernel changes such that the call numbers change.

New with this release (2.4.18-3.0):

The info below has changed.  Please read it again rather than assume it
is the same.


This file and those "near" it are in the kernel tree.  You may move it
out if you like, however, if you build the library file where it is you
should not need to mess with the links to the kernel tree as described
below.  Also, should you want to send me a patch, I would like it to be
in this location.

Be aware that the patch is not just to the kernel.  There are four
parts:

1.)The kernel patch (this is in a separate patch) 
2.)A library file (contains the system call stubs and a header file), and
3.)A patch to a header files to expand some of the signal structures and
such. 
4.)A set of test programs.

For the newer glibc library, the bits/types.h file is ok as it stands.
An old version is included just in case, but it is renamed to stay out
of the way (see ./usr_incl/bits/).  The bits/signinfo.h file provided
is, I think, compatible with both the new and old libraries.  I included
a patched version from the Red Hat 7.3 distro.  There is also a patch in
case you want to know what changed or want to use some other version.  I
think the patch file for this header will work with both old and new
libraries.  In any case you have the desired result and can act
accordingly.

There are a bunch of other header files under usr_incl.  These are used
ONLY to make the system call stub library.  The only file you may want
to move to /usr/include is the bits/siginfo.h file.

If you like, you can copy the siginfo.h file to a separate directory
(called "bits"), and then use "-I/xxx" in the cc command, where "xxx" is
the path to then new bits directory. (Don't include "bits" in xxx, the
#include <bits/yyy.h> has the "bits" in it.)  This is what I am doing
for testing so as not to affect my include files till I am REALLY sure
this is what I want.  The test program Makefile is set up to pick up the
include files from the directory created for them by applying this
patch.  The patch includes a patched version of siginfo.h, but you may
want to patch your own to be sure you have current versions for your
system (this is from glib-2.2.4-13).

Header file issues: In addition to the headers called out in the
standard and the man pages you will want to include the lib/posix_time.h
file in this patch.  This file is automatically configured by the library
make file to remove a possible conflict with your standard headers.  It
has everything you need to use glibc versions as old as 2.1.2.  New
glibc versions have almost all of this stuff included in them.  If you
have trouble with the auto configure stuff, all it changes is an #ifdef
NEED_ITIMERSPEC.  Do let me know if this does not work on your system.

You will need to build the library file (Makefile is included in the
patch) AFTER you patch the kernel as it uses the system call definitions
the patch puts in (also after the first make on the tree so that the asm
link in include is defined in the kernel tree).  In order for this to
work you need to have a symbolic link in /usr/include for asm that
points to the kernel include asm directory.  You already have this link,
but it may point to a different kernel if you have more than one on your
system.  Again, you can provide an alternative for this by putting
"-Ipath/include" in the CPPFLAGS macro in the library build make file.
Here path should be to the top directory of your new kernel (i.e. where
include is found).  Note, the Makefile tries to point to a directory in
the tarball but this will not exist and should be harmless if you have
the correct asm link.  A recommended link for asm in /usr/include is:

ln -s ../src/linux/include/asm asm

This assumes that you have your kernel(s) located in the /usr/src
directory and have a symbolic link to the current kernel (which you will
need to do the patch).  If you should move to a new kernel, changing the
link in /usr/src will allow the /usr/include/asm to follow.

After building the library, install it in your /usr/lib directory on
your target. Then rebuild your kernel, and you should be set to build
timer calls into your applications.

MAN PAGES

We now have man pages (Thanks to Robert Love).  

However, we did the man pages for the system we would like to have, but
don't just yet.  Here are the known deficiencies:

The SIGEV_THREAD stuff in timer_create() requires glibc or thread
package support which we just don't have yet.

The SIGEV_THREAD in timer_create() requires thread groups be supported
in the thread package.  Linux threads does not yet use thread groups so
this will not work.  If you do create your own, or use a thread package
that does use thread groups, be aware that the thread id that is to be
passed to the kernel must be a pid, not a pthread_t id.  Again glibc
will do this translation once it gets to using thread groups.

The clock_* man pages talk about two CLOCK_*CPU* clocks.  These will be
supported someday, but not just yet.  For now, expect bad clock id
errors on these clocks.

The man pages on *_getcpuclockid actually describe functions in the
existing glibc, at least at newer revs.  You may or may not actually
find the functions depending on your glibc version.  Not that it
matters, because, as we said above, we don't yet support these clocks in
the kernel.

Installing the man pages:

In the .../man directory there is a make file that will install the
pages.  The target directory must exist and is determined as follows:

# If the environment variable MANPATH is defined and not null, use the
# first entry in it.

# Otherwise, if "/etc/man.config" exists, use the first MANPATH entry in
# it.  If both of these fail, print an error and quit.

# If you want to override this to put the pages in directory foo use:
# make MANPATH=foo

# If you  want to  force it to  use the  /etc/man.config and you  have a
# MANPATH use: make MANPATH=

Usually you will need root capability to store into the man page
directory.

Thats all the problems I can think of.  As always, let me know if there
is more to be said here, or anywhere.

Let me know if you have any problems.  I would like to keep these
instructions for the next user...  Be nice if they were correct :)

George Anzinger george@mvista.com

