LinuxCNC Documentation Wiki: RtaiSteps

Step by step instructions for patching and installing a Realtime kernel. These instructions work verbatim on fedora core 3, but should work on almost any Linux distribution without too much effort.

Based mostly on the Kernel-Build-HOWTO found at http://www.digitalhermit.com/linux/Kernel-Build-HOWTO.html and on tldp.org if you're lucky. Also see "installing RTAI 3.0" at http://www.fdn.fr/~brouchou/rtai/rtai-doc-prj/installation-guide.html

This document assumes a fast internet connection and some basic knowledge of Linux.. If you don't already have a system up and running that you need to install emc on, you should go with the BDI distro instead, even if you already know how to do all of this in your sleep.

Get the Kernel and RTAI Sources

You need to get the "vanilla" kernel source code:

Download the latest tarball from: http://download.gna.org/rtai/testing/v3/ - These are the official RTAI releases.

For current stable "Testing", use cvs to checkout the vesuvio module from https://gna.org/cvs/?group=rtai or magma if you want the latest kernel support. Check in <rtai>/base/arch/i386/patches to see which kernels are supported. Modify the remainder of the instructions below to suit. [Side Note] The magma and vesuvio branches underwent some serious breakages between Dec. 4th and Dec. 12th 2005 in preparation for an rtai-3.3 release. IF you used CVS between these date, start again.

On no account use any patches from www.adeos.org - The RTAI team modify the adeos patches and have introduced some Incompatibilities.

cd /usr/local/src/
sudo chmod a+rwx .
wget http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.10.tar.bz2

and its signature:

wget http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.10.tar.bz2.sign

and RTAI and the associated kernel patches:

wget http://www.aero.polimi.it/RTAI/rtai-3.2.tar.bz2

and a bunch of other stuff:

sudo apt-get update
sudo apt-get install cvs gcc-c++ gcc ncurses-devel pciutils-devel tk-devel tcl-devel gtk+-devel

(note: i didn't install gcc-2.95)

Now verify that the kernel sources arrived intact:

gpg --keyserver wwwkeys.pgp.net --recv-keys 0x517D0F0E
gpg --verify linux-2.6.10.tar.bz2.sign linux-2.6.10.tar.bz2

(well, this didn't work for me, but it ought to dammit!)

Unpack the kernel and rtai patches:

bunzip2 linux-2.6.10.tar.bz2
tar -xf linux-2.6.10.tar
bunzip2 rtai-3.2.tar.bz2
tar -xvf rtai-3.2.tar

Compiling a Test Kernel

It is a good idea to see if you can compile a straight vanilla kernel first just to make sure it works, before attempting to compile one with RTAI support. Let's do this now.

First, configure the kernel. This is a subject in its own right. Suffice to say, I left most values at their default settings. (xconfig will try to use the settings of your current kernel)

cd linux-2.6.10
make xconfig

turn off ACPI, APM, CPU frequency scaling, module versioning (under general setup,) make sure CONFIG_REGPARM (under firmware drivers) is not on - it wasn't even there when I looked, save, and close the window.

make dep   ;#(depreciated? well, can't hurt)
make clean

Compile the kernel:

make bzImage

(This took 10 minutes on my 900MHz Duron)

ls -l arch/i386/boot/bzImage

You should see something like:

-rw-r--r--  1 blipkowi users 1563617 Jun  6 01:01 arch/i386/boot/bzImage

Otherwise, you are going to have to use your brain! Now, build and install the modules:

make modules   ;#(46 minutes)
su -
make modules_install
mkinitrd /boot/initrd-2.6.10.img 2.6.10

Install the new kernel:

cp arch/i386/boot/bzImage /boot/bzImage-2.6.10
cp System.map /boot/System.map-2.6.10
ln -s /boot/System.map-2.6.10 /boot/System.map

I edited my /boot/grub/grub.conf file to look like this: (fenn: fix this crappy wiki formatting please!)

# grub.conf generated by anaconda
#
# Note that you do not have to rerun grub after making changes to this file
# NOTICE:  You have a /boot partition.  This means that
#          all kernel and initrd paths are relative to /boot/, eg.
#          root (hd0,0)
#          kernel /vmlinuz-version ro root=/dev/hda2
#          initrd /initrd-version.img
#boot=/dev/hda
default=1
timeout=5
splashimage=(hd0,0)/grub/splash.xpm.gz
hiddenmenu
title Fedora Core (2.6.9-1.667)
        root (hd0,0)
        kernel /vmlinuz-2.6.9-1.667 ro root=LABEL=/1 rhgb quiet
        initrd /initrd-2.6.9-1.667.img
title Test Kernel (2.6.10)
        root (hd0,0)
        kernel /bzImage-2.6.10 ro root=LABEL=/1
        initrd /initrd-2.6.10.img

That's it for installing the plain kernel. Let's reboot and see if it works! If it doesn't work, you can always boot from the old kernel. Also, make sure your CD drive is empty, as it can be annoying if it tries to boot from a CD instead of your kernel. If you manage to really screw up your grub.conf and are locked out of your system completely, you can still edit it in "rescue mode" with the disc that came with your distribution.

Patching the Kernel

Okay, I'm assuming you're now reading this with your new kernel running. Now it's time to patch the kernel sources with RTAI. You kept the original .tar of your kernel sources as a backup, right? Well, if not, then now's a good time to back up the source tree.

cd /usr/local/src/linux-2.6.10
make clean
cd ..
tar -zcvf linux-2.6.10.tar.gz linux-2.6.10/

Let's patch the kernel! (finally)

mv linux-2.6.10 linux-2.6.10-adeos
cd linux-2.6.10-adeos
patch -p1 < ../hal-linux-2.6.10-i386-r9.patch   [N.B.] Use the latest patch from rtai/base/arch/i386/patches/

Now, compile the kernel as usual. (I wanted to wait until after compiling RTAI to do this, since compiling the kernel takes forever, but the automatic RTAI configuration script assumes that you're compiling on the kernel you want to run on, so we have to wait until we get the patched kernel running to compile RTAI.)

cd /usr/local/src/linux-2.6.10-adeos
make xconfig  ;#(make sure ACPI, APM, and module versioning are off)
make bzImage
make modules
su
make modules_install

Install the new kernel as before...

mkinitrd /boot/initrd-2.6.10-adeos.img 2.6.10
cp arch/i386/boot/bzImage /boot/bzImage-2.6.10-adeos
cp System.map /boot/System.map-2.6.10-adeos
ln -s /boot/System.map-2.6.10-adeos /boot/System.map

Edit /boot/grub/grub.conf as follows: (and make changes where necessary, i.e. which hard disk partition and default kernel choice)

echo "title RTAI Kernel (2.6.10-adeos)" >> /boot/grub/grub.conf
echo "       root (hd0,0)" >> /boot/grub/grub.conf
echo "       kernel /bzImage-2.6.10-adeos ro root=LABEL=/1" >> /boot/grub/grub.conf
echo "       initrd /initrd-2.6.10-adeos.img" >> /boot/grub/grub.conf

Configure RTAI:

cd /usr/local/src/rtai-3.2/
make xconfig

change linux source tree to /usr/local/src/linux-2.6.10-adeos select "exit", and "yes," you wanna save the configuration.

Compile RTAI

make sure you're running a realtime kernel before you do this

su -
cd /usr/local/src/rtai-3.2/
make
make install

Now, test out RTAI:

cd /usr/realtime/testsuite/kern/latency/
./run

you should see a bunch of numbers... max_latency is the one we're interested in. You can compare your results to others found on http://issaris.org/rtai/

That's it! If you've got numbers, it means your RTAI is up and running. Now it's time for CompilingEMC2.

I followed these steps on FC4. I had to install compat-gcc-32 and compat-gcc-32-c++, and build the kernel, rtai, and emc2 with that compiler. EMC2 runs, but there's an unsolved problem where the keyboard stops working until I reboot. -- JeffEpler

another bug.. it seems udev deletes the shared memory device files <Not a bug - udev maintains a dynamic /dev, creating and deleting devices on demand.> ... this is confirmed by rebooting, and /dev/rtai_shm and /dev/rtf[0-9] disappear. a temporary fix to this problem is to re-make the device files, then tell udev not to delete them.

sudo (cd /usr/local/src/rtai-3.2/ ; make dev )
sudo cp -a /dev/rtai_shm /etc/udev/devices/
sudo cp -a /dev/rtf[0-9] /etc/udev/devices/

Check your locked memory limit

This is not strictly related to RTAI, but it's needed if you want to use EMC2 with a non-root user. Since the various parts of EMC2 communicates using shared memory, and since that's realtime shared memory it needs to be locked in ram (so that it will be NEVER swapped out by the system). Of course, real RAM is a precious resource (and locking memory uses it permanently) so there is a limit on how much of it a user can allocate.

The default on a bare system is 32 KB, a little on the low side... you can check the amount available using the limit command (by the way EMC2 usually needs about 1.1MB to work).

The symptom is an error during emc startup (as a common user) stating that it couldn't access shared memory (and to check if rtapi is loaded). During a strace it's identified by mmap2 returning EAGAIN (limits are the only way a mmap can fail with EAGAIN, so it is a definitive diagnosis).

On a PAM-based system you can fix this configuring a new limit for locked memory (without PAM it could be a LOT more difficult, depending on your login method):

First of all, check that you PAM config for your login method (usually in /etc/pam.d, it could be login, xdm, gdm or some other file - Debian for example keep a common file included by the other ones) contains a

session required pam_limits.so

that should be the default, but for a system built from the ground up who knows!

Then edit the configuration file proper, /etc/security/limits.conf. It's well commented but anyway what you need are two lines in it:

* soft memlock 10240
* hard memlock 10240

... which more or less says 'allows any user to lock in ram 10MB of memory'. After a new logon you should see (using limit) the new limit. If not, re-check the /etc/pam.d files to ensure that pam_limits is being used!