Installing Linux and RT-Linux for the EMC

What is Linux?

Linux is a free Unix-type operating system originally created by Linus Torvalds with the assistance of developers around the world. Linux is an independent POSIX implementation and includes true multitasking, virtual memory, shared libraries, demand loading, proper memory management, TCP/IP networking, and other features consistent with Unix-type systems. Developed under the GNU General Public License, the source code for Linux is freely available to everyone.

For more information on Linux, including its history, commercial distributions, and products available for it, visit www.linux.org.

What is Real-Time Linux?

Real-Time Linux is an extension to Linux that handles time-critical tasks. RT-Linux shares a PC between a small hard-real-time kernel and standard Linux, so that the PC can be used for applications like data acquisition, control, and robotics while still serving as a standard Linux workstation.

For more information on Real-Time Linux, including projects around the world, visit rtlinux.cs.nmt.edu/~rtlinux.

Which Linux Should I Get for the EMC?

There are many distributions of Linux that you can buy, which save you the trouble of downloading and compiling the source code. If you have the patience, you can probably get just about any distribution to work with the EMC. However, we strongly recommend getting a distribution that has been tested either at NIST or by some other patient soul. The most important thing is to get a distribution with a tested version of the kernel and the corresponding real-time patch. The default version of the Real-Time Linux patch does not support floating-point calculations, which are required for the EMC. We have modified the Real-Time Linux patch to enable floating point. These modified patches are available here, or you can make the correction yourself as described in the Rolling Your Own section.

Linux Distribution Kernel Version RT-Linux Patch with FPU fix
Red Hat Linux 4.2 2.0.27 rtlinux-0.5a-fp.tgz
Red Hat Linux 5.0 2.0.32 rtlinux-0.6-2.0.33-fp.tgz
Linux Central Red Hat Linux 5.0 2.0.32 rtlinux-0.6-2.0.33-fp.tgz

Installation Instructions

This sections details installing Linux and Real-Time Linux, including the modifications necessary to run the Enhanced Machine Controller (EMC) using shared memory communication.

Materials required:

Installation Steps:
  1. Boot up the PC from the boot floppy accompanying your Linux distribution. If no such floppy came ready-made, you can build one following the instructions that came with your distribution. With Red Hat Linux, the dosutils\rawrite.exe on the CD-ROM is used. The program prompts for the destination floppy (e.g., A) and the disk image to be copied to floppy. The image to use is images\boot.img on the CD-ROM.
  2. Follow the installation instructions prompted by the boot program. If you have a manual, follow the printed instructions! After installation is complete, the computer will be rebooted. You should end up with a PC that boots Linux when it's powered up. If not, see the Troubleshooting section.
  3. Log in as "root", using the password you set up when you installed Linux. If you want, start X Windows via:
    startx
    
    If this doesn't work, don't despair. You can get this working later.
  4. Go to the base source directory.
    cd /usr/src
    
  5. Mount the floppy on which you have the Real-Time Linux .tgz patch file, copy the file over to the base source directory, and unmount the floppy. In the example below, the .tgz file is shown with a V for your version (e.g., 5, 6) and XX for kernel (e.g., 27, 33). Replace these with the actual numbers for your distribution and patch.
    mount /dev/fd0 /mnt/floppy
    cp /mnt/floppy/rtlinux-0.V-2.0.XX-fp.tgz /usr/src
    umount /mnt/floppy
    
  6. Unpack the Real-Time Linux patch. This will create the rtlinux directory corresponding to the version of the patch you selected, e.g., the directory rtlinux-0.V-2.0.XX/.
    tar xzvf rtlinux-0.V-2.0.XX-fp.tgz
    
  7. Go to the base linux source directory.
    cd /usr/src/linux
    
    Apply the Real-Time Linux patch by following the instructions in the README file located in the rtlinux directory. Capture the output to a file, so you can see if the patch worked. This will be something like:
    patch -p1 < /usr/src/rtlinux-0.V-2.0.XX/kernel_patch 1> patch.out 2> patch.err
    
    The patch.out file will contain normal diagnostic output; the patch.err file will contain errors. Inspect them for signs like "hunk #1 failed". All parts of the patch should have been installed with no failures. If you do have failures, it means that the kernel and patch don't match. Consult the Real-Time Linux web page rtlinux.cs.nmt.edu/~rtlinux for more information.
  8. Configure Linux by running
    make config OR make menuconfig
    
    If you are running X Windows (i.e., startx worked when you ran it after logging in), you can configure Linux by running
    make xconfig
    
    The configuration program will let you customize hardware drivers and other operating system components. Unless you know what you are doing, you can leave everything at their defaults.
  9. Create the dependencies and clean up the files in preparation for building the kernel.
    make dep ; make clean
    
  10. Build the kernel. This will take quite a while, and will generate lots of diagnostics output as the Linux and Real-Time Linux source code is compiled.
    make zImage
    
  11. Build the kernel modules, among which are the real-time scheduler and FIFO communication queues.
    make modules
    
  12. Install the kernel modules in the standard place Linux looks for them.
    make modules_install
    
  13. These two modules can be loaded automatically when you boot up by putting them in the local boot script, typically in /etc/rc.d/rc.local. You can put the entries at the end of the file, e.g.,
    # install RT-Linux modules
    insmod /lib/modules/2.0.XX/fs/rt_fifo_new.o
    insmod /lib/modules/2.0.XX/misc/rt_prio_sched.o
    
  14. Go to the directory in which boot information is stored. On Red Hat Linux distributions, this is /boot.
    cd /boot
    
  15. Copy the newly-compiled kernel to the boot directory, overwriting the original one.
    cp /usr/src/linux/arch/i386/boot/zImage /boot/vmlinuz
    
  16. Configure shared memory communication by editing /etc/lilo.conf, and adding a line specifying the amount of RAM to be used by Linux. This is a typical default entry in /etc/lilo.conf:
    boot=/dev/hda
    map=/boot/map
    install=/boot/boot.b
    prompt
    timeout=50
    image=/boot/vmlinuz
            label=linux
            root=/dev/hda1
            read-only
    
    Add a line after the last entry for the image, to specify an amount of memory 1 megabyte less than your total amount of physical memory. The extra 1 megabyte will be used for EMC communication. For a 32-megabyte system, this line is append="mem=31m", as shown in bold below:
    boot=/dev/hda
    map=/boot/map
    install=/boot/boot.b
    prompt
    timeout=50
    image=/boot/vmlinuz
            label=linux
            root=/dev/hda1
            read-only
            append="mem=31m"
    
    For a 64-megabyte system, this line is append="mem=63m", as shown in bold below:
    boot=/dev/hda
    map=/boot/map
    install=/boot/boot.b
    prompt
    timeout=50
    image=/boot/vmlinuz
            label=linux
            root=/dev/hda1
            read-only
            append="mem=63m"
    
    If you are interested in using shared memory for your own programming, see Using Shared Memory in Real-Time Linux for details.
  17. Run the Linux Loader (LILO) to configure the boot loader to use the new kernel and to boot with 1 megabyte of shared memory set aside.
    /sbin/lilo
    
  18. Reboot to run the new kernel.
    /sbin/reboot
    
  19. Log back in as root, and verify that the real-time modules loaded properly from the local boot script.
    /sbin/lsmod
    
    You should see something like this:
    Module         Pages    Used by
    rt_prio_sched      1            0
    rt_fifo_new        2            0
    
  20. Go to the Real-Time Linux test program directory.
    cd /usr/src/rtlinux-0.V-2.0.XX/testing
    
  21. Read the README file and create the special files for FIFO communication.
    mknod /dev/rtf0 c 63 0
    mknod /dev/rtf1 c 63 1
    mknod /dev/rtf2 c 63 2
    mknod /dev/rtf3 c 63 3
    
  22. Go to the 2-tasks testing directory and build the test example.
    cd /usr/src/rtlinux-0.V-2.0.XX/testing/2tasks
    make
    
  23. Now run the test example.
    /sbin/insmod ./rt_process.o
    ./app
    
    You should see something like this:
    FIFO 1: Frank 
    FIFO 2: Zappa 
    (more of the same)
    
If you got this far, congratulations! Linux and Real-Time Linux are installed and configured. Now you can go to the EMC software site and start on the next phase, building the controller.

Rolling Your Own

If you prefer to use a Linux distribution or Real-Time Linux patch other than those listed above, here are some things to keep in mind:
  1. The layout of your Linux distribution may differ from that assumed in the rtlinux.cs.nmt.edu/~rtlinux has a list of kernel versions and corresponding patches.
  2. Edit /usr/src/linux/kernel/rt_prio_sched.c and enable floating point in the init_module function by adding the line commented below:
    int init_module(void)
    {
      rt_tasks = &rt_linux_task;
      rt_current = &rt_linux_task;
      rt_linux_task.priority = RT_LOWEST_PRIORITY;
      rt_linux_task.next = 0;
      rt_linux_task.state = RT_TASK_READY;
      rt_linux_task.uses_fp = 1; /* ADD THIS LINE */
      rt_request_timer(&rt_schedule);
      return 0;
    }
    
    This tells the RT-Linux scheduler to save and restore the floating point registers when suspending and resuming the Linux kernel. You'll need to remake the modules, e.g.,
    cd /usr/src/linux
    make modules
    make modules_install
    

Troubleshooting

Things to do to get help: