********************************************************************
The code and documentation here are by Jerry Epplin
http://stereotaxis.wustl.edu/~jerry
Changes to this code to make it work in the R9 tree have been put in.
This code is included on an experimental basis. I would like to make
the API more congruent with the standard schedular API,  and there
are some minor changes needed for SMP systems. 
    VY oct 20,1998

(Cultural note: The test program balances Barabanov's California FZ test with a 
                reference to New York's finest.
 VY)

**********************************************************************
rt_ipc is a Linux loadable module for use with Real-Time Linux.  Currently
it provides semaphores (binary and counting), message queues, and an
enhancement to the RT-FIFO mechanism that provides blocking and timeouts.

Note that with V0.3 the semantics of the timeout capability have been
changed and harmonized.  First, all rt_ipc functions use RT_NO_WAIT
for return immediately, and RT_WAIT_FOREVER for no timeout.  If neither
of these is specified, the timeout value represents the TIME AT WHICH THE
FUNCTION WILL TIMEOUT, not the amount of time that will elapse before the
function times out, as previously.  I'm of the opinion that this eimplifies
the implementation of higher-level functionality.  Let me know if you
disagree (and why).  In any case, a macro (RELATIVE_TIME) is provided
to give you relative times rather than absolute.

The goal was to implement basic IPC functionalilty as a loadable module
rather than as part of the rtlinux base system.  To accomplish this, I had
to override some of the rtlinux API, specifically the RT_TASK type, and the
rt_task_init() and rt_task_delete() functions.  These were replaced by
RT_TASK_IPC, rt_task_ipc_init(), and rt_task_ipc_delete(), respectively.

These functions are provided:

rt_task_ipc_init() -- replaces rt_task_init(), providing the same functionality.

rt_task_ipc_delete() -- replaces rt_task_delete(), providing the same
	functionality.

rt_sem_init(), rt_sem_destroy() -- semaphore creating and removal functions.

rt_sem_post(), rt_sem_wait(), rt_sem_trywait() -- semaphore functionality

rt_mq_init(), rt_mq_destroy() -- message queue creating and removal functions.

rt_mq_send(), rt_mq_receive() -- message queue functionality

rtf_ipc_create(), rtf_ipc_destroy() -- replaces rtf_create() and rtf_destroy().

rtf_receive(), rtf_send() -- fifo manipulation routines.

See the man pages for more information.  The rest of the rtlinux API is
still available.  To call a function that uses an RT_TASK, the macro
MAKE_RT_TASK() is provided.  Thus, for example, to create a task and start
it running, do something like the following:

	RT_TASK_IPC tsk;
	rt_task_ipc_init(&tsk, tsk_code, 0, 3000, 10);
	rt_task_wakeup(MAKE_RT_TASK(&tsk));

The semaphore and message queue functionality is basic -- task deletion safety,
semaphore and message queue deletion safety, and timeouts are implemented, but
priority inheritance is not.  I plan to implement priority inheritance as time
allows.

To build rt_ipc, simply type 'make'.  To install it, type 'make ins'.
To remove it, type 'make rm'.  You might have to change the path in the
Makefile.

I attempted to follow the POSIX.4 terminology for semaphores as much as
possible in order to make rt_ipc easy for people with a UNIX background
to learn.  Thus, the function names and type names are derived from
the corresponding POSIX.4 terms.  But no semantic compromises were made
to accomplish this goal; the similarities are simply syntactic.

Yes, I know the term IPC (interprocess communication) is a bit imprecise
in this context -- with the exception of the RT-FIFO facilities, rt_ipc
provides communication between real-time tasks, not Linux processes.
The term "intertask communication" is sometimes used, but I used the
terminology with which most people are familiar.

Revision history:
-----------------
0.1  21-Jul-97  Binary and counting semaphores.

0.2  28-Jul-97  Message queues.  Timeouts on both semaphores and message
                queues.

0.3  29-Aug-97  RT-FIFO enhancement.  Adds blocking and timeouts.  Also
                changed the timeout semantics of the previously-implemented
                facilities.  Placed under GPL.
