NAME

rtf_create - create a real-time FIFO

SYNOPSIS

#include "rtai_fifos.h"

int rtf_create (unsigned int fifo, int size);

DESCRIPTION

rtf_create creates a real-time fifo (RT-FIFO) of initial size size and assigns it the identifier fifo.
fifo is a small postive integer what identifies the fifo on further operations. It have to be less than RTF_NO.
fifo may refer an existing RT-FIFO. In this case the size is adjusted if necessary.

The RT-FIFO is a mechanism, implemented as a character device, to communicate between 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.

RETURN VALUE

On success, size is returned. On failure, a negative value is returned.

ERRORS

-ENODEV

fifo is greater than or equal to RTF_NO.

-ENOMEM

size bytes could not be allocated for the RT-FIFO.

BUGS

If resizing was unsuccesful, no error code is returned.

[return to index]

NAME

rtf_destroy - close a real-time FIFO

SYNOPSIS

#include "rtai_fifos.h"

int rtf_destroy (unsigned int fifo);

DESCRIPTION

rtf_destroy closes a real-time fifo previously created/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.

RETURN VALUE

On success, a non-negative number is returned. Actually it is the open counter, that means how many times rtf_destroy should be called yet to destroy the fifo. On failure, a negative value is returned.

ERRORS

-ENODEV

fifo is greater than or equal to RTF_NO.

-EINVAL

fifo refers to not an open fifo.

[return to index]

NAME

rtf_reset - reset a real-time FIFO

SYNOPSIS

#include "rtai_fifos.h"

int rtf_reset (unsigned int fifo);

DESCRIPTION

rtf_reset resets RT-FIFO fifo by setting its buffer pointers to zero, so that any existing data is discarded and the fifo started anew like at its creations.

RETURN VALUE

On success, 0 is returned. On failure, a negative value is returned.

ERRORS

-ENODEV

fifo is greater than or equal to RTF_NO.

-EINVAL

fifo refers to not an open fifo.

-EFAULT

Operation was unsuccesful.

[return to index]

NAME

rtf_resize - resize a real-time FIFO

SYNOPSIS

#include "rtai_fifos.h"

int rtf_resize (unsigned int fifo, int size);

DESCRIPTION

rtf_resize modifies the real-time fifo fifo, previously created with , rtf_create, to have a new size of size. Any data in the fifo is discarded.

RETURN VALUE

On success, size is returned. On failure, a negative value is returned.

ERRORS

-ENODEV

fifo is greater than or equal to RTF_NO.

-EINVAL

fifo refers to not an open fifo.

-ENOMEM

size bytes could not be allocated for the RT-FIFO. Fifo size is unchanged.

[return to index]

NAME

rtf_put - write data to FIFO

SYNOPSIS

#include "rtai_fifos.h"

int rtf_put (unsigned int fifo, void *buf, int count);

DESCRIPTION

rtf_put tries to write a block of data to a real-time fifo previously created with rtf_create.
fifo is the ID with which the RT-FIFO was created.
buf points the block of data to be written.
count is the size of the block in bytes.
This mechanism is available only to real-time tasks; Linux processes use a write to the corresponding /dev/fifo<n> device to enqueue data to a fifo. Similarly, Linux processes use read or similar functions to read the data previously written via rtf_put by a real-time task.

RETURN VALUE

On success, the number of bytes written is returned. Note that this value may be less than count if count bytes of free space is not available in the fifo. On failure, a negative value is returned.

ERRORS

-ENODEV

fifo is greater than or equal to RTF_NO.

-EINVAL

fifo refers to not an open fifo.

[return to index]

NAME

rtf_get - read data from FIFO

SYNOPSIS

#include "rtai_fifos.h"

int rtf_get (unsigned int fifo, void *buf, int count);

DESCRIPTION

rtf_get tries to read a block of data from a real-time fifo previously created with a call to rtf_create.
fifo is the ID with which the RT-FIFO was created.
buf points a buffer of count bytes size provided by the caller. 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.

RETURN VALUE

On success, the size of the received data block is returned. Note that this value may be less than count if count bytes of data is not available in the fifo. On failure, a negative value is returned.

ERRORS

-ENODEV

fifo is greater than or equal to RTF_NO.

-EINVAL

fifo refers to not an open fifo.

[return to index]

NAME

rtf_create_handler - install a FIFO handler function

SYNOPSIS

#include "rtai_fifos.h"

int rtf_create_handler (unsigned int fifo, int (*handler)(unsigned int fifo));

DESCRIPTION

rtf_create_handler installs a handler which is executed when data is written to or read from a real-time fifo.
fifo is an RT-FIFO that must have previously been created with a call to rtf_create.
The function pointed by handler is called whenever a Linux process accesses that fifo.

rtf_create_handler is often used in conjunction with rtf_get to process data acquired asynchronously from a Linux process. The installed handler calls rtf_get when data is present. Because the handler is only executed when there is activity on the fifo, polling is not necessary.

RETURN VALUE

On success, 0 is returned. On failure, a negative value is returned.

ERRORS

-EINVAL

fifo is greater than or equal to RTF_NO, or handler is NULL.

BUGS

rtf_create_handler does not check if FIFO referred by fifo is open or not. The next call of rtf_create will uninstall the handler just "installed".

[return to index]