http://www.realtimelinux.org/documentation.html Real Time Linux Documentation Project, Vol. 1, 2000 P. N. Daly and J. K pper, eds.

u Real Time Linux Community Press

RTLinux Installation Manual

Phil Whilshire Kaiser Aluminum, http://www.kaiseral.com philwil@realtimelinux.org Victor Yodaiken VJY Associates L.L.C., http://www.vjy.com yodaiken@fsmlabs.com Joachim Nilsson and Daniel Rytterlund M lardalen Realtime Research Centre, http://www.mrtc.mdh.se/ a joachim.nilsson, daniel.rytterlund @vmlinux.org Abstract. A brief installation tutorial that covers everything from conguring the Linux kernel and installing it, messing with Lilo down to compiling and testing the RTLinux test examples.

License This document is free. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation either version 2 of the License, or (at your option) any later version. This document is distributed in the hope that it will be useful, but without any warranty. Without even the implied warranty of merchantability or tness for a particular purpose. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this document. If not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge MA 02139, USA. Copyright(s) c 1999, Phil Whilshire, the original installation guide; Installing RT Linux. . . NMT RTLinux. All rights reserved. c 2000, Victor Yodaiken, modications for RTLinux 2.2 c 2000, Joachim Nilsson and Daniel Rytterlund, conversion to RTLDOC. All rights reserved. Typographic Conventions The conventions used in this document are described in Table 1 on page 2. For reasons of clarity,

Phil Whilshire et al. Table 1.: Typographical Conventions for this Document Markup Usage Effect

\rtlin{blue type-face} user input blue type-face \rtlout{magenta sans-serif } machine output magenta sans-serif \rtlnormal{black times-roman} normal text (reset) black times-roman \rtlmargin{teal italic} margin notes teal italic

the \rtlmargin is not shown as a margin note within the table. Verbatim-like output can be set using the rtlcode environment(Daly et al., 2000).
\begin{rtlcode} . . . \end{rtlcode}

RTLinux Installation Manual 1. Retrieving and Unpacking the Source

In this section a brief introduction on how to retrieve, congure, compile and install the Linux kernel is given. There is also a run through of how to patch the kernel with the RTLinux kernel patch. Installing the kernel and conguring the boot-time options is mostly the same on all Linux distributions, like Red Hat, Debian and Slackware (including their derivatives). Here a Red Hat based distribution is assumed, probably more to come later. This version of the installation manual assumes the Red Hat GNU/Linux distribution during section 3. If you already know how to retrieve the latest kernels and patches you can skip ahead to section 1.5. For a more complete run-through on how to compile and install the standard Linux kernel the Kernel-HOWTO (Ward, 1999), which usually resides in /usr/doc/HOWTO/, is the recommended source of information. 1.1. Get a Clean Linux Kernel The rst thing to do is to download the Linux kernel. In this case it has to be the kernel matching the latest release of RTLinux. In our case that is RTLinux ver.2.2and Linux ver.2.2.14. To nd your nearest/fastest location for kernel downloads consult:
http://www.kernel.org/mirrors/

1.2. Get the RTLinux Patch File The latest RTLinux patches to the Linux kernel, which in our case is v.2.2, is available from:
ftp://ftp.rtlinux.com/rtlinux/

You have two options when performing this step. 1. Download the patch and manually patch the Linux kernel yourself. 2. Download a pre-patched kernel. The second step is of course the easiest and it means you can skip section 1.6. below. It also means that the previous step was completely useless, but thats another issue. :) 1.3. Pre-Installation Issues The common place to unpack and store the Linux kernel tree is in /usr/src/ where the current kernel usually resides in the subdirectory linux/. This can either be a real directory or a symbolic link to the correct tree, say linux-2.2.12/. You can check this by issuing:
[wilshire@pasrack3 wilshire]$ ls -ld /usr/src/linux

lrwxrwxrwx

1 root

root

17 Aug 17

1998 /usr/src/linux -> linux-2.2.12

In this case it was a link. If it isnt you have to move the current tree to another directory, otherwise simply remove the link. Become root (administrator) and move the old kernel:

4
[wilshire@pasrack3 wilshire]$ su
Password:

Phil Whilshire et al.

[root@pasrack3 wilshire]# cd /usr/src [root@pasrack3 src]# mv linux linux-uname -r

If you want to work in /usr/src/ you can continue as is explained in the Kernel-HOWTO (Ward, 1999, Unpacking the source). However, we have chosen a somewhat different approach, which is given below. 1.4. Creating a Working Directory In the examples given below we are working in the /opt/rtl/ directory tree. Its good to keep your work separated from the system kernel. (This of course implies that you do have the /opt/ directory rst of all . . . )1 Make the directory.

[root@pasrack3 src]# mkdir /opt/rtl

Loosen up the restrictions on the new directory:

[root@pasrack3 src]# chmod a+rw /opt/rtl

This will allow you as a user (and everybody else) to access this. There are better ways, like using the chown command and similar approaches, but for clearity reasons we have left this out. But please note that doing your work as a regular user is always safer! Now leave this unsafe root world . . .

[root@pasrack3 src]# exit [wilshire@pasrack3 wilshire]$

1.5. Unpacking Untar the RTLinux tarball into your working directory, set up above. I.e. if the tarball is in /home/wilshire/download/rtl/rtlinux-2.2.tgz

[wilshire@pasrack3 wilshire]$ cd /opt/rtl [wilshire@pasrack3 rtl]$ tar xvzf /home/wilshire/download/rtl/rtlinux-2.2.tgz

This will create the RTLinux directory tree:

/opt/rtl/rtlinux-2.2 /opt/rtl/rtlinux-2.2/linux /opt/rtl/rtlinux-2.2/rtl /opt/rtl/rtlinux-2.2/rtl/doc/ /opt/rtl/rtlinux-2.2/rtl/drivers/

1

You may need to do this as root.

RTLinux Installation Manual

/opt/rtl/rtlinux-2.2/rtl/examples/ /opt/rtl/rtlinux-2.2/rtl/fifos/ /opt/rtl/rtlinux-2.2/rtl/html/ /opt/rtl/rtlinux-2.2/rtl/include/ /opt/rtl/rtlinux-2.2/rtl/man/ /opt/rtl/rtlinux-2.2/rtl/modules/ /opt/rtl/rtlinux-2.2/rtl/semaphores/ /opt/rtl/rtlinux-2.2/rtl/misc/ /opt/rtl/rtlinux-2.2/rtl/schedulers/ /opt/rtl/rtlinux-2.2/rtl/system/

If youve downloaded and untar:ed a pre-patched version of RTLinux, then you can skip down to section 2. Otherwise, move on to the patching. 1.6. Patching the Kernel Look in the INSTALL le and follow the instructions.
********************** INSTALL ****************************** 1. put a fresh copy of Linux in this directory under the name linux. 2. cd linux patch -p1 < ../kernel_patch *************************************************************

1. This means take the linux-2.2.14.tar.gz tarball and put it where the install guide suggests. I.e. if the tarball is in /home/wilshire/download/linux/linux-2.2.14.tar.gz
[wilshire@pasrack3 rtl]$ cd rtlinux-2.2 [wilshire@pasrack3 rtlinux-2.2]$ tar xvzf /home/wilshire/download/linux/linux-2.2.14.tar.gz

2. Now you are set to patch.

[wilshire@pasrack3 rtlinux-2.2]$ cd linux [wilshire@pasrack3 linux]$ patch -p1 ../kernel patch

Check for rejects during the course of the patch. There should be no rejects! Here is an example2 of a reject:
[wilshire@pasrack3 linux]$ patch -p1 < ../kernel patch

Patching file arch/i386/kernel/irq.c using Plan A... Hunk #1 failed at 39. Hunk #2 succeeded at 236. Hunk #3 succeeded at 280. Hunk #21 succeeded at 1324. 1 out of 21 hunks failed--saving rejects to arch/i386/kernel/irq.c.rej
2

Output may differ between versions of the UNIX patch command.

Phil Whilshire et al. To nd any rejected patch les, issue a find request in the linux/ directory like this:

[wilshire@pasrack3 linux]$ find ./ -name *.rej

./arch/i386/kernel/irq.c.rej

You can only patch once (well sort of) so start again, from section 1.5. just to be on the safe side, if you fumble somehow.
[wilshire@pasrack3 linux]$ cd .. [wilshire@pasrack3 rtlinux-2.2]$ rm -rf linux [wilshire@pasrack3 rtlinux-2.2]$ tar xvzf /home/wilshire/download/linux/linux-2.2.14.tar.gz

If it seems completely impossible to patch the Linux kernel, try downloading the latest prepatched version of RTLinux, as mentioned above in section 1.2. Untar it according to the steps mentioned above. This distribution comes complete with a matching pre-patched Linux kernel. 2. Congure and compile the Kernel If you have patched the kernel or if you skipped the previous step because you downloaded and untar:ed a pre-patched kernel this is the place to continue at. 2.1. Examining the Running System To be able to use the resources of your system when running RTLinux you need to examine your, hopefully working, Linux installation. Start out by looking at whats running currently.
[wilshire@pasrack3 linux]$ /sbin/lsmod

Module 3c59x

Size 19048

Used by 1 (autoclean)

We see the modules used and make sure that we congure the new kernel for the same ones. 2.2. Congure the Kernel To compile the patched Linux kernel you need to run the config utility that comes with the kernel. It exist in three shapes: config, menuconfig and xconfig. For further details consult the Linux Kernel-HOWTO (Ward, 1999).
[wilshire@pasrack3 linux]$ cd /opt/rtl/rtlinux-2.2/linux [wilshire@pasrack3 linux]$ make menucong

When the kernel menu is up start checking the options as required to match your settings.
Code maturity level options ---> yes

Processor type and features ---> (PPro/6x86MX) Processor family

... or whatever you have

[*] Symmetric multi-processing support

RTLinux Installation Manual

[*] Hard realtime support Loadable module support ---> [*] Enable loadable module support [ ] Set version information on all symbols for modules [ ] Kernel module loader General setup Plug and Play support Plug and Play support Networking options SCSI support ---> ---> ---> ---> ---> accept accept accept accept accept defaults defaults defaults defaults defaults

Network device support ---> ... here we wanted a 3c59x module Ethernet (10 or 100Mbit) ---> [*] 3COM cards <M> 3c590/3c900 series (592/595/597) "Vortex/Boomerang" support. Kernel hacking ---> [*] Magic SysRq key

... this may come in handy

The Magic SysRq key commands are described in linux/Documentation/sysrq.txt . Finish off by saving your conguration, save to a le in your home directory for instance, so that you have it close by if you need to redo the conguration. 2.3. Compiling the Kernel Finally, you get to compile the kernel. The CPU has been idle for so long now while you have been reading this manual. Let it do some real work for a change!
[wilshire@pasrack3 linux]$ make dep clean bzImage

Go for a cup of tea, read your mail, write a manual . . . 10 minutes or so (depending on how fast your computer is, of course). You will end up with a new kernel image a new Symbol.map etc. 2.4. Make/Install the modules This next step will compile and install the necessary modules that you selected during the conguration. In our case we wanted the 3c59x NIC to be compiled as a module.
[root@pasrack3 linux]# make modules

mkdir -p modules touch modules/MARKER . . .

Now you only need to become root (administrator) and install them.
[wilshire@pasrack3 linux]$ su
Password:

[root@pasrack3 linux]#

Phil Whilshire et al.

[root@pasrack3 linux]# make modules install

. . . Installing Installing Installing Installing

modules modules modules modules

under under under under

/lib/modules/2.2.14-RTL2.2/fs /lib/modules/2.2.14-RTL2.2/ipv4 /lib/modules/2.2.14-RTL2.2/misc /lib/modules/2.2.14-RTL2.2/net

If you want to verify the result to ensure that your modules actually were built and installed then look in this directory. Some of the below mentioned subdirectories might not exist, it depends on the choices made during the conguration.
[root@pasrack3 linux]# ls -l /lib/modules/2.2.14-RTL2.2

total 4 drwxr-xr-x drwxr-xr-x drwxr-xr-x drwxr-xr-x total 3 -rw-r--r--rw-r--r--

2 2 2 2

root root root root

root root root root root root

1024 1024 1024 1024

Mar Mar Mar Mar

6 6 6 6

17:10 17:10 17:10 17:10

fs ipv4 misc net

[root@pasrack3 linux]# ls -l /lib/modules/2.2.14-RTL2.2/net/

1 root 1 root

2360 Mar 2360 Mar

6 17:10 dummy.o 6 17:10 3c59x.o

We decide that were happy with this and move on to setting up the boot conguration. 3. Setting up Boot & Lilo To be able to boot the newly compiled kernel and start working with RTLinux you need to copy the boot image, and in some cases also the Symbol.map, to the right place. Depending on the distribution the kernel mostly lives in /boot/. However, some distributions, like Slackware, simply store it in /. The reason for all this is that on x86 based systems the bootloader needs to have the kernel on the rst 1024 cylinders of the hard drive, which in most cases is the root or boot partition.
[root@pasrack3 linux]# cp arch/i386/boot/bzImage /boot/rtlinuz-2.2 [root@pasrack3 linux]# ln -sf /boot/rtlinuz-2.2 /boot/rtlinuz

Finish off by editing /etc/lilo.conf, the LInux LOader conguration. If you start to feel a bit anxious now, take a look at the man-page rst.
[root@pasrack3 linux]# man lilo.conf [root@pasrack3 linux]# vim /etc/lilo.conf . . . the author prefers vim

It should look something like this:

========================================================= boot=/dev/hda ... I have Lilo in the MBR. map=/boot/map

RTLinux Installation Manual

install=/boot/boot.b prompt timeout=50 image=/boot/rtlinuz label=rtlinux root=/dev/hda1 append="mem=128M" read-only

... First image == default. ... The RTLinux kernel.

image=/boot/vmlinuz label=linux root=/dev/hda1 append="mem=128M" read-only ======================================================

Its always a good idea to keep a working kernel conguration in the lilo.conf le. Otherwise you might end up in quite a predicament. No bootable kernel, thats another issue not covered here. Next step: run Lilo.
[root@pasrack3 linux]# /sbin/lilo

Added rtlinux * Added linux

4. Booting RTLinux Now, nally, is the time to reboot with RTLinux and see if youve succeeded in your painful efforts.
[root@pasrack3 linux]# reboot

For some applications, the Symbol.map needs to be in the right place also. Without it they cannot do lookups in the kernel correctly. You might have noticed this during the reboot, so to resolve this you need to copy the recently created kernel symbol table to /boot/ with the correct version appended to the name. Log in as root, x it and reboot once again to be on the safe side:
[root@pasrack3 root]# cd /opt/rtl/rtlinux-2.2/linux [root@pasrack3 linux]# cp Symbol.map /boot/Symbol.map-uname -r [root@pasrack3 linux]# reboot

Since everything went completely well having rebooted well now move on to compiling the necessary RTLinux modules and examples. Log in as root and continue happily with this never ending story in the nal two sections. :)

10 5. The RTLinux Modules

Phil Whilshire et al.

RTLinux consists of quite a few parts. The Linux kernel patch, that was the subject in the previous sections is actually just a small part. The real work is done by the RTLinux modules: rtl shed, rtl time, rtl posixio, rtl fo, semaphore and mbuff. For a run-through of the RTLinux architecture please consult the design document (Yodaiken and Barabanov, 1999). 5.1. Preparing for the RTLinux modules To be able to compile the RTLinux modules we need to move the systems Linux source link to our new source tree3 . If you havent already removed/moved the /usr/src/linux link/directory, as mentioned in section 1.3. or in the Linux Kernel-HOWTO (Ward, 1999, Unpacking the source), this is the time to go back and do just that.
[root@pasrack3 wilshire]# ln -s /opt/rtl/rtlinux-2.2/linux /usr/src/linux

This is to ensure that there are no stale links in /usr/include since the /usr/include/asm and /usr/include/linux point to, or rather should point to, directories in the current kernel. 5.2. Compiling the RTLinux Modules Move to the RTLinux directory and compile the modules (preferably not as root).
[wilshire@pasrack3 wilshire]$ cd /opt/rtl/rtlinux-2.2/rtl [wilshire@pasrack3 rtl]$ make all

Everything should work out ne and youre now only one step away from getting down dirty with the examples! Only the installation of the RTLinux modules remains. 5.3. Installing the RTLinux Modules Become root (administrator) and start the installation. The output should resemble the result below.
[wilshire@pasrack3 rtl]$ su

Password:
[root@pasrack3 rtl]# make install

. . . Testing for the mbuff device... mknod /dev/mbuff c 10 254 Testing for FIFOs... already existent. Instaling modules in /lib/modules/2.2.14-RTL2.2/misc /sbin/depmod -a Installing man pages to /usr/local/man Installing header /usr/include/rtlinux install -c -m 644 rtl.mk /usr/include/rtlinux;

Thats it for the main install. . .

3

Most likely you need to be root to do all this.

RTLinux Installation Manual 6. Running the RTLinux Examples

11

Now its at long last time to start playing around with the examples. To mess with modules in the kernel, and such stuff, you need to be root. Start by inserting the RTLinux modules before we compile the rst example.
[root@pasrack3 rtl]# ./insrtl

Real-Time tasks are inserted into RTLinux by the use of standard Linux modules. Modules consist of two main functions, namely: init module() and cleanup module(). RT tasks are usually created in init module() and deleted in cleanup module(). The best thing with the examples is that you can mess around with them yourself and try out the different features that is also the best way see this section, as a brief piece of information about the meaning of the examples. 6.1. Frank Zappa The coolest of the examples is the frank module. The name was given by Michael fz Barabanov as a tribute to the late singer. This example features two real-time tasks that can potentially perform some real work, e.g. data collection. Here they simply write strings into FIFOs. The real-time part creates three RT-FIFOs: two for data passing, and one for control. Then it creates two real-time tasks and registers a handler with the control FIFO. Real-time and non-real-time parts both agree on the format of control messages (see le control.h). Whenever Linux tasks writes to the control FIFO, the handler is invoked. In the handler the RT-tasks are started and stopped. The real-time tasks are almost identical. They keep writing strings into FIFOs. In the end of each loop each of them makes a request to deschedule itself until the beginning of the next period. The Linux program (app) opens RT-FIFO devices, starts RT-tasks and enters the loop in which it reads and prints the data produced by RT-tasks. To run type make && make test
[root@pasrack3 rtl]# cd examples/frank [root@pasrack3 frank]# make [root@pasrack3 frank]# make test

. . . FIFO 2: Zappa FIFO 1: Frank FIFO 2: Zappa FIFO 2: Zappa FIFO 2: Zappa FIFO 1: Frank frank_app: now sending commands to stop RT-tasks

6.2. Floating Point The second example illustrates the use of oating point arithmetic in real-time tasks. The program in fptest.c is meant to test the user mode FP operations while the RT system is running.

12

Phil Whilshire et al.

[root@pasrack3 frank]# cd examples/fp [root@pasrack3 rtl]# make all [root@pasrack3 rtl]# cp rtprocess.o fptasks.o

. . . bug in Makele

[root@pasrack3 fp]# make test

insmod fp_tasks.o ./fptest

[root@pasrack3 fp]# lsmod

Module fp_tasks rtl_fifo rtl_posixio rtl_sched rtl_time 3c59x

Size 892 5944 6952 35364 8424 19176

Used by 0 (unused) 0 (unused) 0 [rtl_fifo] 0 [fp_tasks rtl_posixio] 0 [fp_tasks rtl_sched] 1

. . . NOTE: no .o extension

[root@pasrack3 fp]# rmmod fptasks

6.3. HELO SMTP SPOKEN HERE This is probably the simplest RTL program (and it has absolutely nothing to do with mail programs and such, which the title might imply . . . ;). Type make test to run it. As usual, you have to be at a Linux console (no X) to see the results.
[root@pasrack3 fp]# cd ../hello [root@pasrack3 hello]# make [root@pasrack3 hello]# make test

This is the simplest RTL program First we remove any existing rtl-modules You may see error warnings from "make" -- ignore them Type <return> to continue rmmod sound rmmod: module sound not loaded make: [test] Error 1 (ignored) rmmod rt_process rmmod: module rt_process not loaded make: [test] Error 1 (ignored) rmmod frank_module rmmod: module frank_module not loaded make: [test] Error 1 (ignored) (cd ../../; ./rmrtl) Now insert the fifo and scheduler Type <return> to continue

RTLinux Installation Manual

(cd ../../; ./insrtl) Now start the real-time tasks Type <return> to continue Now lets stop the application Type <return> to finish

13

module

6.4. Measurements This example tests the scheduling accuracy. The relevant les are rt_process.c and monitor.c. Run make test to try it out.
[root@pasrack3 hello]# cd ../measurements [root@pasrack3 measurements]# make [root@pasrack3 measurements]# make test C

min: 9152, max: 17632 make: *** [test] Interrupt

min: Is the minimum rt-task latency (how much time a task ran late) in nanoseconds during a measurement cycle. max: Is the maximum. The jitter is max-min. You can change several module parameters in rt_process.c. For example, try:
[root@pasrack3 measurements]# insmod rtprocess.o minimizejitter=1

Other interesting parameters are: period: period in milliseconds; default = 1000000 minimize jitter: if non-zero, schedule interrupts to occur early to reduce jitter; default = 0 latency oneshot: how much time to schedule interrupt in advance; default = 25000 This schell script example will show you the histogram of the jitter.
#!/bin/sh ./monitor > m.out & sleep(25) ./histplot m.out m.res cat m.res

14 7. Document Revision History

Phil Whilshire et al.

11 Nov 1999, Phil Wilshire: Original version Hope this helps. 23 Feb 2000, Victor Yodaiken: Modied for RTLinux 2.2 17 Mar 2000, Joachim Nilsson and Daniel Rytterlund: Conversion to RTLDOC & additions. Acknowledgments. References
A Daly, P. N. et al. (2000). RTLDOC L TEX 2 Template and Style File. realtimelinux.org/documentation/rtldoc.pdf.

Linux is a registered trade mark of Linus Torvalds.

http://www.

Ward, B. (1999). The Linux Kernel HOWTO. Kernel-HOWTO.html.

http://www.linuxdoc.org/HOWTO/

Yodaiken, V. and Barabanov, M. (1999). RTLinux Version Two. http://www.rtlinux.com/ archive/design.pdf .