File: GettingStarted.html

package info (click to toggle)
rtlinux 3.1pre3-2
links: PTS
area: non-free
in suites: sarge, woody
size: 4,892 kB
ctags: 4,228
sloc: ansic: 26,204; sh: 2,069; makefile: 1,414; perl: 855; tcl: 489; asm: 380; cpp: 42
file content (3371 lines) | stat: -rw-r--r-- 81,652 bytes
parent folder | download | duplicates (4)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<!--Converted with LaTeX2HTML 2K.1beta (1.48)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Getting Started with RTLinux</TITLE>
<META NAME="description" CONTENT="Getting Started with RTLinux">
<META NAME="keywords" CONTENT="GettingStarted">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="LaTeX2HTML v2K.1beta">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="GettingStarted.css">

</HEAD>

<BODY bgcolor="white">
<!--Navigation Panel-->
<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
 SRC="/usr/share/latex2html/icons/nx_grp_g.png"> 
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="/usr/share/latex2html/icons/up_g.png"> 
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="/usr/share/latex2html/icons/prev_g.png">   
<BR>
<BR>
<BR>
<!--End of Navigation Panel-->

<P>

<H1 ALIGN="CENTER">Getting Started with RTLinux</H1>
<P ALIGN="CENTER"><STRONG>FSM Labs, Inc.</STRONG></P>
<BR>

<H2><A NAME="SECTION00100000000000000000">
Contents</A>
</H2>
<!--Table of Contents-->

<UL>
<LI><A NAME="tex2html233"
  HREF="GettingStarted.html">Introduction</A>
<UL>
<LI><A NAME="tex2html234"
  HREF="#SECTION00210000000000000000">Sources of Help</A>
<LI><A NAME="tex2html235"
  HREF="#SECTION00220000000000000000">Before You Begin: A Warning</A>
<LI><A NAME="tex2html236"
  HREF="#SECTION00230000000000000000">RTLinux Overview</A>
</UL>
<BR>
<LI><A NAME="tex2html237"
  HREF="#SECTION00300000000000000000">The Basic API</A>
<UL>
<LI><A NAME="tex2html238"
  HREF="#SECTION00310000000000000000">Understanding an RTLinux Program</A>
<LI><A NAME="tex2html239"
  HREF="#SECTION00320000000000000000">The Basic API</A>
<UL>
<LI><A NAME="tex2html240"
  HREF="#SECTION00321000000000000000">Creating RTLinux POSIX Threads</A>
<LI><A NAME="tex2html241"
  HREF="#SECTION00322000000000000000">Time Facilities</A>
<LI><A NAME="tex2html242"
  HREF="#SECTION00323000000000000000">Conversion Routines</A>
<LI><A NAME="tex2html243"
  HREF="#SECTION00324000000000000000">Scheduling Threads</A>
</UL>
<LI><A NAME="tex2html244"
  HREF="#SECTION00330000000000000000">A Simpl ``Hello World'' RTLinux program</A>
<UL>
<LI><A NAME="tex2html245"
  HREF="#SECTION00331000000000000000">Code Listing</A>
<LI><A NAME="tex2html246"
  HREF="#SECTION00332000000000000000">Dissecting ``Hello World''</A>
<LI><A NAME="tex2html247"
  HREF="#SECTION00333000000000000000">Compiling and Executing ``Hello World''</A>
</UL>
</UL>
<BR>
<LI><A NAME="tex2html248"
  HREF="#SECTION00400000000000000000">The Advanced API</A>
<UL>
<LI><A NAME="tex2html249"
  HREF="#SECTION00410000000000000000">Using Floating Point Operations in RTLinux POSIX Threads</A>
<LI><A NAME="tex2html250"
  HREF="#SECTION00420000000000000000">RTLinux IPC</A>
<UL>
<LI><A NAME="tex2html251"
  HREF="#SECTION00421000000000000000">Using Real-Time FIFOs</A>
<LI><A NAME="tex2html252"
  HREF="#SECTION00422000000000000000">Using Shared Memory</A>
<LI><A NAME="tex2html253"
  HREF="#SECTION00423000000000000000">Waking and Suspending RTLinux Threads</A>
<LI><A NAME="tex2html254"
  HREF="#SECTION00424000000000000000">Mutual Exclusion</A>
</UL>
<LI><A NAME="tex2html255"
  HREF="#SECTION00430000000000000000">Accessing Memory</A>
<LI><A NAME="tex2html256"
  HREF="#SECTION00440000000000000000">Interrupts</A>
<UL>
<LI><A NAME="tex2html257"
  HREF="#SECTION00441000000000000000">Hard Interrupts</A>
<LI><A NAME="tex2html258"
  HREF="#SECTION00442000000000000000">Soft interrupts</A>
</UL>
</UL>
<BR>
<LI><A NAME="tex2html259"
  HREF="#SECTION00500000000000000000">Special Topics</A>
<UL>
<LI><A NAME="tex2html260"
  HREF="#SECTION00510000000000000000">Symmetric Multi-Processing Considerations</A>
<LI><A NAME="tex2html261"
  HREF="#SECTION00520000000000000000">RTLinux Serial Driver (<TT>rt_com</TT>)</A>
<LI><A NAME="tex2html262"
  HREF="#SECTION00530000000000000000">Interfacing RTLinux Components to Linux</A>
<LI><A NAME="tex2html263"
  HREF="#SECTION00540000000000000000">Writing RTLinux Schedulers</A>
</UL>
<BR>
<LI><A NAME="tex2html264"
  HREF="#SECTION00600000000000000000">Running RTLinux Programs</A>
<UL>
<LI><A NAME="tex2html265"
  HREF="#SECTION00610000000000000000">General</A>
<LI><A NAME="tex2html266"
  HREF="#SECTION00620000000000000000">Examples</A>
<UL>
<LI><A NAME="tex2html267"
  HREF="#SECTION00621000000000000000">Using <TT>rtlinux</TT></A>
<LI><A NAME="tex2html268"
  HREF="#SECTION00622000000000000000">Using <TT>modprobe</TT></A>
<LI><A NAME="tex2html269"
  HREF="#SECTION00623000000000000000">Using <TT>insmod</TT> and <TT>rmmod</TT></A>
</UL>
</UL>
<BR>
<LI><A NAME="tex2html270"
  HREF="#SECTION00700000000000000000">RTLinux API Reference</A>
<UL>
<LI><A NAME="tex2html271"
  HREF="#SECTION00710000000000000000">Getting Around</A>
<LI><A NAME="tex2html272"
  HREF="#SECTION00720000000000000000">Scripts and Utilities</A>
<LI><A NAME="tex2html273"
  HREF="#SECTION00730000000000000000">Core RTLinux API</A>
<LI><A NAME="tex2html274"
  HREF="#SECTION00740000000000000000">Version 1.x API: Not for New Projects</A>
</UL>
<BR>
<LI><A NAME="tex2html275"
  HREF="#SECTION00800000000000000000">About this document ...</A>
</UL>
<!--End of Table of Contents-->
<P>

<H1><A NAME="SECTION00200000000000000000"></A><A NAME="introduction"></A>
<BR>
Introduction
</H1>

<P>
Welcome to the RTLinux Getting Started Guide! RTLinux is a hard realtime operating system that coexists with the Linux OS. With RTLinux, it is possible to create realtime POSIX.1b threads that will run at precisely specified moments of time. We have designed the Getting Started Guide with the assumption that the reader has had some programming experience, but has never used RTLinux.

<P>
The document is organized as follows. First, we present basic
information needed to get started: sources of help, common programming
errors, and an overview of the RTLinux design (Chapter
<A HREF="GettingStarted.html#introduction">1</A>). Next, we present the basic RTLinux API and will
step you through your first ``Hello World'' program (Chapter
<A HREF="GettingStarted.html#hello_world">2</A>). Third, we offer some of the more advanced API
(Chapter <A HREF="GettingStarted.html#advanced_api">3</A>), after which you'll find some special
considerations and concepts (Chapter&nbsp;<A HREF="GettingStarted.html#special_topics">4</A>). Finally,
in the appendices, you find some different ways of running RTLinux
programs (Appendix&nbsp;<A HREF="GettingStarted.html#running_rtlinux_progs">A</A>) and, most importantly,
a complete listing of the RTLinux API, utilities, and important paths
(Appendix&nbsp;<A HREF="GettingStarted.html#rtlinux_api">B</A>).

<P>

<H1><A NAME="SECTION00210000000000000000">
Sources of Help</A>
</H1>

<P>
The RTLinux white paper in <TT>doc/design.pdf</TT> explains the basic
architecture in more detail and a summary of the design is presented
in Section&nbsp;<A HREF="GettingStarted.html#rtlinux_overview">1.3</A>. As you progress in your use of
RTLinux, you'll find yourself wanting more information. Fortunately,
there are many sources of help. For the most up-to-date information,
see the 
	
		<A NAME="tex2html5"
  HREF="http://www.fsmlabs.com/">http://www.fsmlabs.com</A>

,

		<A NAME="tex2html6"
  HREF="http://www.rtlinux.com/">http://www.rtlinux.com</A>

 and

		<A NAME="tex2html7"
  HREF="http://www.rtlinux.org/">http://www.rtlinux.org</A>

 websites.

<P>

<P>
	<BR>
<BR>
	
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>If you are primarily interested in hard realtime control and
not particularly interested in learning how to use RTLinux itself,
take a look at FSM Labs 
	
		<A NAME="tex2html1"
  HREF="../RTiC/rtic.html">RTiC-Lab</A>

 at

		<A NAME="tex2html2"
  HREF="http://rtic-lab.org">www.rtic-lab.org</A>

. RTiC-Lab is a front
end to RTLinux that greatly simplifies hard realtime control
implementation, monitoring and tuning. 
	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
	
<P>
	<BR>
<BR>

<P>

<P>
	<BR>
<BR>
	
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>If you are interested in running RTLinux on an industry
standard PC-104 board or other type of minimal or embedded system, see
FSMLabs 
	
		<A NAME="tex2html3"
  HREF="../minirtl.html">MiniRTL project</A>

, found at

		<A NAME="tex2html4"
  HREF="http://www.rtlinux.org/minirtl.html">www.rtlinux.org/minirtl.html</A>

MiniRTL fits on a signle floppy disk and provides full RTLinux
capabilities.
	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
	
<P>
	<BR>
<BR>

<P>
Some other documents you may find useful are (Note: All references to
directories and files assume that RTLinux has been installed in its
default location <TT>/usr/rtlinux</TT>).:

<P>

<UL>
<LI>The RTLinux Manual Project, available at

		<A NAME="tex2html8"
  HREF="http://www.rtlinux.org/documents/documentation/RTLManual/RTLManual.html#toc1">-www.rtlinux.org/documents/documentation/RTLManual/RTLManual.html</A>

<P>
</LI>
<LI>The Single UNIX specification, available at

		<A NAME="tex2html9"
  HREF="http://www.opengroup.org/onlinepubs/7908799/index.html">www.opengroup.org/onlinepubs/7908799/index.html</A>

.
(The Single UNIX spec is also installed in HTML format with the
RTLinux distribution. (<TT>susv2/index.html</TT>)

<P>
</LI>
<LI>The LinuxThreads library documentation at

		<A NAME="tex2html10"
  HREF="http://pauillac.inria.fr/~xleroy/linuxthreads">http://pauillac.inria.fr/~xleroy/linuxthreads</A>

(included with
glibc2). You can try running:

<P><PRE>
man 3 pthread_create
</PRE>

<P>
to see if it is installed on your system.

<P>
</LI>
<LI>``Getting Started With POSIX Threads'' (by Thomas Wagner and Don
Towsley), available at

		<A NAME="tex2html11"
  HREF="http://centaurus.cs.umass.edu/~wagner/threads_html/tutorial.html">centaurus.cs.umass.edu/~wagner/threads_html/tutorial.html</A>

.

<P>
</LI>
<LI>``Pthreads Programming'', available at

		<A NAME="tex2html12"
  HREF="http://www.oreilly.com/catalog/pthread">www.oreilly.com/catalog/pthread</A>

by Bradford Nichols,
Dick Buttlar, and Jacqueline Proulx Farrell.

<P>
</LI>
<LI>Other documents or books describing POSIX threads.
</LI>
</UL>

<P>
The RTLinux distribution itself contains documentation to help you
along in your RTLinux projects:

<P>

<UL>
<LI>The <TT>man</TT> directory contains UNIX manual pages describing
features and commands specific to RTLinux. You can modify the
MANPATH environment variable so that these manual pages can be found
with the man command.  (Type <TT>man man</TT> for instructions on how to
change the MANPATH variable globally.)

<P>
</LI>
<LI>The 
	
		<A NAME="tex2html13"
  HREF="../MAN"><TT>html/MAN</TT></A>

 directory contains the same manual
pages, converted to HTML.

<P>
</LI>
<LI>The 
	
		<A NAME="tex2html14"
  HREF="../FAQ/FAQ.html">RTLinux Frequently Asked Questions
(FAQ)</A>

 file can be found under the top level directory of the RTLinux source
tree.

<P>
</LI>
<LI>The <TT>examples</TT> directory contains programs which will
give you firsthand experience with the RTLinux API.

<P>
</LI>
</UL>

<P>
If, after attempting all of the above, you still have questions, there
is another rich source of information via the RTLinux mailing
lists. You can subscribe/unsubscribe to these lists at

		<A NAME="tex2html15"
  HREF="http://www.rtlinux.org/mailing_lists.html">www.rtlinux.org/mailing_lists.html</A>

.
Of course, you may not be the first person with your question. To ease
your search for answers, the lists are both browseable and searchable.

<P>

<H1><A NAME="SECTION00220000000000000000">
Before You Begin: A Warning</A>
</H1>

<P>
Realtime programs in RTLinux are executed in kernel space and
have little or no protection against bugs in the user's code. Special
care must be taken when programming realtime tasks because
programming errors may bring the system down.

<P>
RTLinux supplies a debugger within its source tree under the directory
<TT>debugger</TT>. <EM>Use of the debugger is strongly recommended to reduce
the risk of system crashes.</EM>

<P>
Note also that by default RTLinux tasks do not have access to the
computer's Floating Point Unit (FPU). You must explicitly set
permissions for each of your RTLinux tasks that require the use of the
FPU.

<P>

<H1><A NAME="SECTION00230000000000000000"></A><A NAME="rtlinux_overview"></A>
<BR>
RTLinux Overview
</H1>

<P>
This section is intended to give users a top-level understanding of
RTLinux. It is not designed as an in-depth
technical discussion of the system's architecture. Readers interested in the topic can start with Michael Barabanov's Master's Thesis. (A postscript version is
available for download at

		<A NAME="tex2html18"
  HREF="http://www.rtlinux.org/documents/papers/thesis.ps">www.rtlinux.org/documents/papers/thesis.ps</A>

).

<P>
The basic premise underlying the design of RTLinux is that it is not
feasible to identify and eliminate all aspects of kernel operation
that lead to unpredictability. These sources of unpredictability
include the Linux scheduling algorithm (which is optimized to maximize
throughput), device drivers, uninterrruptible system calls, the use of
interrupt disabling and virtual memory operations. The best way to avoid these problems
is to construct a small, predictable kernel separate from the Linux
kernel, and to make it simple enough that operations can be measured
and shown to have predictable execution. This has been the course taken by the developers of RTLinux. This approach has the added benefit of maintainability - prior to the development of
RTLinux, every time new device drivers or other enhancements to Linux
were needed, a study would have to be performed to determine that the
change would not introduce unpredictability.

<P>
Figure&nbsp;<A HREF="GettingStarted.html#linux">1.1</A> shows the basic Linux kernel without hard realtime
support. You will see that the Linux kernel separates the
hardware from user-level tasks. The kernel has the ability to
suspend any user-level task, once that task has outrun the ``slice of
time'' allotted to it by the CPU. Assume, for example, that a user
task controls a robotic arm. The standard Linux kernel could potentially preempt
the task and give the CPU to one which is less critical (e.g. one
that boots up Netscape). Consequently, the arm will not meet strict
timing requirements. Thus, in trying to be ``fair'' to all tasks, the kernel
can prevent critical events from occurring.

<P>
Figure&nbsp;<A HREF="GettingStarted.html#rtlinux">1.2</A> shows a Linux kernel modified to support
hard realtime. An additional layer of abstraction - termed a ``virtual
machine'' in the literature - has been added between the standard Linux
kernel and the computer hardware. As far as the standard Linux kernel
is concedrned, this new layer appears to be actual
hardware. More importantly, this new layer introduces
its own fixed-priority scheduler. This scheduler assigns the lowest priority
to the standard Linux kernel, which then runs as an independent task.
Then it allows the user to both introduce and set priorities for any
number of realtime tasks.

<P>

<P></P>
<DIV ALIGN="CENTER"><A NAME="linux"></A><A NAME="938"></A>
<TABLE>
<CAPTION ALIGN="BOTTOM"><STRONG>Figure 1.1:</STRONG>
Detail of the bare Linux kernel</CAPTION>
<TR><TD>
<DIV ALIGN="CENTER">
	
		<IMG
 WIDTH="440" HEIGHT="286" ALIGN="BOTTOM" BORDER="0"
 SRC="img2.png"
 ALT="\includegraphics[width=0.8\textwidth]{components/unix.eps}">

</DIV></TD></TR>
</TABLE>
</DIV><P></P>

<P>

<P></P>
<DIV ALIGN="CENTER"><A NAME="rtlinux"></A><A NAME="939"></A>
<TABLE>
<CAPTION ALIGN="BOTTOM"><STRONG>Figure 1.2:</STRONG>
Detail of the RTLinux kernel</CAPTION>
<TR><TD>
<DIV ALIGN="CENTER">
	
		<IMG
 WIDTH="443" HEIGHT="257" ALIGN="BOTTOM" BORDER="0"
 SRC="img3.png"
 ALT="\includegraphics[width=0.8\textwidth]{components/rt-linux.eps}">

</DIV></TD></TR>
</TABLE>
</DIV><P></P>

<P>
The abstraction layer introduced by RTLinux works by intercepting all 
hardware interrupts.
Hardware interrupts not related to realtime activities are held and 
then passed
to the Linux kernel as software interrupts when the RTLinux kernel is 
idle and the standard Linux
kernel runs. Otherwise, the appropriate realtime interrupt service
routine (ISR) is run. The RTLinux executive is itself nonpreemptible.
Unpredictable delays within the RTLinux executive are eliminated by
its small size and limited operations. Realtime tasks have two special
attributes: they are ``privileged'' (that is, they have direct access to
hardware), and they do not use virtual memory.
Realtime tasks are written as special Linux modules that can be
dynamically loaded into memory. They are are not expected to execute 
Linux system calls.
The initialization code for a
realtime tasks initializes the realtime task structure and informs
RTLinux of its deadline, period, and release-time constraints.
Non-periodic tasks are supported through the use of interrupts.

<P>
In contrast with some other approaches to realtime, RTLinux leaves
the Linux kernel essentially untouched. Via a set of relatively simple 
modifications, it manages
to convert the existing Linux kernel into a hard realtime environment
without hindering future Linux development.

<P>

<H1><A NAME="SECTION00300000000000000000"></A><A NAME="hello_world"></A>
<BR>
The Basic API: Writing RTLinux Modules
</H1>

<P>
This chapter Introduces critical concepts that must be grasped in order
to successfully write RTLinux modules. It also presents
the basic Application Programming Interface (API) used in all RTLinux programs. Then
it steps the user through the creation of a basic ``Hello World''
programming example, which is intended to help the user in developing
their very first RTLinux program.

<P>

<H1><A NAME="SECTION00310000000000000000">
Understanding an RTLinux Program</A>
</H1>

<P>
In the latest versions of RTLinux, programs are not created as standalone
applications. Rather, they are modelled as modules
which are loaded into the Linux kernel space. A Linux module is 
nothing but an object file, usually
created with the <TT>-c</TT> flag argument to <TT>gcc</TT>. The module itself
is created by compiling an ordinary C language file in which the <TT>main ()</TT> function is replaced by a pair of <TT>init/cleanup</TT> functions:

<P><PRE>
int init_module();
void cleanup_module();
</PRE>

<P>
As its name implies, the <TT>init_module ()</TT> function is
called when the module is first loaded into the kernel. It should return
0 on success and a negative value on failure. Similarly, the <TT>cleanup_module</TT> is called when the module is unloaded.

<P>
For example, if we assume that a user has created a C file named
<TT>my_module.c</TT>, the code can be converted into a module by
typing the following:

<P><PRE>
gcc -c {SOME-FLAGS} my_module.c
</PRE>

<P>
This command creates a module file named <TT>my_module.o</TT>, which can now be inserted into the kernel. To insert the module into the kernel, we use the <TT>insmod</TT> command. To remove it, the <TT>rmmod</TT> command is
used.

<P>

<P>
	<BR>
<BR>
	
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>Documentation for both of these commands can be accessed by
typing:
</EM>
<P>
<BLOCKQUOTE><EM><TT>man 8 insmod</TT>, and 
<BR><TT>man 8 rmmod</TT>.
</EM></BLOCKQUOTE>
<P>
<EM>Here, the ``8'' forces the man command to look for the
manual pages associated with system administration. From now on, we
will refer to commands by their name and manual category. Using this
format, these two commands would be referred to as <TT>insmod (8)</TT> and
<TT>rmmod (8)</TT>. 
	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
	
<P>
	<BR>
<BR>

<P>
For further information on running RTLinux programs,
refer to Appendix&nbsp;<A HREF="GettingStarted.html#running_rtlinux_progs">A</A>.

<P>

<H1><A NAME="SECTION00320000000000000000">
The Basic API</A>
</H1>

<P>
Now that we understand the general structure of modules, and how to
load and unload them, we are ready to look at the RTLinux API.

<P>

<H2><A NAME="SECTION00321000000000000000">
Creating RTLinux POSIX Threads</A>
</H2>

<P>
A realtime application is usually composed of several ``threads'' of execution.
Threads are light-weight processes which share a
common address space. Conceptually, Linux kernel control threads are also RTLinux threads (with one for each CPU in the system). In
RTLinux, all threads share the Linux kernel address space.

<P>
To create a new realtime thread, we use the

		<A NAME="tex2html20"
  HREF="../MAN/pthread_create.3.html"><TT>pthread_create(3)</TT></A>

function. This function must only be called from the Linux kernel
thread (i.e., using <TT>init_module()</TT>):

<P><PRE>
#include &lt;pthread.h&gt;
int pthread_create(pthread_t * thread,
                    pthread_attr_t * attr,
                    void *(*start_routine)(void *),
                    void * arg);
</PRE>

<P>
The thread is created using the attributes specified in the ``<TT>attr</TT>'' thread attributes object. If <TT>attr</TT> is <TT>NULL</TT>, default
attributes are used. For more detailed information, refer to the 
POSIX functions:

<P>

<UL>
<LI><TT>pthread_attr_init(3)</TT>,
</LI>
<LI><TT>pthread_attr_setschedparam(3)</TT>, and
</LI>
<LI><TT>pthread_attr_getschedparam(3)</TT>
</LI>
</UL>

<P>
as well as these RTL-specific functions:

<P>

<UL>
<LI>
		<A NAME="tex2html21"
  HREF="../MAN/pthread_attr_getcpu_np.3.html"><TT>pthread_attr_getcpu_np(3)</TT></A>

, and
</LI>
<LI>
		<A NAME="tex2html22"
  HREF="../MAN/pthread_attr_setcpu_np.3.html"><TT>pthread_attr_setcpu_np(3)</TT></A>

</LI>
</UL>

<P>
which are used to get and set general attributes for
the scheduling parameters and the CPUs in which the thread is intended
to run.

<P>
The ID of the newly created thread is stored in the location pointed to by
``<TT>thread</TT>''. The function pointed to by <TT>start_routine</TT> is
taken to be the thread code. It is passed the ``<TT>arg</TT>'' argument.

<P>
To cancel a thread, use the POSIX function:

<P>
<BLOCKQUOTE>
<TT>pthread_cancel(pthread thread);</TT>

</BLOCKQUOTE>

<P>

<P>
	<BR>
<BR>
	
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>You should join the thread in <TT>cleanup_module</TT> with <TT>pthread_join()</TT> for its resources to be deallocated.

	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
	
<P>
	<BR>
<BR>

<P>

<P>
	<BR>
<BR>
	
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>You must make sure the thread is cancelled before calling
<TT>pthread_join()</TT> from <TT>cleanup_module()</TT>. Otherwise, Linux
will hang waiting for the thread to finish. If unsure, use

		<A NAME="tex2html19"
  HREF="../MAN/pthread_delete_np.3.html"><TT>pthread_delete_np(3)</TT></A>

instead of <TT>pthread_cancel()/pthread_join()</TT>. 
	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
	
<P>
	<BR>
<BR>

<P>

<H2><A NAME="SECTION00322000000000000000">
Time Facilities</A>
</H2>

<P>
RTLinux provides several clocks that can be used for timing
functionality, such as as referencing for thread scheduling and
obtaining timestamps. Here is the general timing API:

<P><PRE>
#include &lt;rtl_time.h&gt;

int clock_gettime(clockid_t clock_id, struct timespec *ts);
hrtime_t clock_gethrtime(clockid_t clock);

struct timespec {
   time_t tv_sec; /* seconds */
   long tv_nsec; /* nanoseconds */
};
</PRE>

<P>
To obtain the current clock reading, use the

		<A NAME="tex2html23"
  HREF="../susv2/xsh/clock_gettime.html"><TT>clock_gettime(3)</TT></A>

function where <TT>clock_id</TT> is the clock to be read and <TT>ts</TT> is
a structure which stores the value obtained.

<P>
The <TT>hrtime_t</TT> value is expressed as a single 64-bit number of
nanoseconds. Thus, 
	
		<A NAME="tex2html24"
  HREF="../MAN/clock_gethrtime.3.html"><TT>clock_gethrtime(3)</TT></A>

 is the same as <TT>clock_gettime</TT>, but returns
the time as an <TT>hrtime_t</TT> rather than as a <TT>timespec</TT> structure.

<P>

<H2><A NAME="SECTION00323000000000000000">
Conversion Routines</A>
</H2>
Several routines exist for converting from one form of time
reporting to the other:

<P><PRE>
#include &lt;rtl_time.h&gt;

hrtime_t timespec_to_ns(const struct timespec *ts);
struct timespec timespec_from_ns(hrtime_t t)
const struct timespec * hrt2ts(hrtime_tvalue);
</PRE>

<P>
These are especially useful macros for passing time values into <TT>nanosleep</TT>, <TT>pthread_cond_timedwait</TT> and the like.

<P>
Currently supported clocks are:

<P>

<UL>
<LI>CLOCK_MONOTONIC: This POSIX clock runs at a steady rate, and is
never adjusted or reset.

<P>
</LI>
<LI>CLOCK_REALTIME: This is the standard POSIX realtime
clock. Currently, it is the same as CLOCK_MONOTONIC. It is planned
that in future versions of
RTLinux this clock will give the world time.

<P>
</LI>
<LI>CLOCK_RTL_SCHED: The clock that the scheduler uses for task
scheduling.
</LI>
</UL>

<P>
The following clocks are architecture-dependent. They are not normally
found in user programs.

<P>

<UL>
<LI>CLOCK_8254: Used on non-SMP x86 machines for scheduling.

<P>
</LI>
<LI>CLOCK_APIC: Used on SMP x86 machines.

<P>
</LI>
<LI>CLOCK_APIC: corresponds to the local APIC clock of the
processor that executes <TT>clock_gettime</TT>. You cannot read or set the
APIC clock of other processors.
</LI>
</UL>

<P>

<H2><A NAME="SECTION00324000000000000000">
Scheduling Threads</A>
</H2>

<P>
RTLinux provides scheduling, which allows thread code to 
 run at specific times. RTLinux uses a pure priority-driven
scheduler, in which the highest priority (ready) thread is
always chosen to run. If two threads have the same priority, which one
is chosen is undefined. RTLinux uses the following scheduling API:

<P><PRE>
int pthread_setschedparam(pthread_t thread,
                           int policy,
                           const struct sched_param *param);
int pthread_make_periodic_np(pthread_t thread,
                              const struct itimerspec *its);
int pthread_wait_np(void);
int sched_get_priority_max(int policy);
int sched_get_priority_min(int policy);

struct itimerspec {
   struct timespec it_interval; /* timer period */
   struct timespec it_value;    /* timer expiration */
};
</PRE>

<P>
Thread priority can be modified at thread creation time by using:
<BLOCKQUOTE>
		<A NAME="tex2html25"
  HREF="../susv2/xsh/pthread_attr_setschedparam.html"><TT>pthread_attr_setschedparam(3)</TT></A>

</BLOCKQUOTE>

<P>
or afterwards by using

<P>
<BLOCKQUOTE>
		<A NAME="tex2html26"
  HREF="../susv2/xsh/pthread_setschedparam.html"><TT>pthread_setschedparam(3)</TT></A>

.

</BLOCKQUOTE>

<P>
The policy argument is currently not used in RTLinux, but should be specified as <TT>SCHED_FIFO</TT> for 
compatibility with future
versions. The structure
<TT>sched_param</TT> contains the <TT>sched_priority</TT> member.
Higher values correspond to higher priorities. Use:

<P>

<UL>
<LI>
		<A NAME="tex2html30"
  HREF="../susv2/xsh/sched_get_priority_max.html"><TT>sched_get_priority_max(3)</TT></A>

, and
</LI>
<LI>
		<A NAME="tex2html31"
  HREF="../susv2/xsh/sched_get_priority_min.html"><TT>sched_get_priority_min(3)</TT></A>

</LI>
</UL>
to determine possible values of <TT>sched_priority</TT>.

<P>
To make a realtime thread execute periodically, users may use the
<EM>non-portable</EM><A NAME="tex2html27"
  HREF="#foot250"><SUP>2.1</SUP></A>function:

<P>
<BLOCKQUOTE>
		<A NAME="tex2html28"
  HREF="../MAN/pthread_make_periodic_np.3.html"><TT>pthread_make_periodic_np(3)</TT></A>

</BLOCKQUOTE>

<P>
which marks the thread as
periodic. Timing is specified by the <TT>itimer</TT> structure <TT>its</TT>. The <TT>it_value</TT> member of the passed struct <TT>itimerspec</TT>
specifies the time of the first invocation; the <TT>it_interval</TT> is
the thread period. Note that when setting up the period for task <B>T</B>, the period specified in the <TT>itimer</TT> structure can be 0. This
means that task <B>T</B> will execute only once.

<P>
The actual execution timing is performed by use of the function:

<P>
<BLOCKQUOTE>
		<A NAME="tex2html29"
  HREF="../MAN/pthread_wait_np.3.html"><TT>pthread_wait_np(3)</TT></A>

</BLOCKQUOTE>

<P>
This function suspends the execution of the calling thread
until the time specified by:

<P>
<BLOCKQUOTE>
<TT>pthread_make_periodic_np(3)</TT>

</BLOCKQUOTE>

<P>
In the next section we'll put the API to practical use.

<P>

<H1><A NAME="SECTION00330000000000000000">
A Simpl ``Hello World'' RTLinux program</A>
</H1>

<P>
We'll now write a small program that uses all of the API that
we've learned thus far. This program will execute two times per second,
and during each iteration it will print the message:

<P><PRE>
I'm here, my arg is 0
</PRE>

<P>

<H2><A NAME="SECTION00331000000000000000">
Code Listing</A>
</H2>
Save the following code under the filename <TT>hello.c</TT>:<PRE>
#include &lt;rtl.h&gt;
#include &lt;time.h&gt;
#include &lt;pthread.h&gt;

pthread_t thread;
void * start_routine(void *arg) {
   struct sched_param p;
   p . sched_priority = 1;
   pthread_setschedparam (pthread_self(), SCHED_FIFO, &amp;p);
   pthread_make_periodic_np (pthread_self(), gethrtime(),
                             500000000);

   while (1) {
     pthread_wait_np();
     rtl_printf("I'm here; my arg is %x\n", (unsigned) arg);
   }
   return 0;
}

int init_module(void) {
   return pthread_create (&amp;thread, NULL, start_routine, 0);
}

void cleanup_module(void) {
   pthread_cancel (thread);
   pthread_join (thread, NULL);
}
</PRE>

<P>

<P>
	<BR>
<BR>
	
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>This program can be found in <TT>examples/hello</TT>. 
	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
	
<P>
	<BR>
<BR>

<P>
Now, let's analyze the code.

<P>

<H2><A NAME="SECTION00332000000000000000">
Dissecting ``Hello World''</A>
</H2>
In our program, the

<P>
<BLOCKQUOTE>
<TT>init_module()</TT>

</BLOCKQUOTE>

<P>
function begins the entire process by creating our execution
thread - embodied in the function <TT>start_routine()</TT> - with an
argument of 0 passed to <TT>start_routine()</TT>.

<P>
<TT>start_routine</TT> has three components:
initialization, run-time and termination - best understood as the
blocks before, during and after the <TT>while()</TT> loop, respectively.

<P>
Upon the first call to the newly-created thread <TT>start_routine()</TT>, the initialization section tells the scheduler to
assign this thread a scheduling priority of 1 (one) with the call to
<TT>p.sched_priority</TT>. Next, the thread sets the scheduler's
behavior to be SCHED_FIFO for all subsequent executions with the call
to <TT>pthread_setschedparam</TT>. Finally, by calling the function:

<P>
<BLOCKQUOTE>
		<A NAME="tex2html32"
  HREF="../MAN/pthread_make_periodic_np.3.html"><TT>pthread_make_periodic_np()</TT></A>

</BLOCKQUOTE>

<P>
the thread tells the scheduler to periodically execute this thread
at a frequency of <IMG
 WIDTH="16" HEIGHT="20" ALIGN="BOTTOM" BORDER="0"
 SRC="img4.png"
 ALT="$2$">Hz (500 microseconds). This
marks the end of the initialization section for the thread.

<P>
The <TT>while()</TT> loop begins with a call to the function:

<P>
<BLOCKQUOTE>
		<A NAME="tex2html33"
  HREF="../MAN/pthread_wait_np.3.html"><TT>pthread_wait_np()</TT></A>

</BLOCKQUOTE>

<P>
which blocks all further execution of the thread until the scheduler
calls it again. Once the thread is called again, it executes
the rest of the contents inside the while loop, until it encounters
another call to:

<P>
<BLOCKQUOTE>
<TT>pthread_wait_np()</TT>

</BLOCKQUOTE>

<P>
Because we haven't included any way to exit the loop, this
thread will continue to execute forever at a rate of 2Hz. The only way
to stop the program is by removing it from the kernel with the <TT>rmmod(8)</TT> command.

<P>

<H2><A NAME="SECTION00333000000000000000">
Compiling and Executing ``Hello World''</A>
</H2>

<P>
In order to execute our program, we must first do the
following:

<P>

<OL>
<LI><EM>Compile the source code and create a module</EM>. We can
normally accomplish this by using the Linux GCC compiler directly from
the command line. To simplify things, however, we'll create
a Makefile. Then we'll only need to type ``make'' to compile
our code.

<P>
</LI>
<LI><EM>Locate and copy the <TT>rtl.mk</TT> file</EM>. The <TT>rtl.mk</TT>
file is an include file which contains all the flags needed
to compile our code. For simplicity, we'll copy it from the RTLinux
source tree and place it alongside of our <TT>hello.c</TT> file.

<P>
</LI>
<LI><EM>Insert the module into the running RTLinux kernel</EM>. The
resulting object binary must be ``plugged in'' to the kernel, where
it will be executed by RTLinux.
</LI>
</OL>

<P>
Let's look at these steps in some detail.

<P>
We begin by creating the 
	
		<A NAME="tex2html34"
  HREF="http://www.gnu.org/manual/make-3.79.1/make.html">Makefile</A>

 that
will be used to compile our <TT>hello.c</TT> program. Type the following
into a file called <TT>Makefile</TT> and put it in the same directory as
your <TT>hello.c</TT> program:

<P><PRE>
hello.o: hello.c
     gcc $(CFLAGS) hello.c
</PRE>

<P>
If you haven't already done so, locate the file <TT>rtl.mk</TT> and copy
it into the same directory as your <TT>hello.c</TT> and <TT>Makefile</TT>
files. The <TT>rtl.mk</TT> file can usually be found at <TT>/usr/include/rtlinux/rtl.mk</TT>.

<P>
<BLOCKQUOTE>
<TT>cp /usr/include/rtlinux/rtl.mk .</TT>

</BLOCKQUOTE>

<P>
(Note the trailing dot (.).)

<P>
Now, type the following:

<P><PRE>
make -f rtl.mk hello.o
</PRE>

<P>
This compiles the <TT>hello.c</TT> program and produces an
object file named <TT>hello.o</TT>.

<P>
We now need to load the RTLinux modules. There are several ways to do
this. The easiest is to use the <TT>rtlinux(1)</TT> command (as root):

<P>
<BLOCKQUOTE>
<TT>rtlinux start hello</TT>

</BLOCKQUOTE>

<P>
You can check the status of your modules by typing the command:

<P>
<BLOCKQUOTE>
<TT>rtlinux status hello</TT>

</BLOCKQUOTE>

<P>
For more information about the usage of the <TT>rtlinux(1)</TT> command,
refer to its man page, or type:

<P>
<BLOCKQUOTE>
<TT>rtlinux help</TT>

</BLOCKQUOTE>

<P>
You should now be able to see your <TT>hello.o</TT> program printing
its message twice per second. Depending on the configuration
of your machine, you should either be able to see it directly in your
console, or by typing:

<P>
<BLOCKQUOTE>
<TT>dmesg</TT>

</BLOCKQUOTE>

<P>
To stop the program, we need to remove it from the
kernel. To do so, type:

<P>
<BLOCKQUOTE>
<TT>rtlinux stop hello</TT>

</BLOCKQUOTE>

<P>
For other ways on running RTLinux programs, refer to
Appendix <A HREF="GettingStarted.html#running_rtlinux_progs">A</A>.

<P>
Congratulations, you have now successfully created and run your very
first RTLinux program!

<P>

<H1><A NAME="SECTION00400000000000000000"></A><A NAME="advanced_api"></A>
<BR>
The Advanced API: Getting More Out of Your 
RTLinux Modules
</H1>

<P>
RTLinux has a rich assortment of functions which can be used to solve
most realtime application problems. This chapter describes some of
the more advanced concepts.

<P>

<H1><A NAME="SECTION00410000000000000000">
Using Floating Point Operations in RTLinux POSIX Threads</A>
</H1>

<P>
The use of floating-point operations in RTL POSIX threads
is prohibited by default. The RTL-specific function

		<A NAME="tex2html35"
  HREF="../MAN/pthread_setfp_np.3.html"><TT>pthread_setfp_np(3)</TT></A>

 is used to
change the status of floating-point operations.

<P><PRE>
int pthread_setfp_np (pthread_tthread, int flag);
</PRE>

<P>
To enable FP operations in the thread, set the flag to 1. To disable
FP operations, pass 0.

<P>
The <TT>examples/fp</TT> directory contains several examples of tasks
which use floating point and the math library.

<P>

<H1><A NAME="SECTION00420000000000000000">
RTLinux Inter-Process Communication (IPC)</A>
</H1>

<P>
The general philosophy of RTLinux requires the realtime component of an
application to be lightweight, small and simple. Applications should be split in such a way that, as long as timing 
restrictions are met,
most of the work is done in user space. This
approach makes for easier debugging and better understanding of the
realtime part of the system. Consequently, communication mechanisms
are necessary to interface RTLinux tasks and Linux.

<P>
RTLinux provides several mechanisms which allow communication
between realtime threads and user space Linux processes. The most
important are realtime FIFOs and shared memory.

<P>

<H2><A NAME="SECTION00421000000000000000">
Using Real-Time FIFOs</A>
</H2>

<P>
Realtime FIFOs are First-In-First-Out queues that can be read from and
written to by Linux processes and RTLinux threads. FIFOs are
uni-directional - you can use a pair of FIFOs for bi-directional data
exchange. To use the FIFOs, the <TT>system/rtl_posixio.o</TT> and <TT>fifos/rtl_fifo.o</TT> Linux modules must be loaded in the kernel.

<P>
RT-FIFOs are Linux character devices with the major number of 150. Device entries in <TT>/dev</TT> are created during system installation. The
device file names are <TT>/dev/rtf0</TT>, <TT>/dev/rtf1</TT>, etc., through
<TT>/dev/rtf63</TT> (the maximum number of RT-FIFOs in the system is
configurable during system compilation).

<P>
Before a realtime FIFO can be used, it must be initialized:

<P><PRE>
#include &lt;rtl_fifo.h&gt;
int rtf_create(unsigned int fifo, int size);
int rtf_destroy(unsigned int fifo);
</PRE>

<P>

		<A NAME="tex2html36"
  HREF="../MAN/rtf_create.3.html"><TT>rtf_create</TT></A>

allocates the buffer of the specified size for the fifo buffer. The
<TT>fifo argument corresponds to the minor number of the device. 
	
		<A NAME="tex2html37"
  HREF="../MAN/rtf_destroy.3.html"><TT>rtf_destroy</TT></A>

deallocates the FIFO.
</TT>
<P>
<P>
<TT>	<BR>
<BR>
	</TT>
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>These functions must only be called from the Linux kernel thread
(i.e., from <TT>init_module()</TT>).

	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
<P>
<TT>	<BR>
<BR>

</TT>
<P>
<TT>After the FIFO is created, the following calls can be used to access
it from RTLinux threads: 
	
		<A NAME="tex2html38"
  HREF="../susv2/xsh/open.html"><TT>open(2)</TT></A>

, 
	
		<A NAME="tex2html39"
  HREF="../susv2/xsh/read.html"><TT>read(2)</TT></A>

,

		<A NAME="tex2html40"
  HREF="../susv2/xsh/write.html"><TT>write(2)</TT></A>

 and

		<A NAME="tex2html41"
  HREF="../susv2/xsh/close.html"><TT>close(2)</TT></A>

. Support for other
<TT>STDIO</TT> functions is planned for future releases.
</TT>
<P>
<P>
<TT>	<BR>
<BR>
	</TT>
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>Current implementation requires the FIFOs to be opened in non-blocking
mode (O_NONBLOCK) by RTL threads.

	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
<P>
<TT>	<BR>
<BR>

</TT>
<P>
<TT>You can also use the RTLinux-specific functions

		<A NAME="tex2html42"
  HREF="../MAN/rtf_put.3.html"><TT>rtf_put (3)</TT></A>

 and

		<A NAME="tex2html43"
  HREF="../MAN/rtf_get.3.html"><TT>rtf_get (3)</TT></A>

.
</TT>
<P>
<TT>Linux processes can use UNIX file IO functions without
restriction. See the <TT>examples/measurement/rt_process.c</TT> example
program for a practical application of RT-FIFOs.
</TT>
<P>
<H2><A NAME="SECTION00422000000000000000">
Using Shared Memory</A>
</H2>
<P>
<TT>For shared memory, you can use the excellent mbuff driver by Tomasz
Motylewski (<TT>motyl@chemie.unibas.ch</TT>. It is included with the
RTLinux distribution and is installed in the <TT>drivers/mbuff</TT> directory. A manual
is included with the package. Here, we'll just briefly describe the basic
mode of operation.
</TT>
<P>
<TT>First, the <TT>mbuff.o</TT> module must be loaded in the kernel. Two
functions are used to allocate blocks of shared memory, connect to
them and eventually deallocate them.
</TT>
<P><PRE>
#include &lt;mbuff.h&gt;
void * mbuff_alloc(const char *name, int size);
void mbuff_free(const char *name, void * mbuf);
</PRE>
<P>
<TT>The first time <TT>mbuff_alloc</TT> is called with a given name, a
shared memory block of the specified size is allocated. The reference
count for this block is set to 1. On success, the pointer to the newly
allocated block is returned. <TT>NULL</TT> is returned on failure. If the
block with the specified name already exists, this function returns a
pointer that can be used to access this block and increases the
reference count. 
</TT>
<P>
<TT><TT>mbuff_free</TT> deassociates <TT>mbuff</TT> from the
specified buffer. The reference count is decreased by 1. When it
reaches 0, the buffer is deallocated.
</TT>
<P>
<TT>These functions are available for use in both Linux processes and the
Linux kernel threads.
</TT>
<P>
<P>
<TT>	<BR>
<BR>
	</TT>
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM><TT>mbuff_alloc</TT> and <TT>mbuff_free</TT> cannot be used from
realtime threads. You should call them from <TT>init_module</TT> and
<TT>cleanup_module</TT> only.

	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
<P>
<TT>	<BR>
<BR>

</TT>
<P>
<H2><A NAME="SECTION00423000000000000000">
Waking and Suspending RTLinux Threads</A>
</H2>
<P>
<TT>Interrupt-driven RTLinux threads can be created using the thread
<TT>wakeup</TT> and <TT>suspend</TT> functions:
</TT>
<P><PRE>
int pthread_wakeup_np(pthread_t thread);
int pthread_suspend_np(void);
</PRE>
<P>
<TT>The general idea is that a threaded task can be either awakened
or suspended from within an interrupt service routine.
</TT>
<P>
<TT>An interrupt-driven thread calls <TT>pthread_suspend_np(pthread_self())</TT> and blocks. Later, the
interrupt handler calls 
	
		<A NAME="tex2html44"
  HREF="../MAN/pthread_wakeup_np.3.html"><TT>pthread_wakeup_np(3)</TT></A>

 for this thread. The thread will run until
the next call to 
	
		<A NAME="tex2html45"
  HREF="../MAN/pthread_suspend_np.3.html"><TT>pthread_suspend_np(3)</TT></A>

. An example can be found in <TT>examples/sound/irqthread.c</TT>.
</TT>
<P>
<TT>Another way to implement interrupt-driven threads is to use
semaphores. See <TT>examples/measurements/irqsema.c</TT> for examples of this method.
</TT>
<P>
<H2><A NAME="SECTION00424000000000000000">
Mutual Exclusion</A>
</H2>
<P>
<TT>Mutual exclusion refers to the concept of allowing only one task at a
time (out of many) to read from or write to a shared resource. Without
mutual exclusion, the integrity of the data found in that shared
resource could become compromised. Refer to the appendix for
further information on mutual exclusion.
</TT>
<P>
<TT>RTLinux supports the POSIX <TT>pthread_mutex_</TT> family of functions 
(<TT>include/rtl_mutex.h</TT>). Currently the following functions are 
available:
</TT>
<P>
<UL>
<LI>
		<A NAME="tex2html46"
  HREF="../susv2/xsh/pthread_mutexattr_getpshared.html"><TT>pthread_mutexattr_getpshared(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html47"
  HREF="../susv2/xsh/pthread_mutexattr_setpshared.html"><TT>pthread_mutexattr_setpshared(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html48"
  HREF="../susv2/xsh/pthread_mutexattr_init.html"><TT>pthread_mutexattr_init(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html49"
  HREF="../susv2/xsh/pthread_mutexattr_destroy.html"><TT>pthread_mutexattr_destroy(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html50"
  HREF="../susv2/xsh/pthread_mutexattr_settype.html"><TT>pthread_mutexattr_settype(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html51"
  HREF="../susv2/xsh/pthread_mutexattr_gettype.html"><TT>pthread_mutexattr_gettype(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html52"
  HREF="../susv2/xsh/pthread_mutex_init.html"><TT>pthread_mutex_init(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html53"
  HREF="../susv2/xsh/pthread_mutex_destroy.html"><TT>pthread_mutex_destroy(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html54"
  HREF="../susv2/xsh/pthread_mutex_lock.html"><TT>pthread_mutex_lock(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html55"
  HREF="../susv2/xsh/pthread_mutex_trylock.html"><TT>pthread_mutex_trylock(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html56"
  HREF="../susv2/xsh/pthread_mutex_unlock.html"><TT>pthread_mutex_unlock(3)</TT></A>

</LI>
</UL>
<P>
<TT>The supported mutex types include:
</TT>
<P>
<UL>
<LI>PTHREAD_MUTEX_NORMAL (default POSIX mutexes) and
</LI>
<LI>PTHREAD_MUTEX_SPINLOCK (spinlocks)
</LI>
</UL>
<P>
<TT>See <TT>examples/mutex</TT> for a test program. POSIX
semaphores are also supported. An example using POSIX semaphores can
be found in <TT>examples/mutex/sema_test.c</TT>.
</TT>
<P>
<H1><A NAME="SECTION00430000000000000000">
Accessing Physical Memory and I/O Ports 
from RTLinux Threads</A>
</H1>
<P>
<TT>These capabilities are essential for programming hardware devices in
the computer. RTLinux, just like ordinary Linux, supports the <TT>/dev/mem</TT> device (<B>man 4 mem</B>) for accessing physical memory from
RTLinux threads. The <TT>rtl_posixio.o</TT> module must be loaded. The
program opens <TT>/dev/mem</TT>, <EM>mmaps</EM> it, and then proceeds to
read and write the mapped area. See <TT>examples/mmap</TT> for an example.
</TT>
<P>
<P>
<TT>	<BR>
<BR>
	</TT>
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>In a module, you can call <TT>mmap</TT> from Linux mode only (i.e.,
from <TT>init_module()</TT>). Calling <TT>mmap</TT> from RT-threads will fail. 
	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
<P>
<TT>	<BR>
<BR>

</TT>
<P>
<TT>Another way to access physical memory is via Linux's <B>ioremap</B>
call:
</TT>
<P><PRE>
char *ptr = ioremap(PHYS_AREA_ADDRESS, PHYS_AREA_LENGTH);
...
ptr[i] = x;
</PRE>
<P>
<TT>IO port access functions (specifically for x86
architecture) are as follows:
</TT>
<P>
<UL>
<LI>Output a byte to a port:

<P><PRE>
#include &lt;asm/io.h&gt;
void rtl_outb(char value, short port)
void rtl_outb_p(char value, short port)
</PRE>

<P>
</LI>
<LI>Output a word to a port:

<P><PRE>
#include &lt;asm/io.h&gt;
void outw(unsigned int value, unsigned short port)
void outw_p(unsigned int value, unsigned short port)
</PRE>

<P>
</LI>
<LI>Read a byte from a port:

<P><PRE>
#include &lt;asm/io.h&gt;
char rtl_inb(unsigned short port)
char rtl_inb_p(unsigned short port)
</PRE>

<P>
</LI>
<LI>Read a word from a port:

<P><PRE>
#include &lt;asm/io.h&gt;
short inw(unsigned short port)
short inw_p(unsigned short port)
</PRE>
</LI>
</UL>
<P>
<TT>Note, the order of arguments is <TT>value, port</TT> in the output
functions. This may cause confusion when porting old code from other
systems.
</TT>
<P>
<TT>Functions with the ``<TT>_p</TT>'' suffix (e.g., <TT>outb_p</TT>)
provide a small delay after reading or writing to the port. This delay
is needed for some slow ISA devices on fast machines. (See also the Linux
I/O port programming mini-HOWTO).
</TT>
<P>
<TT>Check out <TT>examples/sound</TT> to see how some of these functions are used to
program the PC realtime clock and the speaker.
</TT>
<P>
<H1><A NAME="SECTION00440000000000000000">
Soft and Hard Interrupts</A>
</H1>
<P>
<TT>There are two types of interrupts in RTLinux: hard and soft.
</TT>
<P>
<TT>Soft interrupts are normal Linux kernel interrupts. They have the
advantage that some Linux kernel functions can be called from
them safely. However, for many tasks they do not provide hard realtime
performance; they may be delayed for considerable periods of time.
</TT>
<P>
<TT>Hard interrupts (or realtime interrupts), on the other hand, have
much lower latency. However, just as with realtime threads, only a
very limited set of kernel functions may be called from the hard
interrupt handlers.
</TT>
<P>
<H2><A NAME="SECTION00441000000000000000">
Hard Interrupts</A>
</H2>
<P>
<TT>The two functions:
</TT>
<P>
<UL>
<LI>
		<A NAME="tex2html57"
  HREF="../MAN/rtl_request_irq.3.html"><TT>rtl_request_irq(3)</TT></A>

 and

<P>
</LI>
<LI>
		<A NAME="tex2html58"
  HREF="../MAN/rtl_free_irq.3.html"><TT>rtl_free_irq(3)</TT></A>

</LI>
</UL>
<P>
<TT>are used for installing and uninstalling hard interrupt
handlers for specific interrupts. The manual pages describe their
operation in detail.
</TT>
<P><PRE>
#include &lt;rtl_core.h&gt;
int rtl_request_irq(unsigned int irq,
                     unsigned int (*handler) (unsigned int,
                     struct pt_regs *));
int rtl_free_irq(unsigned int irq);
</PRE>
<P>
<H2><A NAME="SECTION00442000000000000000">
Soft interrupts</A>
</H2>
<P><PRE>
int rtl_get_soft_irq(
         void (*handler)(int, void *, struct pt_regs *),
         const char * devname);
void rtl_global_pend_irq(int ix);
void rtl_free_soft_irq(unsigned int irq);
</PRE>
<P>
<TT>The 
	
		<A NAME="tex2html59"
  HREF="../MAN/rtl_get_soft_irq.3.html"><TT>rtl_get_soft_irq(3)</TT></A>

 function allocates a virtual irq number and
installs the handler function for it. This virtual interrupt can later
be triggered using 
	
		<A NAME="tex2html60"
  HREF="../MAN/rtl_global_pend_irq.3.html"><TT>rtl_global_pend_irq(3)</TT></A>

. <TT>rtl_global_pend_irq</TT> is safe to
use from realtime threads and realtime interrupts.

		<A NAME="tex2html61"
  HREF="../MAN/rtl_free_soft_irq.3.html"><TT>rtl_free_soft_irq(3)</TT></A>

 frees the allocated virtual interrupt.
</TT>
<P>
<TT>Note that soft interrupts are
used in the RTLinux FIFO implementation (<TT>fifos/rtl_fifo.c</TT>).
</TT>
<P>
<H1><A NAME="SECTION00500000000000000000"></A><A NAME="special_topics"></A>
<BR>
Special Topics
</H1>
<P>
<TT>You may never find yourself needing to know any of the following. Then again, you might.
</TT>
<P>
<H1><A NAME="SECTION00510000000000000000">
Symmetric Multi-Processing Considerations</A>
</H1>
<P>
<TT>From the point of view of thread scheduling, RTLinux implements a
separate UNIX process for each active CPU in the system. In general,
thread control functions can only be used for threads running on the
local CPU. Notable exceptions are:
</TT>
<P>
<UL>
<LI>
		<A NAME="tex2html62"
  HREF="../MAN/pthread_wakeup_np.3.html"><TT>int pthread_wakeup_np(pthread_t thread)</TT></A>

: wake up suspended thread

<P>
</LI>
<LI>
		<A NAME="tex2html63"
  HREF="../MAN/pthread_cancel.3.html"><TT>int pthread_cancel (pthread_t thread)</TT></A>

: cancel thread

<P>
</LI>
<LI>
		<A NAME="tex2html64"
  HREF="../MAN/pthread_join.3.html"><TT>int
pthread_join(pthread_t thread)</TT></A>

: wait for thread to finish

<P>
</LI>
<LI>
		<A NAME="tex2html65"
  HREF="../MAN/pthread_delete_np.3.html"><TT>int
pthread_delete_np (pthread_t thread)</TT></A>

: kill the thread

<P>
</LI>
</UL>
<P>
<TT>By default, a thread is created to run on the current CPU. To assign a
thread to a particular CPU, use the

		<A NAME="tex2html66"
  HREF="../MAN/pthread_attr_setcpu_np.3.html"><TT>pthread_attr_setcpu_np(3)</TT></A>

 function to set the CPU pthread
attribute. See <TT>examples/mutex/mutex.c</TT>.
</TT>
<P>
<H1><A NAME="SECTION00520000000000000000">
RTLinux Serial Driver (<TT>rt_com</TT>)</A>
</H1>
<P>
<TT><TT>rt_com(3)</TT> is a driver for 8250 and 16550 families of UARTs
commonly used in PCs (COM1, COM2, etc.). The available API is as
follows:
</TT>
<P><PRE>
#include &lt;rt_com.h&gt;
#include &lt;rt_comP.h&gt;
void rt_com_write(unsigned int com, char *pointer, int cnt);
int rt_com_read(unsigned int com, char *pointer, int cnt);
int rt_com_setup(unsigned int com, unsigned int baud,
                  unsigned int parity, unsigned int stopbits,
                  unsigned int wordlength);


#define RT_COM_CNT n
struct rt_com_struct
{
   int magic;                 // unused
   int baud-base;             // base-rate; 11520
                              // (BASE_BAUD in rt_comP.h;
                              // for standard ports.
   int port;                  // port number
   int irq;                   // interrupt number (IRQ)
                              //     for the port
   int flag;                  // flags set for this port
   void (*isr)(void)          // address of the interrupt
                              //     service routine
   int type;                  //
   int ier;                   // a copy of the IER register
   struct rt_buf_struct ibuf; // address of the port input
                              //     buffer
   struct rt_buf_struct obuf; // address of the port output
                              //     buffer
} rt_com_table [RT_COM_CNT];
</PRE>
<P>
<TT>where
</TT>
<P>
<UL>
<LI><TT>rt_com_write(3)</TT> - writes <TT>cnt</TT> characters from
buffer <TT>ptr</TT> to the realtime serial port <TT>com</TT>.

<P>
</LI>
<LI><TT>rt_com_read(3)</TT> - attempts to read <TT>cnt</TT> characters
to buffer <TT>ptr</TT> from the realtime serial port <TT>com</TT>.

<P>
</LI>
<LI><TT>rt_com_setup(3)</TT> - is used to dynamically change the
parameters of each realtime serial port.
</LI>
</UL>
<P>
<TT><TT>rt_com</TT> is a Linux module. The user must specify relevant serial port information
 via entries in
<TT>rt_com_setup</TT>. In
addition, the user must specify - via entries in the <TT>rt_com_table</TT> (located in <TT>rt_com.h</TT>) - the following:
</TT>
<P>
<UL>
<LI>Number of serial ports available (n)
</LI>
<LI>Serial ports and relevant parameters for each, and
</LI>
<LI>An ISR to be executed when the port
irq fires.
</LI>
</UL>
<P>
<TT>When <TT>rt_com (3)</TT> is installed with either <TT>insmod(8)</TT>, <TT>modprobe(8)</TT> or 
	
		<A NAME="tex2html67"
  HREF="../MAN/rtlinux.1.html"><TT>rtlinux(1)</TT></A>

, its <TT>init_module()</TT> function (in <TT>rt_com.c</TT>) requests
the port device memory, registers the ISR and sets various default
values for each port entry in <TT>rt_com_table</TT>.
</TT>
<P>
<H1><A NAME="SECTION00530000000000000000">
Interfacing RTLinux Components to Linux</A>
</H1>
<P>
<TT>RTLinux threads, sharing a common address space with the Linux kernel,
can in principle call Linux kernel functions. This is usually <EM>not</EM> a safe thing to do, however, because RTLinux threads may run even
while Linux has interrupts disabled. Only functions that do not modify
Linux kernel data structures (e.g., vsprintf) should be called from
RTLinux threads.
</TT>
<P>
<TT>RTLinux provides two delayed execution mechanisms to overcome this
limitation: soft interrupts and task queues.
</TT>
<P>
<P>
<TT>	<BR>
<BR>
	</TT>
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>The RTLinux white paper discusses this topic in more detail.
	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
<P>
<TT>	<BR>
<BR>

</TT>
<P>
<H1><A NAME="SECTION00540000000000000000">
Writing RTLinux Schedulers</A>
</H1>
<P>
<TT>Most users will never be required to write a scheduler. Future
versions of RTLinux are expected to have a fully customizable
scheduler, but in the meantime, here are some points to help the rest
of you along:
</TT>
<P>
<UL>
<LI>The scheduler is implemented in the <TT>scheduler/rtl_sched.c</TT> file
</LI>
<LI>The scheduler's architecture-dependent files are located in <TT>include/arch-i386</TT> and <TT>scheduler/i386</TT>
</LI>
<LI>The scheduling decision is taken in the <TT>rtl_schedule()</TT>
function. Thus, by modifying this function, it is possible to change
the scheduling policy.
</LI>
</UL>
<P>
<TT>Further questions in this area may be addressed directly to the FSM
Labs Crew.
</TT>
<P>
<H1><A NAME="SECTION00600000000000000000"></A><A NAME="running_rtlinux_progs"></A>
<BR>
Running RTLinux Programs
</H1>
<P>
<TT>Your RTLinux distribution comes complete with several examples in the
<TT>examples/</TT> sub-directory. These examples are useful, not only for
testing your brand new RTLinux distribution, but for helping get you
started writing your own RTLinux programs.
</TT>
<P>
<H1><A NAME="SECTION00610000000000000000">
General</A>
</H1>
<P>
<TT>Before you will be able to run any RTLinux programs, you must first
insert the RTLinux scheduler and support modules in the <TT>modules</TT>
into the Linux kernel. Use any of the following:
</TT>
<P>
<UL>
<LI>
		<A NAME="tex2html68"
  HREF="../MAN/rtlinux.1.html"><B>rtlinux(1)</B></A>

 script, the
preferred method,
</LI>
<LI><B>insmod(8)</B>,
</LI>
<LI><B>modprobe(8)</B>, or
</LI>
<LI>the <TT>insrtl</TT> script file that has been supplied for you in the
<TT>scripts</TT> directory.
</LI>
</UL>
<P>
<TT>For more information on Linux modules and how to manipulate them,
see the 
	
		<A NAME="tex2html69"
  HREF="http://www.ibiblio.org/mdw/HOWTO/Kernel-HOWTO.html">Linux
Kernel-HOWTO</A>

. 
</TT>
<P>
<TT>The following sections describe each of these methods in more detail.
</TT>
<P>
<H1><A NAME="SECTION00620000000000000000">
Examples</A>
</H1>
<P>
<H2><A NAME="SECTION00621000000000000000">
Using <TT>rtlinux</TT></A>
</H2>
<P>
<TT>Beginning with RTLinux 3.0-pre9, users can load and
remove user modules by using the 
	
		<A NAME="tex2html70"
  HREF="../MAN/rtlinux.1.html"><TT>rtlinux(1)</TT></A>

 command. To insert, remove, and obtain status
information about RTLinux modules, use the following commands:
</TT>
<P>
<BLOCKQUOTE><TT><TT>rtlinux start my_program</TT>
<BR><TT>rtlinux stop my_program</TT>
<BR><TT>rtlinux staus my_program</TT>
</TT></BLOCKQUOTE>
<P>
<TT>For further information on the the

		<A NAME="tex2html71"
  HREF="../MAN/rtlinux.1.html"><TT>rtlinux(1)</TT></A>

 script, type
either:
</TT>
<P>
<BLOCKQUOTE><TT><TT>man 1 rtlinux</TT>
</TT></BLOCKQUOTE>
<P>
<TT>or
</TT>
<P>
<BLOCKQUOTE><TT><TT>rtlinux help</TT>.
</TT></BLOCKQUOTE>
<P>
<H2><A NAME="SECTION00622000000000000000">
Using <TT>modprobe</TT></A>
</H2>
<P>
<TT>all the RTLinux modules, type the following:
</TT>
<P><PRE>
modprobe -a rtl rtl_time rtl_sched rtl_posixio rtl_fifo
</PRE>
<P>
<P>
<TT>	<BR>
<BR>
	</TT>
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>Using modprobe requires that modules be installed in <TT>/lib/modules/<EM>kernel_version</EM></TT>. 
	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
<P>
<TT>	<BR>
<BR>

</TT>
<P>
<H2><A NAME="SECTION00623000000000000000">
Using <TT>insmod</TT> and <TT>rmmod</TT></A>
</H2><TT>
Suppose we have the appropriately named
<TT>my_program.o</TT>. Assuming that all the
appropriate RTLinux modules have already been loaded, all that's left to do is to load this module
into the kernel:
</TT>
<P><PRE>
insmod my_program.o
</PRE>
<P>
<TT>To stop the program, all we need do is type:
</TT>
<P><PRE>
rmmod my_program
</PRE>
<P>
<H1><A NAME="SECTION00700000000000000000"></A><A NAME="rtlinux_api"></A>
<BR>
The RTLinux API at a Glance
</H1>
<P>
<TT>Some paths to be aware of:
</TT>
<P>
<UL>
<LI>RTLinux is installed in the directory <TT>/usr/rtlinux-xxx</TT>,
where <TT>xxx</TT> is the version number. To simplify future development, a symbolic link has been created as
<TT>/usr/rtlinux</TT> which points to <TT>/usr/rtlinux-xxx</TT>. Users are
encouraged to specify their paths via this symbolic link to maintain
future compatibility with new RTLinux versions.

<P>
</LI>
<LI><TT>/usr/rtlinux/include</TT> contains all the <TT>include</TT>
files necessary for development projects.

<P>
</LI>
<LI><TT>/usr/rtlinux/examples</TT> contains the RTLinux example programs, which illustrate the use of much of the API.

<P>
</LI>
<LI><TT>/usr/doc/rtlinux/man</TT> contains the manual pages for RTLinux.

<P>
</LI>
<LI><TT>/usr/rtlinux/modules</TT> contains the core RTLinux modules.

<P>
</LI>
<LI><TT>/usr/rtlinux/bin</TT> contains RTLinux scripts and utilities.

<P>
</LI>
</UL>
<P>
<TT>The following sections provide a listing of the various utilities
and APIs available in RTLinux.
</TT>
<P>
<H1><A NAME="SECTION00710000000000000000">
Getting Around</A>
</H1>
<P>
<TT>There are several manual pages which give overviews
on the technology and the APIs.
</TT>
<P>
<UL>
<LI>
		<A NAME="tex2html72"
  HREF="../MAN/rtl_v1.3.html"><TT>rtl_v1</TT> (3)</A>

: RTLinux
facilities for RTLinux v1.x. 
	
<P>
	<BR>
<BR>
	
<P></P>
<DIV ALIGN="CENTER">

		<IMG
 WIDTH="23" HEIGHT="22" ALIGN="BOTTOM" BORDER="0"
 SRC="img1.png"
 ALT="\includegraphics[width=0.2in]{components/stop_sign.eps}">

	<TABLE  WIDTH="80%">
<TR><TD>
	<EM>The RTLinux V1 API is presented exclusively
for backwards compatibility. It is no
longer recommended for new projects. Users are strongly discouraged from
starting any new projects with this API.
	</EM></TD></TR>
</TABLE>
</DIV>
<P></P>
	
<P>
	<BR>
<BR>

</LI>
<LI>
		<A NAME="tex2html73"
  HREF="../MAN/rtf.4.html"><TT>rtf</TT> (4)</A>

: realtime fifo devices
</LI>
<LI>
		<A NAME="tex2html74"
  HREF="../MAN/rtl_index.4.html"><TT>rtl_index</TT> (4)</A>

: A
comprehensive list of RTLinux functions.
</LI>
<LI>
		<A NAME="tex2html75"
  HREF="../MAN/rtlinux.4.html"><TT>rtlinux</TT> (4)</A>

: A general
roadmap and description to RTLinux
</LI>
</UL>
<P>
<H1><A NAME="SECTION00720000000000000000">
Scripts and Utilities</A>
</H1><TT>
The following utilities are designed to make your programming
job easier.
</TT>
<P>
<UL>
<LI>
		<A NAME="tex2html76"
  HREF="../MAN/rtl-config.1.html"><TT>rtl-config</TT> (1)</A>

: script
used to get information about the installed version of RTLinux,
cflags, include paths, and documentation paths.

<P>
</LI>
<LI>
		<A NAME="tex2html77"
  HREF="../MAN/rtlinux.1.html"><TT>rtlinux</TT> (1)</A>

: SysV compatible
script used to start RTLinux and load the user's RTLinux modules

<P>
</LI>
</UL>
<P>
<H1><A NAME="SECTION00730000000000000000">
Core RTLinux API</A>
</H1>
<P>
<TT>Here is the main RTLinux API. You are encouraged to use this API for all new projects.
</TT>
<P>
<UL>
<LI>
		<A NAME="tex2html78"
  HREF="../MAN/clock_gethrtime.3.html"><TT>clock_gethrtime</TT> (3)</A>

: get high resolution time using the specified clock

<P>
</LI>
<LI>
		<A NAME="tex2html79"
  HREF="../susv2/xsh/clock_gettime.html">clock_gettime</A>

: clock and timer functions

<P>
</LI>
<LI>
		<A NAME="tex2html80"
  HREF="../susv2/xsh/clock_settime.html">clock_settime</A>

: clock and timer functions

<P>
</LI>
<LI>
		<A NAME="tex2html81"
  HREF="../MAN/gethrtime.3.html"><TT>gethrtime</TT> (3)</A>

: get high resolution time

<P>
</LI>
<LI>
		<A NAME="tex2html82"
  HREF="../susv2/xsh/nanosleep.html">nanosleep</A>

: high resolution
sleep

<P>
</LI>
<LI>
		<A NAME="tex2html83"
  HREF="../MAN/pthread_attr_getcpu_np.3.html"><TT>pthread_attr_getcpu_np</TT> (3)</A>

: examine and change the CPU pthread attribute

<P>
</LI>
<LI>
		<A NAME="tex2html84"
  HREF="../susv2/xsh/pthread_attr_getschedparam.html"><TT>pthread_attr_getschedparam</TT></A>

: dynamic thread scheduling parameters access

<P>
</LI>
<LI>
		<A NAME="tex2html85"
  HREF="../susv2/xsh/pthread_attr_getdetachstate.html">pthread_attr_getdetachstate</A>

: get detachstate attributes

<P>
</LI>
<LI>
		<A NAME="tex2html86"
  HREF="../susv2/xsh/pthread_attr_getstacksize.html">pthread_attr_getstacksize</A>

: get stacksize attribute

<P>
</LI>
<LI>
		<A NAME="tex2html87"
  HREF="../susv2/xsh/pthread_attr_init.html">pthread_attr_init</A>

: initialize threads attribute object

<P>
</LI>
<LI>
		<A NAME="tex2html88"
  HREF="../MAN/pthread_attr_setcpu_np.3.html"><TT>pthread_attr_setcpu_np</TT> (3)</A>

: examine and change the CPU pthread attribute

<P>
</LI>
<LI>
		<A NAME="tex2html89"
  HREF="../susv2/xsh/pthread_attr_setdetachstate.html">pthread_attr_setdetachstate</A>

: set detachstate attributes

<P>
</LI>
<LI>
		<A NAME="tex2html90"
  HREF="../MAN/pthread_attr_setfp_np.3.html"><TT>pthread_attr_setfp_np</TT> (3)</A>

: set and get floating point enable attribute

<P>
</LI>
<LI>
		<A NAME="tex2html91"
  HREF="../susv2/xsh/pthread_attr_setschedparam.html"><TT>pthread_attr_setschedparam</TT></A>

: dynamic thread scheduling parameters access

<P>
</LI>
<LI>
		<A NAME="tex2html92"
  HREF="../susv2/xsh/pthread_attr_setstacksize.html">pthread_attr_setstacksize</A>

: set stacksize attribute

<P>
</LI>
<LI>
		<A NAME="tex2html93"
  HREF="../MAN/pthread_cancel.3.html"><TT>pthread_cancel</TT> (3)</A>

: stop and cancel a thread (not recommended)

<P>
</LI>
<LI>
		<A NAME="tex2html94"
  HREF="../MAN/pthread_create.3.html"><TT>pthread_create</TT> (3)</A>

: create a thread

<P>
</LI>
<LI>
		<A NAME="tex2html95"
  HREF="../susv2/xsh/pthread_condattr_destroy.html"><TT>pthread_condattr_destroy</TT></A>

: destroy condition variable attributes object

<P>
</LI>
<LI>
		<A NAME="tex2html96"
  HREF="../susv2/xsh/pthread_condattr_getpshared.html"><TT>pthread_condattr_getpshared</TT></A>

: get the process-shared
condition variable attributes	

<P>
</LI>
<LI>
		<A NAME="tex2html97"
  HREF="../susv2/xsh/pthread_condattr_init.html"><TT>pthread_condattr_init</TT></A>

: initialize condition variable attributes object

<P>
</LI>
<LI>
		<A NAME="tex2html98"
  HREF="../susv2/xsh/pthread_condattr_setpshared.html"><TT>pthread_condattr_setpshared</TT></A>

: set the process-shared
condition variable attributes	

<P>
</LI>
<LI>
		<A NAME="tex2html99"
  HREF="../susv2/xsh/pthread_cond_broadcast.html"><TT>pthread_cond_broadcast</TT></A>

: broadcast a condition

<P>
</LI>
<LI>
		<A NAME="tex2html100"
  HREF="../susv2/xsh/pthread_cond_destroy.html"><TT>pthread_cond_destroy</TT></A>

: destroy condition variable

<P>
</LI>
<LI>
		<A NAME="tex2html101"
  HREF="../susv2/xsh/pthread_cond_init.html"><TT>pthread_cond_init</TT></A>

: initialize condition variable

<P>
</LI>
<LI>
		<A NAME="tex2html102"
  HREF="../susv2/xsh/pthread_cond_signal.html"><TT>pthread_cond_signal</TT></A>

: signal a condition

<P>
</LI>
<LI>
		<A NAME="tex2html103"
  HREF="../susv2/xsh/pthread_cond_timedwait.html"><TT>pthread_cond_timedwait</TT></A>

: wait on a condition variable

<P>
</LI>
<LI>
		<A NAME="tex2html104"
  HREF="../susv2/xsh/pthread_cond_wait.html"><TT>pthread_cond_wait</TT></A>

: wait on a condition variable

<P>
</LI>
<LI>
		<A NAME="tex2html105"
  HREF="../MAN/pthread_delete_np.3.html"><TT>pthread_delete_np</TT> (3)</A>

: delete a realtime thread

<P>
</LI>
<LI>
		<A NAME="tex2html106"
  HREF="../susv2/xsh/pthread_exit.html"><TT>pthread_exit</TT></A>

: thread termination

<P>
</LI>
<LI>
		<A NAME="tex2html107"
  HREF="../MAN/pthread_join.3.html"><TT>pthread_join</TT> (3)</A>

:
terminate a thread

<P>
</LI>
<LI>
		<A NAME="tex2html108"
  HREF="../MAN/pthread_kill.3.html"><TT>pthread_kill</TT> (3)</A>

: send
a signal to a thread

<P>
</LI>
<LI>
		<A NAME="tex2html109"
  HREF="../MAN/pthread_linux.3.html"><TT>pthread_linux</TT> (3)</A>

: get the thread identifier of the Linux thread

<P>
</LI>
<LI>
		<A NAME="tex2html110"
  HREF="../MAN/pthread_make_periodic_np.3.html"><TT>pthread_make_periodic_np</TT> (3)</A>

: mark a realtime thread as periodic

<P>
</LI>
<LI>
		<A NAME="tex2html111"
  HREF="../susv2/xsh/pthread_mutexattr_destroy.html"><TT>pthread_mutexattr_destroy(3)</TT></A>

: Destroys a mutex attribute object.

<P>
</LI>
<LI>
		<A NAME="tex2html112"
  HREF="../susv2/xsh/pthread_mutexattr_getprioceiling.html"><TT>pthread_mutexattr_getprioceiling</TT></A>

: get priority ceiling attribute
of mutex attribute object.

<P>
</LI>
<LI>
		<A NAME="tex2html113"
  HREF="../susv2/xsh/pthread_mutexattr_getpshared.html"><TT>pthread_mutexattr_getpshared</TT></A>

: obtains the process-shared setting of a mutex attribute object.

<P>
</LI>
<LI>
		<A NAME="tex2html114"
  HREF="../susv2/xsh/pthread_mutexattr_gettype.html"><TT>pthread_mutexattr_gettype</TT></A>

: get the mutex type

<P>
</LI>
<LI>
		<A NAME="tex2html115"
  HREF="../susv2/xsh/pthread_mutexattr_init.html"><TT>pthread_mutexattr_init</TT></A>

: initializes a mutex attribute object. 

<P>
</LI>
<LI>
		<A NAME="tex2html116"
  HREF="../susv2/xsh/pthread_mutexattr_setprioceiling.html"><TT>pthread_mutexattr_setprioceiling</TT></A>

: set priority ceiling attribute
of mutex attribute object.

<P>
</LI>
<LI>
		<A NAME="tex2html117"
  HREF="../susv2/xsh/pthread_mutexattr_setpshared.html"><TT>pthread_mutexattr_setpshared</TT></A>

: sets the process-shared attribute
of a mutex attribute object

<P>
</LI>
<LI>
		<A NAME="tex2html118"
  HREF="../susv2/xsh/pthread_mutexattr_settype.html"><TT>pthread_mutexattr_settype</TT></A>

: set the mutex type

<P>
</LI>
<LI>
		<A NAME="tex2html119"
  HREF="../susv2/xsh/pthread_mutex_destroy.html"><TT>pthread_mutex_destroy</TT></A>

: destroys a mutex

<P>
</LI>
<LI>
		<A NAME="tex2html120"
  HREF="../susv2/xsh/pthread_mutex_init.html"><TT>pthread_mutex_init(3)</TT></A>

: initializes a mutex with the attributes specified in the specified mutex attribute object. 

<P>
</LI>
<LI>
		<A NAME="tex2html121"
  HREF="../susv2/xsh/pthread_mutex_lock.html"><TT>pthread_mutex_lock</TT></A>

: locks an unlocked mutex. If the mutex is
already locked, the calling thread blocks until the thread that
currently holds the mutex releases it.

<P>
</LI>
<LI>
		<A NAME="tex2html122"
  HREF="../susv2/xsh/pthread_mutex_trylock.html"><TT>pthread_mutex_trylock</TT></A>

: tries to lock a mutex. If the mutex is
already locked, the calling thread returns without wating for the
mutex to be freed.

<P>
</LI>
<LI>
		<A NAME="tex2html123"
  HREF="../susv2/xsh/pthread_mutex_unlock.html"><TT>pthread_mutex_unlock</TT></A>

: unlocks a mutex. 

<P>
</LI>
<LI>
		<A NAME="tex2html124"
  HREF="../susv2/xsh/pthread_getschedparam.html"><TT>pthread_getschedparam</TT></A>

: get schedparam attribute

<P>
</LI>
<LI>
		<A NAME="tex2html125"
  HREF="../susv2/xsh/pthread_self.html"><TT>pthread_self</TT></A>

: get calling thread's ID

<P>
</LI>
<LI>
		<A NAME="tex2html126"
  HREF="../susv2/xsh/pthread_setcancelstate.html"><TT>pthread_setcancelstate</TT></A>

: set cancelability state

<P>
</LI>
<LI>
		<A NAME="tex2html127"
  HREF="../susv2/xsh/pthread_setschedparam.html"><TT>pthread_setschedparam</TT></A>

: set schedparam attribute

<P>
</LI>
<LI>
		<A NAME="tex2html128"
  HREF="../MAN/pthread_setfp_np.3.html"><TT>pthread_setfp_np</TT> (3)</A>

: allow use of floating-point operations in a thread.

<P>
</LI>
<LI>
		<A NAME="tex2html129"
  HREF="../MAN/pthread_suspend_np.3.html"><TT>pthread_suspend_np</TT> (3)</A>

: suspend execution of a realtime thread.

<P>
</LI>
<LI>
		<A NAME="tex2html130"
  HREF="../MAN/pthread_wait_np.3.html"><TT>pthread_wait_np</TT>
(3)</A>

: suspend the current thread until the next period

<P>
</LI>
<LI>
		<A NAME="tex2html131"
  HREF="../MAN/pthread_wakeup_np.3.html"><TT>pthread_wakeup_np</TT> (3)</A>

: wake up a realtime thread.

<P>
</LI>
<LI>
		<A NAME="tex2html132"
  HREF="../MAN/rt_com.3.html"><TT>rt_com</TT> (3)</A>

: serial port driver for RTLinux

<P>
</LI>
<LI>
		<A NAME="tex2html133"
  HREF="../MAN/rt_com_read.3.html"><TT>rt_com_read</TT> (3)</A>

: read data in realtime from a serial por

<P>
</LI>
<LI>
		<A NAME="tex2html134"
  HREF="../MAN/rt_com_setup.3.html"><TT>rt_com_setup</TT> (3)</A>

: dynamically change the parameters of each realtime serial port.

<P>
</LI>
<LI>
		<A NAME="tex2html135"
  HREF="../MAN/rt_com_table.3.html"><TT>rt_com_table</TT> (3)</A>

: an array of descriptions, one per serial port.

<P>
</LI>
<LI>
		<A NAME="tex2html136"
  HREF="../MAN/rt_com_write.3.html"><TT>rt_com_write</TT> (3)</A>

: write data in realtime to a serial port

<P>
</LI>
<LI>
		<A NAME="tex2html137"
  HREF="../MAN/rtf_create.3.html"><TT>rtf_create</TT> (3)</A>

: create a realtime fifo

<P>
</LI>
<LI>
		<A NAME="tex2html138"
  HREF="../MAN/rtf_create_handler.3.html"><TT>rtf_create_handler</TT> (3)</A>

: install a handler for realtime fifo data

<P>
</LI>
<LI>
		<A NAME="tex2html139"
  HREF="../MAN/rtf_create_rt_handler.3.html"><TT>rtf_create_rt_handler</TT> (3)</A>

: install a handler for realtime fifo data

<P>
</LI>
<LI>
		<A NAME="tex2html140"
  HREF="../MAN/rtf_destroy.3.html"><TT>rtf_destroy</TT> (3)</A>

: remove
a realtime fifo created with 
	
		<A NAME="tex2html141"
  HREF="../MAN/rtf_create.3.html"><TT>rtf_create(3)</TT></A>

<P>
</LI>
<LI>
		<A NAME="tex2html142"
  HREF="../MAN/rtf_flush.3.html"><TT>rtf_flush</TT> (3)</A>

: empty a
realtime FIFO

<P>
</LI>
<LI>
		<A NAME="tex2html143"
  HREF="../MAN/rtf_get.3.html"><TT>rtf_get</TT> (3)</A>

: read data from
a realtime fifo

<P>
</LI>
<LI>
		<A NAME="tex2html144"
  HREF="../MAN/rtf_link_user_ioctl.3.html"><TT>rtf_link_user_ioctl</TT> (3)</A>

: install an <TT>ioctl (3)</TT> handler for a
realtime FIFO.

<P>
</LI>
<LI>
		<A NAME="tex2html145"
  HREF="../MAN/rtf_put.3.html"><TT>rtf_put</TT> (3)</A>

: write data to
a realtime fifo

<P>
</LI>
<LI>
		<A NAME="tex2html146"
  HREF="../MAN/rtf_make_user_pair.3.html"><TT>rtf_make_user_pair</TT> (3)</A>

: make a pair of RT-FIFOs act like a bidirectional FIFO

<P>
</LI>
<LI>
		<A NAME="tex2html147"
  HREF="../MAN/rtl_allow_interrupts.3.html"><TT>rtl_allow_interrupts</TT> (3)</A>

: control the CPU interrupt state

<P>
</LI>
<LI>
		<A NAME="tex2html148"
  HREF="../MAN/rtl_free_irq.3.html"><TT>rtl_free_irq</TT> (3)</A>

:
install and remove realtime interrupt handlers

<P>
</LI>
<LI>
		<A NAME="tex2html149"
  HREF="../MAN/rtl_free_soft_irq.3.html"><TT>rtl_free_soft_irq</TT> (3)</A>

: install and remove software interrupt handlers

<P>
</LI>
<LI>
		<A NAME="tex2html150"
  HREF="../MAN/rtl_get_soft_irq.3.html"><TT>rtl_get_soft_irq</TT> (3)</A>

: install and remove software interrupt handlers

<P>
</LI>
<LI>
		<A NAME="tex2html151"
  HREF="../MAN/rtl_getcpuid.3.html"><TT>rtl_getcpuid</TT> (3)</A>

: get the current processor id

<P>
</LI>
<LI>
		<A NAME="tex2html152"
  HREF="../MAN/rtl_getschedclock.3.html"><TT>rtl_getschedclock</TT> (3)</A>

: get the current scheduler clock

<P>
</LI>
<LI>
		<A NAME="tex2html153"
  HREF="../MAN/rtl_global_pend_irq.3.html"><TT>rtl_global_pend_irq</TT> (3)</A>

: schedule a Linux interrupt

<P>
</LI>
<LI>
		<A NAME="tex2html154"
  HREF="../MAN/rtl_hard_disable_irq.3.html"><TT>rtl_hard_disable_irq</TT> (3)</A>

: interrupt control

<P>
</LI>
<LI>
		<A NAME="tex2html155"
  HREF="../MAN/rtl_hard_enable_irq.3.html"><TT>rtl_hard_enable_irq</TT> (3)</A>

: interrupt control

<P>
</LI>
<LI>
		<A NAME="tex2html156"
  HREF="../MAN/rtl_no_interrupts.3.html"><TT>rtl_no_interrupts</TT> (3)</A>

: control the CPU interrupt state

<P>
</LI>
<LI>
		<A NAME="tex2html157"
  HREF="../MAN/rtl_printf.3.html"><TT>rtl_printf</TT> (3)</A>

: print formatted output

<P>
</LI>
<LI>
		<A NAME="tex2html158"
  HREF="../MAN/rtl_request_irq.3.html"><TT>rtl_request_irq</TT> (3)</A>

: install and remove realtime interrupt handlers

<P>
</LI>
<LI>
		<A NAME="tex2html159"
  HREF="../MAN/rtl_restore_interrupts.3.html"><TT>rtl_restore_interrupts</TT> (3)</A>

: control the CPU interrupt state

<P>
</LI>
<LI>
		<A NAME="tex2html160"
  HREF="../MAN/rtl_setclockmode.3.html"><TT>rtl_setclockmode</TT> (3)</A>

: set the RTLinux clock mode

<P>
</LI>
<LI>
		<A NAME="tex2html161"
  HREF="../MAN/rtl_stop_interrupts.3.html"><TT>rtl_stop_interrupts</TT> (3)</A>

: control the CPU interrupt state

<P>
</LI>
<LI>
		<A NAME="tex2html162"
  HREF="../MAN/rtlinux_sigaction.3.html"><TT>rtlinux_sigaction</TT> (3)</A>

: RTLinux v3 User-Level signal handling functions.

<P>
</LI>
<LI>
		<A NAME="tex2html163"
  HREF="../MAN/rtlinux_signal.3.html"><TT>rtlinux_signal</TT> (3)</A>

: list of available RTLinux User-Level signals

<P>
</LI>
<LI>
		<A NAME="tex2html164"
  HREF="../MAN/rtlinux_sigprocmask.3.html"><TT>rtlinux_sigprocmask</TT> (3)</A>

: RTLinux v3 User-Level signal handling functions.

<P>
</LI>
<LI>
		<A NAME="tex2html165"
  HREF="../MAN/rtlinux_sigsetops.3.html"><TT>rtlinux_sigsetops</TT> (3)</A>

: RTLinux User-Level signal set operations

<P>
</LI>
<LI>
		<A NAME="tex2html166"
  HREF="../susv2/xsh/sched_get_priority_max.html"><TT>sched_get_priority_max</TT></A>

: get priority limits for the scheduling
policy

<P>
</LI>
<LI>
		<A NAME="tex2html167"
  HREF="../susv2/xsh/sched_get_priority_min.html"><TT>sched_get_priority_min</TT></A>

: get priority limits for the scheduling
policy

<P>
</LI>
<LI>
		<A NAME="tex2html168"
  HREF="../susv2/xsh/sem_init.html"><TT>sem_init</TT></A>

: initialize POSIX semaphore

<P>
</LI>
<LI>
		<A NAME="tex2html169"
  HREF="../susv2/xsh/sem_destroy.html"><TT>sem_destroy</TT></A>

: destroy an unnamed POSIX semaphore

<P>
</LI>
<LI>
		<A NAME="tex2html170"
  HREF="../susv2/xsh/sem_getvalue.html"><TT>sem_getvalue</TT></A>

: get the value of a sempahore

<P>
</LI>
<LI>
		<A NAME="tex2html171"
  HREF="../susv2/xsh/sem_post.html"><TT>sem_post</TT></A>

: unlock a semaphore

<P>
</LI>
<LI>
		<A NAME="tex2html172"
  HREF="../susv2/xsh/sem_trywait.html"><TT>sem_trywait</TT></A>

: lock a semaphore

<P>
</LI>
<LI>
		<A NAME="tex2html173"
  HREF="../susv2/xsh/sem_wait.html"><TT>sem_wait</TT></A>

: lock a semaphore

<P>
</LI>
<LI>
		<A NAME="tex2html174"
  HREF="../MAN/sigaction.2.html"><TT>sigaction</TT> (2)</A>

: RTLinux
POSIX signal handling functions

<P>
</LI>
<LI>
		<A NAME="tex2html175"
  HREF="../susv2/xsh/sysconf.html"><TT>sysconf</TT></A>

: get
configurable system variables

<P>
</LI>
<LI>
		<A NAME="tex2html176"
  HREF="../susv2/xsh/time.html"><TT>time</TT></A>

: clock and timer
functions

<P>
</LI>
<LI>
		<A NAME="tex2html177"
  HREF="../susv2/xsh/uname.html"><TT>uname</TT></A>

: get name of current system

<P>
</LI>
<LI>
		<A NAME="tex2html178"
  HREF="../susv2/xsh/usleep.html"><TT>usleep</TT></A>

: suspend execution
for an interval

<P>
</LI>
</UL>
<P>
<H1><A NAME="SECTION00740000000000000000">
Version 1.x API: Not for New Projects</A>
</H1>
<P>
<TT>The v1 API is exclusively for older RTLinux projects. It is
NOT recommended for use with new projects. This listing is for backward compatibility only:
</TT>
<P>
<UL>
<LI>
		<A NAME="tex2html179"
  HREF="../MAN/free_RTirq.3.html"><TT>free_RTirq</TT> (3)</A>

: uninstall an interrupt handler

<P>
</LI>
<LI>
		<A NAME="tex2html180"
  HREF="../MAN/request_RTirq.3.html"><TT>request_RTirq</TT> (3)</A>

: install an interrupt handler

<P>
</LI>
<LI>
		<A NAME="tex2html181"
  HREF="../MAN/rt_get_time.3.html"><TT>rt_get_time</TT> (3)</A>

: get time in ticks

<P>
</LI>
<LI>
		<A NAME="tex2html182"
  HREF="../MAN/rt_task_delete.3.html"><TT>rt_task_delete</TT> (3)</A>

: delete a realtime task

<P>
</LI>
<LI>
		<A NAME="tex2html183"
  HREF="../MAN/rt_task_init.3.html"><TT>rt_task_init</TT> (3)</A>

: create a realtime task

<P>
</LI>
<LI>
		<A NAME="tex2html184"
  HREF="../MAN/rt_task_make_periodic.3.html"><TT>rt_task_make_periodic</TT> (3)</A>

: mark a realtime task for execution.

<P>
</LI>
<LI>
		<A NAME="tex2html185"
  HREF="../MAN/rt_task_suspend.3.html"><TT>rt_task_suspend</TT> (3)</A>

: suspend execution of a realtime task.

<P>
</LI>
<LI>
		<A NAME="tex2html186"
  HREF="../MAN/rt_task_wait.3.html"><TT>rt_task_wait</TT> (3)</A>

: suspend execution for the current period until the next period

<P>
</LI>
<LI>
		<A NAME="tex2html187"
  HREF="../MAN/rt_task_wakeup.3.html"><TT>rt_task_wakeup</TT> (3)</A>

: allow a previously suspended realtime task to run.

<P>
</LI>
<LI>
		<A NAME="tex2html188"
  HREF="../MAN/rt_use_fp.3.html"><TT>rt_use_fp</TT> (3)</A>

: set/remove permission for task to use floating point unit 

<P>
</LI>
</UL>
<P>
<P>
<H1><A NAME="SECTION00800000000000000000">
About this document ...</A>
</H1>Copyright: 2001 FSM Labs, Inc.
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot250">...<EM>non-portable</EM></A><A NAME="foot250"
 HREF="GettingStarted.html#tex2html27"><SUP>2.1</SUP></A>
<DD>It is possible to have threads execute
periodically within RTLinux by using the pure POSIX API. However,
this scheme is quite lengthy. This
particular function has been added, therefore, to reduce user development time.

</DL><HR>
<!--Navigation Panel-->
<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
 SRC="/usr/share/latex2html/icons/nx_grp_g.png"> 
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
 SRC="/usr/share/latex2html/icons/up_g.png"> 
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
 SRC="/usr/share/latex2html/icons/prev_g.png">   
<BR>
<!--End of Navigation Panel-->
<ADDRESS>
Michael Barabanov
2001-06-19
</ADDRESS>
</BODY>
</HTML>