readme.fifos

实时fifo先进先出队列

Introduction
------------

Here you'll find a new fifo implementation for RTAI. It maintains full
compatibility with the basic services provided by its original NMT-RTL 
counterpart while adding some more. 

It is important to remark that even if the RTAI fifo API appears as before the
implementation behind it is based on the mailboxes concepts, already available
in RTAI and symmetrically usable from kernel modules and Linux processes. 
The only notable difference, apart from the file style API functions to be used
in Linux processes, is that on the module side you always have only non blocking
put/get, so that any different policy should be enforced by using appropriate 
user handler functions.

Handler Functions
-----------------

With regard to fifo handlers it is now possible to install also one with a read
write argument (read 'r', write 'w'). In this way you have a handler that can
what it has been called for. It is usefull when you open read-write fifos or to
check against miscalls. For that you can have a handler prototyped as:
        int x_handler(unsigned int fifo, int rw);
that can be installed by using:
        rtf_create_handler(fifo_numver, X_FIFO_HANDLER(x_handler).
see rtai_fifos.h for the X_FIFO_HANDLER macro definition.
The handler code is likely to be a kind of:
 
int x_handler(unsigned int fifo, int rw);
{
        if (rw == 'r') {
// do stuff for a call from read and return appropriate value.                   
        } else {
// do stuff for a call from write and return appropriate value.
        }
}                                                                                

Signal interface
----------------

Even if fifos are strictly no more required in RTAI, because of the availability
of LXRT, fifos are kept for both compatibility reasons and because they are very
useful tools to be used to communicate with interrupt handlers, since they do 
not require any scheduler to be installed.
In this sense you can see this new implementation of fifos as a kind of
universal form of device drivers, since once you have your interrupt handler
installed you can use fifo services to do all the rest.                          

However the new implementation made it easy to add some new services. One of
these is the possibility of using asyncronous signals to notify data
availability by catching a user set signal. It is implemented in a standard way,
see the function:
	- rtf_set_async_sig(int fd, int signum) (default signum is SIGIO);
and standard Linux man for fcntl and signal/sigaction, while the others are 
specific to this implementation.

A complete picture of what is available can be obtained from a look at 
rtai_fifos.h prototypes. 

Select/poll and Blocking
------------------------

It is important to remark that now fifos allows multiple readers/writers so
the select/poll mechanism to synchronize with in/out data can lead to unexpected
blocks for such cases. For example: you poll and get that there are data 
available, then read/write them sure not to be blocked, meanwhile another
user gets into and stoles all of your data, when you ask for them you get 
blocked.

To avoid such problems you have available the functions:
	- rtf_read_all_at_once(fd, buf, count);
that blocks till all count bytes are available and:
	- rtf_read_timed(fd, buf, count, ms_delay);
	- rtf_write_timed(fd, buf, count, ms_delay);
that block just for the specified delay in millisecs but are queued in real time
Linux process priority order. If ms_delay is zero they return immediatly with 
all the data they could get, even if you did not set O_NONBLOCK at fifo opening.
So by mixing normal read/writes with their friends above you can easily 
implement blocking, non blocking and timed IOs. They are not standard and so 
not portable, but far easy to use then the select/poll mechanism. 
The standard llseek is also available but it is equivalent to calling rtf_reset,
whatever fifo place you point at in the call.

For an easier timing you have available also: 
	- rtf_suspend_timed(fd, ms_delay).

User space creation
-------------------

To make them easier to use, fifos can now be created by the user at open time.
If a fifo that does not exist already is opened, it is created with a 1K buffer.
Any following creation on modules side resizes it without any loss of data.
Again if you want to create a fifo from the user side with a desired buffer
size you can use: 
	- rtf_open_sized(const char *dev, perm, size).

Semaphore interface
-------------------

Since they had to be there already to implement our mailboxes we have made 
available also binary semaphores. They can be used for many things, e.g. to 
sinchronize shared memory access without any scheduler installed and in place of
using blocking fifos read/writes with dummy data, just to synchronize.
The semaphore services available are:
	- rtf_sem_init(fd, init_val);
	- rtf_sem_wait(fd);
	- rtf_sem_trywait(fd);
	- rtf_sem_timed_wait(fd, ms_delay);
	- rtf_sem_post(fd);
	- rtf_sem_destroy(fd);
Note that fd is the file descriptor, a semaphore is always associated to a fifo
and you must get a file descriptor by opening the corresponding fifo.

Naturally the above functions are symmetrically available in kernel space but, 
except for init and create, only for the nonblocking services, i.e: trywait and
post.

Named fifos
-----------

To make it easier to keep track of which fifo to use and in order to avoid 
fifo number clashes beween separate real time tasks, it is now possible to 
dynamically create named fifos on an unused fifo number. Existing named fifos 
can have their name looked up in order to find which fifo number they occupy.
The named fifo services available are:
	- rtf_create_named(name);
	- rtf_getfifobyname(name);

The above functions are symmetrically available in kernel and user space. Both
return the allocated fifo number. In user space please note that these calls 
will not automatically open the fifo device for you. Instead you must append 
the returned fifo number onto the end of '/dev/rtf' and then open the fifo 
device as normal.

The maximum length of a fifo's name is defined as RTF_NAMELEN. This is 
currently set to 15.

When using rtf_create_named() from user space you may notice that the first
fifo created is assigned a fifo number of 1 rather than 0. This is because
/dev/rtf0 is used to communicate with the kernel driver module (where the name
to number mapping is kept), and so at the time of calling fifo number 0 is not
free. This should not cause any problems. The same thing does not happen when
rtf_create_named() is called from kernel space.

If you want to monitor the fifo name to number mapping you have two choices.
Either look in /proc/rtai/fifos or use the new RTF_GET_FIFO_INFO ioctl. Take
a look in the test program regression.c and rtai_fifos.h to see a (slightly
contrived) example of using this ioctl.

Printk
------

Among the new added services there is the porting of David Schleef
([e-mail]) rt_printk( const char *fmt, ...), that allows you to safely
use printk like messages in RTAI modules. It is complemented by 
rt_print_to_screen( const char *fmt, ...), to be used if you do not need to 
log messages. See rtai_fifos.h for the calling prototypes.    

Summary
-------

A final, important, warning. All the new services have been tested in relation
to their basic working, while the standard RTL calls worked well on all the
examples they worked before. Thus you will not miss anything with respect to 
either RTL fifos or the previous adaptation of RTAI to them. We hope in some 
help in thorougly verifying all the remaining new stuff.

To stay on the safe side we default the installation to newfifos but keep old
fifos available. See README in newfifos and oldfifos directories.

Note that this directory contains an examples that shows the use of select,
timed reads and semaphores.

To use it:
insmod task  // for a real time task, a copy of the latency calibration task;
./check      // to see the interaction;
check ends by itself. See the macros on top of check.c to change the execution
parameters.