I posted a tutorial on the Silicon Valley HomeBrew Robotics Club Wiki entitled Installing Ubuntu With Real Time Patches On The PandaBoard. The tutorial explains how to compile a new kernel from source and test the latency of the OS. Instructions for installing Ubuntu from scratch are listed in my recent post on ozbotz.org.
Update October 9, 2014: The Homebrew Robotics Wiki is down. An archived copy of the tutorial from the Wiki is repeated below.
Installing Ubuntu With Real Time Patches On The PandaBoard
This tutorial describes how to install on the PandaBoard a version of Ubuntu with the real time kernel patches. The tutorial includes instructions for installing Ubuntu from scratch, compiling a new kernel from source, and testing the latency of the system with the real time patches.
To complete this tutorial, you need
- A PandaBoard.
- An SD card, preferably 16 GB or larger.
- A Linux build system.
- A way to access a command prompt on the PandaBoard. You have two choices:
- Connect your build system to the PandaBoard with a serial cable, and use a program such as minicom.
- Connect a monitor and keyboard to the PandaBoard.
Installing The TI OMAP4 Version Of Ubuntu
This section describes how to install the “preinstalled” version of Ubuntu for the TI OMAP4 processor, which is the processor on the PandaBoard. You can install either a desktop image or a server image. The desktop image contains the Gnome desktop manager, which enables you to use your PandaBoard like a PC. The server image does not include a window manager: interaction with the OS is through a command prompt. The server image is appropriate for a robot that doesn’t need the ovehead of a graphical desktop. This tutorial uses the server image. If you prefer to use the desktop image, replace “server” with “desktop” in the steps below.
To install the Ubuntu image, complete the following steps.
- Download the latest Ubuntu Texas Instruments OMAP4 preinstalled server image from http://cdimage.ubuntu.com/releases/11.10/release.
- Mount an SD card, and make note of the path to the mount point. It might look like /dev/sdc, for example. The last letter should be something other than an “a.” The /dev/sda node points to you primary drive; if you copy the Ubuntu image to /dev/sda, you will erase your drive.
- Write the Ubuntu image to the SD card by entering the following command:
sudo sh -c 'zcat ./ubuntu-11.10-preinstalled-server-armel+omap4.img.gz | dd bs=4M of=/dev/sdx ; sync'
- Replace /dev/sdx with the path to your SD card.
At this point, you have a clean version of Ubuntu on the SD card, but it needs to be configured, which you will do in the next section.
To configure Ubuntu, complete the following steps.
- Make sure you will be able to access a command prompt on the PandaBoard either by connecting a serial cable to the PandaBoard or by attaching a monitor, keyboard, and mouse.
- Inset the SD card containing the Ubuntu image into the PandaBoard.
- Apply power to the PandaBoard.
- When prompted, answer the Ubuntu configuration questions.
- Approximately five minutes after answering the last question, the PandaBoard will reboot and display a log in prompt.
- Note: There is a bug in the Ubuntu configuration that causes the configuration to start again after the reboot. If you are presented with the configuration questions again after the PandaBoard reboots, mount the sd card on your build system and delete the file /var/lib/oem-config/run.
- Verify that you can log in using the user name and password that you created during the configuration.
At this point, you have a functional version of Ubuntu running on your PandaBoard. If you don’t need real time behavior, you can stop reading this tutorial. In the next section, you will build a new kernel and apply the real time patches.
Building A New Kernel From Source
This section describes how to build a new version of the kernel that includes the real time patches.
To build the new kernel, complete the following steps:
- On your build system, create a new directory, and change to the directory.
mkdir src ; cd src
- Download to the current directory the 188.8.131.526-13 source from http://kernel.ubuntu.com/git?p=ubuntu/ubuntu-oneiric.git;a=snapshot;h=7bca30b176890e62ec0ff3fc3678e10459148111;sf=tgz.
- Extract the files from the tar file.
tar xvf ubuntu-oneiric-7bca30b.tar.gz
- Download to the current directory the real time patches: File:Patch-3.0.9-rt26.patch.doc. Rename the file to patch-3.0.9-rt26.patch.
- Extract the patch files.
gzip -d patch-3.0.9-rt26.patch.gz
- Download to the current directory the high-resolution timer patch: File:High-res-timer.patch.doc. Rename the file to high-res-timer.patch.
- Change to kernel source directory that you just extracted.
- Apply the real time patches.
patch -p1 < ../patch-3.0.9-rt26.patch
- Make sure there are no failing hunks.
- Apply the real time patches.
patch -p1 < ../high-res-timer.patch
- Correct an error in one of the source files by adding “#include <linux/cache.h>” to the file ./security/apparmor/sid.c.
- Download the .config file: File:Config.doc. Rename the file to .config. Don’t forget the dot before “config”.
- Start the menu-based configuration tool.
make ARCH=arm menuconfig
- In the configuration tool, change “Kernel Features —> Preemption Model” to Fully Preemptible Kernel and change “System Type —> TI OMAP Common Features —> Use 32KHz timer” to excluded (no asterisk).
- Exit the configuration tool. Save the new .config file when prompted.
- Compile the new uImage file.
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- uImage
- If necessary, change “arm-linux-gnueabi-” to the name required by your cross compiler.
- Compile the new module files.
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- modules
- “Install” the modules files in a directory called mymodules. You will copy the module files to the SD card later in this procedure.
INSTALL_MOD_PATH=./mymodules make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- modules_install
- Insert SD card into card reader on build system.
- Mount the partitions on the SD card. In the following commands, replace sdc with the actual path to the SD card partitions on your system.
sudo mkdir /media/1
sudo mount /dev/sdc1 1
sudo mkdir /media/2
sudo mount /dev/sdc2 2
- If the mount command fails, check if your OS automatically mounted the partitions when you inserted the SD card. If the OS did mount the partitions automatically, either unmount the partitions and remount them using the commands above or use the mounted paths instead of /media/1 and /media/2 in the following steps.
- Copy the uImage and the new modules directory to the SD card.
cp ./arch/arm/boot/uImage /media/1
cp -r ./mymodules/lib/modules/3.0.9-rt26 /media/2/lib/modules
- Unmount the SD card partitions.
sudo umount /media/1
sudo umount /media/2
At this point, the SD card contains a working version of Ubuntu for the PandaBoard with the real time patches. You can now remove the SD card from the build system and insert it into the PandaBoard.
Verifying That The Build Was Successful
To verify the successful application of the real time patches, insert the SD into the PandaBoard and apply power. Log in, open a terminal, and run “uname -r”. If the command returns “3.0.9-rt26,” you have successfully applied the real time patches.
To check the latency of the OS, run the cyclictest tool. You can download and build cyclictest by running the following commands:
git clone git://git.kernel.org/pub/scm/linux/kernel/git/clrkwllms/rt-tests.git cd rt-tests make
The output of cyclictest before applying the real time patches shows a latency of about 14 ms:
root@panda1:~# sudo cyclictest -t1 -p99 -n -i 100 -l 10000 policy: fifo: loadavg: 0.00 0.01 0.05 1/277 1542 T: 0 ( 1542) P:99 I:100 C: 10000 Min: 0 Act: 1701 Avg: 729 Max: 14157
The output of cyclictest after applying the real time patches shows a latency of 40 us:
root@panda1:~# sudo cyclictest -t1 -p99 -n -i 100 -l 10000 policy: fifo: loadavg: 1.62 1.59 0.70 1/308 1738 T: 0 ( 1738) P:99 I:100 C: 10000 Min: 11 Act: 12 Avg: 12 Max: 40
Many thanks to the members of the Robot Reference Platform mailing list and the linux-rt-users mailing list for providing valuable information that helped create this tutorial. In particular, thanks go to Bob Smith for creating the config file and to Sankara Muthukrishnan for creating the high-resolution timer patch. –Osman Eralp
If you have any questions about this procedure, please send a message to the RRP mailing list: http://groups.google.com/group/robotreferenceplatform. You can also track me (Osman) down at the HBRC main monthly meeting or SIG meeting.