                    Real-Time features in Linux


This file covers RT-Linux version 1.3.32.0.
This is alpha software. All bugs reports will be appreciated.


                         Overview

This variant of Linux allows to handle time-critical tasks.
This is accomplished mainly by insertion of Real-Time Kernel layer between Linux
kernel and hardware interrupts. This eliminates the main source of Linux unsuitability
for time-critical processing - big interrupt latency.

Under RT-kernel Linux kernel is just another real-time task.
It has the lowest priority, and can be preempted when needed. 

This structure imposes some restrictions on RT-tasks. They can not
easily use Linux drivers, networking, etc.
They can, however, transfer data to/from ordinary
Linux processes through memory buffers.

Simple FIFOs are implemented for transferring
data between real-time processes and Linux processes.

A typical application consists of real-time tasks that deal with hardware directly,
e.g. acquire data from a device, and Linux tasks performing non-real-time processing,
such as recording data on disk, sending it over network, etc.

The shortest feasible period for a real-time task under RT-Linux is about 150 us
on Pentium 120.

(!) The RT-kernel does not protect from overloads (not yet). 
It is conceivable that real-time tasks can consume all CPU power. In this case, 
having the lowest priority, Linux kernel will never get a chance to run, and the 
system will freeze.

RT-processes execute at the kernel privilege level. All ports and all physical
memory are accessible.


                                   API

This section describes C interface for programming real-time applications.
All paths are relative to the main RT-Linux directory.

Library rtlinux/librtlinux.a contains functions for loading RT-processes into
memory, creating RT-FIFOs, and information exchange.
These functions are used in Linux processes only.
Include file include/linux/rtlinux.h contains prototypes of these functions.

extern int RTload( const char *file);
    loads a RT-program "file", creates a process and returns its pid.
    the process is suspended until RTrun is called.

extern int RTrun( int pid);
    starts execution of the RT-process at a low priority level; 
    the process must be first loaded with
    RTload routine

extern int RTkill( int pid);
    kills a RT-process

extern int RTget_time( RTime *t);
    returns current time; time is a 64 bit integer (long long int), 
    containing number of clock ticks passed since system booted
    The constant  RT_TICKS_PER_SEC contains the number of clocks per second
    (defined in include/asm/rttime.h)

extern int RTfifo_create( unsigned int fifo, int size);
    creates a FIFO number "fifo" of size "size" bytes.
    FIFOs' numbers are global; FIFOs are numbered from 0 to RT_MAX_FIFO-1.
    Applications must agree on the use of the FIFOs available.

extern int RTfifo_destroy( unsigned int fifo);
    destroy a FIFO

extern int RTfifo_read( unsigned int fifo, char * buf, int count);
    read "count" bytes from a FIFO; if the FIFO is empty, wait until data is available
    write bytes to "buf"

extern int RTfifo_get( unsigned int fifo, char * buf, int count);
    the same as RTfifo_read, but doesn't wait; return -1 if there's
    not enough data in the FIFO; otherwise return "count"

extern int RTfifo_write( unsigned int fifo, char * buf, int count);
    write to the FIFO; if the FIFO is full, wait until the space is available

extern int RTfifo_put( unsigned int fifo, char * buf, int count);
    the same, but doesn't wait



The file include/linux/rt.h contains declarations of functions that are used
in RT-programs.

int RTputs(char *s);
    prints string "s" on console. Using printk instead is not recommended.

int RTgetpid();
    returns the pid of the process. RT-processes' pids do not have anything to
    do with Linux pids.

int RTrun(int pid);
    starts execution of the RT-process (at a low priority level); 
    the process must be first loaded with
    RTload system call (see description of include/linux/rtlinux.h above).

int RTset_params(RTime * start, RTime * period, int priority);
    changes scheduling parameters of the process

int RTwait_start(RTime * start, RTime * period, int priority);
    suspends the process until its start time; when start time comes, set
    the priority of the process to the requested value.

int RTwait_period();
    suspend the execution of the process until the beginning of the next period.

int RTkill(int pid);
    kill a process

int RTfifo_put(unsigned int fifo, char * buf, int count);
    put "count" bytes from buffer "buf" into fifo "fifo".
    On success, count is returned. If the buffer is full, negative value is returned.

int RTfifo_get(unsigned int fifo, char * buf, int count);
    get bytes from the buffer.


(!) RT-processes must be linked with file rt/head.o   . See the Makefile in
the testrt/ directory.

(!) Never try to run real-time tasks not being a superuser. This can cause the system
to crash. This bug will soon be fixed.


                          Examples

Examples can be found in testrt/ directory.


Michael Barabanov
baraban@nmt.edu
