rtai-core/ipc/fifos/fifos.c File Reference


Detailed Description

Implementation of the RTAI FIFO module.

Author:
Paolo Mantegazza
Note:
Copyright © 1999-2003 Paolo Mantegazza <mantegazza@aero.polimi.it>
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Include dependency graph for fifos.c:

Include dependency graph

Functions

int rtf_reset (unsigned int minor)
int rtf_resize (unsigned int minor, int size)
int rtf_create (unsigned int minor, int size)
int rtf_destroy (unsigned int minor)
int rtf_create_handler (unsigned int minor, int(*handler)(unsigned int fifo))
int rtf_put (unsigned int minor, void *buf, int count)
int rtf_get (unsigned int minor, void *buf, int count)
int rtf_sem_init (unsigned int minor, int value)
int rtf_sem_post (unsigned int minor)
int rtf_sem_trywait (unsigned int minor)
int rtf_sem_destroy (unsigned int minor)

Function Documentation

int rtf_create unsigned int  minor,
int  size
 

Create a real-time FIFO

rtf_create creates a real-time fifo (RT-FIFO) of initial size size and assigns it the identifier fifo. It must be used only in kernel space.

Parameters:
minor is a positive integer that identifies the fifo on further operations. It has to be less than RTF_NO.
size is the requested size for the fifo.
fifo may refer to an existing RT-FIFO. In this case the size is adjusted if necessary.

The RT-FIFO is a character based mechanism to communicate among real-time tasks and ordinary Linux processes. The rtf_* functions are used by the real-time tasks; Linux processes use standard character device access functions such as read, write, and select.

If this function finds an existing fifo of lower size it resizes it to the larger new size. Note that the same condition apply to the standard Linux device open, except that when it does not find any already existing fifo it creates it with a default size of 1K bytes.

It must be remarked that practically any fifo size can be asked for. In fact if size is within the constraint allowed by kmalloc such a function is used, otherwise vmalloc is called, thus allowing any size that can fit into the available core memory.

Multiple calls of this function are allowed, a counter is kept internally to track their number, and avoid destroying/closing a fifo that is still used.

Return values:
size on success
ENODEV if fifo is greater than or equal to RTF_NO
ENOMEM if the necessary size could not be allocated for the RT-FIFO.

int rtf_destroy unsigned int  minor  ) 
 

Close a real-time FIFO

rtf_destroy closes, in kernel space, a real-time fifo previously created or reopened with rtf_create() or rtf_open_sized(). An internal mechanism counts how many times a fifo was opened. Opens and closes must be in pair. rtf_destroy should be called as many times as rtf_create was. After the last close the fifo is really destroyed.

No need for any particular function for the same service in user space, simply use the standard Unix close.

Returns:
a non-negative value on success. Actually it is the open counter, that means how many times rtf_destroy should be called yet to destroy the fifo.

a a negative value is returned as described below.

Return values:
ENODEV if fifo is greater than or equal to RTF_NO.
EINVAL if fifo refers to a not opened fifo.
Note:
The equivalent of rtf_destroy in user space is the standard UNIX close.

int rtf_get unsigned int  minor,
void *  buf,
int  count
 

Read data from FIFO

rtf_get tries to read a block of data from a real-time fifo previously created with a call to rtf_create().

Parameters:
minor is the ID with which the RT-FIFO was created.
buf points a buffer provided by the caller.
count is the size of buf in bytes.
This mechanism is available only to real-time tasks; Linux processes use a read from the corresponding fifo device to dequeue data from a fifo. Similarly, Linux processes use write or similar functions to write the data to be read via rtf_put() by a real-time task.

rtf_get is often used in conjunction with rtf_create_handler() to process data received asynchronously from a Linux process. A handler is installed via rtf_create_handler(); this handler calls rtf_get to receive any data present in the RT-FIFO as it becomes available. In this way, polling is not necessary; the handler is called only when data is present in the fifo.

Returns:
the size of the received data block on success. Note that this value may be less than count if count bytes of data is not available in the fifo.
Return values:
ENODEV if fifo is greater than or equal to RTF_NO.
EINVAL if fifo refers to a not opened fifo.
Note:
The equivalent of rtf_get in user space is the standard UNIX read, which can be either blocking or nonblocking according to how you opened the related device.


Generated on Sat Jul 24 19:36:13 2004 for RTAI API by doxygen 1.3.4