extern int rtf_create
(unsigned int fifo, int size);
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
Creates a real-time fifo (RT-FIFO) of initial size size
and assigns it the identifier fifo.
fifo is a value unique within the system, and
must be less than RTF_NO.
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.
-EBUSY: fifo is already in use. Choose a different
ID.
-ENOMEM: size bytes could not be allocated for
the RT-FIFO.
extern int rtf_create_using_bh
(unsigned int fifo, int size, task_queue
*bh_list);
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
Creates an RT-FIFO using a bottom half queue. A real-time
fifo is created with initial size of size.
The fifo uses a bh_list to queue waiting Linux
processes up. Any of the task queues managed by the kernel can be used,
however the most useful ones in real time applications should be:
tq_timer that is used to queue work that will
be done as soon after the next system clock tick as is possible. At each
clock tick, this queue is checked to see if it contains any entry and,
if it does, the timer queue bottom half handler is made active . It needs
not to be marked to be run.
tq_immediate that is also processed when the scheduler
processes the active bottom half handler. The immediate bottom half handler
is not as high in priority as the timer queue bottom half handler and so
these tasks will be run later.
tq_scheduler that is processed directly by the
scheduler. It is used to support other task queues in the system and, in
this case, the task to be run will be a routine that processes a task queue,
say for a device driver.
If bh_list is equal to zero an immediate wake
up is adopted.
FIFOs created by using rtf_create defaults
to tq_immediate.
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.
-EBUSY: fifo is already in use. Choose a different
ID.
-ENOMEM: size bytes could not be allocated for
the RT-FIFO.
extern int
rtf_create_using_bh_and_usr_buf
(unsigned int fifo, char *buf,
int size, task_queue *bh_list);
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
Creates an RT-FIFO using a bottom half queue and a buffer
buf of size size assigned by the user. In this way the user
can statically assign a buffer of any appropriate size without the limit
size imposed by the use of kmalloc, as done in rtf_create.
The fifo uses bh_list to queue waiting Linux processes
(see rtf_create_using_bh).
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.
-EBUSY: fifo is already in use. Choose a different
ID.
extern int rtf_destroy
(unsigned int fifo);
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
Removes a real-time fifo (RT-FIFO) previously created with
rtf_create.
fifo is then available for reuse by another call
to rtf_create.
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 is not a valid RT-FIFO identifier.
extern int rtf_destroy_using_usr_buf
(unsigned int fifo);
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
Removes a real-time fifo (RT-FIFO) previously created with
rtf_create_using_bh or rtf_create_using_bh_and_usr_buf.
fifo is then available for reuse by another call
to rtf_create.
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 is not a valid RT-FIFO identifier.
extern void rtf_reset
(unsigned int fifo);
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
An RT-FIFO fifo is reset 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
None
ERRORS
"BUGS" Any data present in the RT-FIFO when rtf_reset is
executed is lost.
extern int rtf_resize
(unsigned int fifo, int size);
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
Modifies the real-time fifo (RT-FIFO) fifo, previously
created with , rtf_create, to have a new size
of size.
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" Any data present in the RT-FIFO when rtf_resize
is executed is lost.
extern int rtf_put
(unsigned int fifo, void *buf,
int count);
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
Writes a block of data to a real-time fifo (RT-FIFO) previously
created with a call to rtf_create.
fifo is the ID with which the RT-FIFO was created.
buf is the block of data to be written, while
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 fifo 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, count is returned. On failure, a negative
value is returned .
ERRORS
-ENODEV: fifo is greater than or equal to RTF_NO.
-EINVAL: fifo is not a valid RT-FIFO identifier.
-ENOSPC: insufficient space is available in the RT-FIFO
for count bytes.
extern int rtf_get
(unsigned int fifo, void *buf,
int count);
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
Reads a block of data from a real-time fifo (RT-FIFO) previously
created with a call to rtf_create.
fifo is the ID with which the RT-FIFO was created.
buf is the block of data to be filled with the
received bytes, while count is the size of the block 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.
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
are 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 is not a valid RT-FIFO identifier.
extern int rtf_create_handler
(unsigned int fifo, int (*handler)(unsigned
int fifo));
SYNOPSIS
#include "rtl_fifo.h"
DESCRIPTION
Installs a handler which is executed when data is written
to or read from a real-time fifo (RT-FIFO).
fifo is an RT-FIFO that must have previously been
created with a call to rtf_create.
handler is then 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 is not a valid RT-FIFO identifier, or handler is NULL.