Last updated:

$Date: 2002/11/25 20:24:19 $

7. What is RTEMS

RTEMS is an open-source real-time multi-tasking embedded executive. Open-source means that you have access to the whole source code of RTEMS. Thus you can tailor it to your needs, use code from others, modify the code, distribute it. Your free in the sense of ``free beer'' as well as in ``freedom''. Multi-tasking means that RTEMS can do several things at a time, and if your familiar with a modern operating system like UNIX/Linux, Microsoft Windows or Mac OS X should be familiar (think multiple-process, or more accurately in the case of RTEMS multi-threaded). Real-time is a difficult to define concept. In the case of RTEMS it means hard real-time: a predictable worst-case latency. Embedded means that RTEMS is designed to be used in small systems, or systems with less or a different interaction from the user. Embedded systems are everything that old a computer inside, but don't look like an usual computer with a keyboard, a big display on a monitor, a hard drive. Example of embedded systems may be your cell-phone, a cash-register, your VCR. If you've done some embedded or real-time work before, these concepts should be familiar.

The ``executive'' part of my first sentence may be trickier. Read ``executive'' as you may read ``operating system''. So what's the difference? Contrary to an operating system, an executive is linked to its application in a single binary executable. As a consequence, the executive (operating system) and its application do not have to sustain the burden of dynamically launch applications, which may imply manage a file system, a dynamic linker, multiple memory spaces (virtual memory). On the negative side, a crash of the application can also crash the whole executive. But on the positive side, as a consequence an executive can be much smaller and faster than a usual operating system. Conclusion: cheaper hardware for the same level of performances. RTEMS can run in a few tens of kilobytes. Classic example of executive are iRMX from Intel, or VRTX from Ready System. More contemporary examples may include eCOS from Cygnus/Red Hat or Micro-C/OS-II from Labrosse.

The good points about RTEMS are its open-source license, its small footprint, its level of maturity (RTEMS has passed version 4.5 after years of development) and above all its GNU/gcc base. RTEMS is based on the gcc (as GNU compiler collection) development tool-chain. By using it, you instantly benefit from gcc-s assets:

What part of "time spend on gcc is time well spent'' didn't you understood?

Cross-development, mature and widespread, free, standard compliant, good support, what would you want more?

If you know other serious alternatives with such features please contact me (, I'm very much interested. Serious.
Furthermore, For more information about rtems, see OAR site ( OAR is the company responsible for RTEMS's development. The FAQ is available here (

8. Install RTEMS

8.1 Introduction

8.1.1 Goals

This is a unofficial micro HOW-TO install and build rtems.

This document will help you to install rtems on your host system for the UNIX BSP plus a specific target BSP. The process is quite straightforward and should not take more than an hour (plus download time).

It was inspired by "RTEMS on the MRM332", (c) 2002 by Joel Sherrill:

This was the real starter when I first installed RTEMS. I hope to be more generic, still using a target BSP as an example, but also adding the UNIX port building procedures and a few hints.

The official documentation for this (``Getting Started with RTEMS for C/C++ Users'' or ``Getting Started with GNAT/RTEMS'') may be a bit confusing when just starting out and/or outdated. Nevertheless, you should read this official documentation afterwards, once you'll have a basic understanding of the system: it provide much more in depth information.

8.1.2 Prerequisites

I'll assume you have a UNIX based host, ideally a Linux one on Intel x86 with an RPM-based distribution. You should also have a basic knowledge of the configure/make/install steps and their meaning. This document also assume that you want an rtems install not only for your favorite BSP/target processor family but also for the UNIX target (simulation), in C/C++. Though lacking some features, the UNIX port is handy for learning RTEMS without the burden of a cross-development environment. Regarding the target BSP, the example given is for the efi332 BSP, an m68k (Motorola 68000) based board.

8.2 Check that you have enough spare space on your system

A cross-development environment takes a lot of disk space.

Rest assure nonetheless that you won't have to download the amount announced here: these are disk space after installation on a living system.

8.2.1 RTEMS source directory

You can't do much without this. That's around 95 MB.

8.2.2 RTEMS build directory

Size vary. For a full blown BSP with C++, network, and all bells and whistles: approximately 340 MB, among these 45 MB for the documentation (that you can remove from this build directory once you have installed them). Still, you will probably want two of these build directory (one for UNIX, one for your target). Think ahead that you'll need to keep this in your home directory, or a directory shared by a group of users.

The base tools, cross-development tools, library and documentation will be installed in /opt, and takes around 175 MB for one each target processor family.

8.2.3 Sum it up

95 + 295 + 295 + 175 = a round up total of 860 MB

Consider your partition setup versus this and again take notes that the most part, that is to say the sources and build directory will live in user space (your home directory for instance). Also think in advance that you may want to keep in sync with OAR RTEMS snapshot releases, this may mean CVS.

8.3 Select what to download

As mentioned before I'll take the example of Linux/PC and will install Intel x86 RPM packages, but you can use alien for a .deb based distro, and rest assure that all sources are at disposal in case of more exotic situations.

The precise names I mention here, as well as the version number, where the ones I found in March 2002. Of course, this is subject to changes. You should take the latest snapshot at your disposal, and the LATEST-xxx tools or TRUSTED-xxx.

You will find the file on OAR FTP site:
For example for the C/C++ tools (binutils, gcc/newlib):

note: during october 2002, OAR made some changes:
http access to their ftp files is now possible:
The documentation from the latest snapshot is now available online. Do use it at:
Finally, you can now find a CD image here:

8.3.1 The basic tools


There can be a misconceptions that autoconf and automake are needed in order to do the configure and make steps on source packages. This is not the case: these tools are needed by the maintainer and distributor of the sources, not by the user of these sources. If you intend to just run the configure script, not generate it for instance then you don't need autoconf. Furthermore, your Linux system probably have autoconf and automake already. On the other hand these two applications are quite versions dependent when working together. This, plus OAR providing these target independent packages in spite of the fact that they are provided by every Linux distribution lead me to the conclusion that they are mandatory. I may be wrong, information welcome on this point.

TODO: check if there's an RPM dependency between these and rtems-gcc

The binutils include the gas assembler and ld linker, silently called by gcc. gcc is, well, the GNU C Compiler and if you've read so far shall need no introduction. The newlib is a replacement C library for the glibc, more suitable for embedded work. gdb the GNU debugger may or may not be usable for your target board "as is". These and other RTEMS gdb packages are optional. Foe example I use so far a custom remote gdb for m68k.

8.3.2 Tools for you target processor

In my example:

8.3.3 RTEMS itself

RTEMS, as the real time executive to be compiled on your host with your application and then loaded and run on your target, is not distributed as an rpm but as sources in a bzip2 archive, always available from:
The naming schemes is:
For example the latest at the date of this writing is:
It's approximately 9 MB in size.

The base tools, plus tools for a target, plus RTEMS sources: a total to download, round up, of 20 MB.

Reminder: if you want to check what's an rpm for and where do its file go, issue:

rpm -qilp name_of_the_rpm.rpm
All OAR RPMs will install in /opt, except the documentation that goes cleanly in /usr/doc in an rtems sub-directory.

8.4 Install on your host

Reminder: to install an rpm, issue:

rpm -ivh name_of_the_rpm.rpm
These will check for dependencies first.

8.4.1 The basic tools

You should install first the generic, target independent tools if needed (see above):

Then proceed with the base:

8.4.2 Tools for you target processor

Same rpm -ivh command, with my m68k example target for:

Don't forget to edit your shell configuration files to have /opt/rtems/bin in your path, since this is where the tools have been installed. Still with the m68k example, you should see with your new path setup:

8.5 Building

8.5.1 Building for your target

In your home create an rtems directory, uncompress and untar the archive in it, this will make an rtems-ss-VERSION subdirectory holding the sources. I want to build for an efi332 board, so besides this rtems sources create a b-efi332i. This will be the build directory. Move in this build directory, and configure:

../rtems-ss-VERSION/configure [options]
More specifically, example here for the efi332 which is an m68k target:
../rtems-ss-20020301/configure --target=m68k-rtems --enable-rtemsbsp=efi332
This should takes less than 1 minute. Or even better, just a bit longer:
../rtems-ss-20020301/configure --target=m68k-rtems --enable-rtemsbsp=efi332 \
--disable-itron --enable-cxx --enable-tests --enable-docs --enable-networking
Explore rtems sources, README and configure script for available options. Try configure -help.

The latter example will enable the POSIX API (default), but not the ITRON API, enable C++, enable the test application suite, the docs (a must), and networking. Launch:
Wait a few minutes. Your build directory will grown up to 140 MB.

Reminder: this build directory now contain a config.status file, generated automatically by the configure step. It can be run (= it's a shell script) to recreate the current configuration again.

But don't do this! Once you're able to build with a bloated configure like described above:

Issue a make clean, then make again but this time logging the build. Keep this log for future reference (for instance: how many and what kind of warnings with a clean source tree for this full blow configuration).

Then do a make install, or at least a make install-doc. The documentation, as html, ps, pdf and xdvi will go in /opt/rtems/share/rtems/. Now, the build process you have gone through is long, and you probably don't want all the features you enabled in the configure options. Even just scanning through the doc sources to check the dependencies without rebuilding anything will consume some time for the make program.

So let's clean the build directory and make the build shorter with a more reasonable configuration:
../rtems-ss-20020301/configure --target=m68k-rtems --enable-rtemsbsp=efi332 \
--disable-itron --enable-tests
And then make again.

Where are the application files?

You will find some .exe files and your build rtems: these may be, depending on your target CPU, Intel HEX or Motorola SRECORD files. Such type of files are ASCII translation of addresses and binary code or data. You'll use this if you have a device programmer of some sort, and in production stage only. For daily code/debug cycle, you will want to use the .nxe files: these are elf object files with the debugging symbols. gdb handle this. For example, if your build directory is b-efi332:
b-efi332/m68k-rtems/c/efi332/tests/samples/hello/o-optimize/hello.nxe This hello.nxe is the classic "hello world" app, supposed to print on a serial port of your target.

8.5.2 Building for your UNIX host

Side by side with you rtems-ss-DATE and b-TARGET directories, create a b-unix directory and move to it. Then issue:

../rtems-ss-DATE/configure --target=i586-pc-linux --disable-itron \
--enable-tests --enable-docs --enable-cxx --enable-networking
Then make install if you which, but there's no real point on installing this: these are demonstration application and object code that you'll use from the build directory, not "real" programs.

Note that the exact target option may vary. I had to scan through the build log to see what was missing and made symlink between what RTEMS was looking for and my gcc tools. I built RTEMS-UNIX on other similar hosts without such problems (sorry, did not kept notes for this).

There's no *.nxe files for the UNIX port. The *.exe files are regular elf files. So that you can now try:
You should see:
Hello World
That's it, it runs.

8.6 Where to go from here

Essential readings among the various documentation that you installed in the steps above (look in your /opt/rtems/share/rtems/html/) are:

You should also perform and record the output of the various test suite to get an idea of where you start from. The sp (Single Processor) tests also uses most of rtems library and thus makes an excellent learning material.

For any remaining questions, first search on rtems user mailing list archive:

TODO - a chapter on ``Remote debugging''
TODO - a chapter on ``Doing an RTEMS board support package for your target''
TODO - Maybe a chapter with ``A few hints''

8.7 RTEMS BSP for NF300 board

For information on RTEMS, see:
OAR site (
For information on NF300, see the README file from this BSP:
Here you will find a patch adding an NF300 BSP to rtems 2002/03/01 snapshot (about 920 KB):
rtems-ss-20020301_nf300.patch.bz2 (
This patch was generated with:

LC_ALL=C TZ=UTC0 diff -Naur rtems-ss-20020301 \
rtems-ss-20020301_nf300 > nf300rtemsbsp.patch
My rtems-ss-20020301 directory being a clean RTEMS snapshot, and my rtems-ss-20020301_nf300 directory being the same snapshot with added support for the NF300 board.

To apply this patch:

Uncompress the patch, you'll obtain an 8MB patch file. With this patch side to side to a clean RTEMS source directory (snapshot 20020301), issue:
patch -Np1 -verbose < rtems-ss-20020301_nf300.patch
Now you can build for NF300, for example:
mkdir b-nf300
cd b-nf300
../rtems-ss-20020301/configure -target=m68k-rtems -enable-rtemsbsp=nf300 \
-disable-itron -enable-cxx -enable-tests -enable-networking
A few remarks: So it should run no more, no less than the efi332 BSP.

Additional info:

CVS tag and changelog from OAR's files have not been edited/deleted, autoconf/automake files have been edited by hand to provide the new make targets. Yes I know, the configure scripts and various should really be regenerated.

note: considering that OAR releases a new RTEMS development snapshot every two or three month, this BSP based on the 2002/03/01 snapshot is clearly outdated. My RTEMS tree is placed under CVS control, and it shouldn't be a big deal to update it. Thanks to the clear layout of RTEMS source tree, it isn't a big deal anyway. I did this kind of work three times already, it takes no more than a couple of hour. On the other hand, considering that this project is done on my spare time, I do not have ``a couple of hour'' to devote to such work for now, and would rather spend this time on drivers and application development or documentation. This would be update frenzy. If you are an NF300 owner, or for any valuable other reason you would like to see this BSP updated, please contact me. We'll sort this out.

9. RTEMS build system

So far you've build, and hopefully loaded and debug on your target some sample applications delivered with RTEMS source package.

In order to have a fully functional development environment, you still miss a convenient way to build your applications without touching rtems source tree (you don't want to do some dirty hacking in your source tree, don't you?). Such a build can be quite complicated in the link phase to say the less, unless you're an expert at GNU make, autoconf and automake. You don't need to have such an expert at hand: OAR provides a build system.

Furthermore, this build system is very convenient and well documented. The only thing to know is that it's not documented in the main user doc in /opt/rtems/share/rtems/ pointed above(TODO: send an rtems FAQ source patch about this?).

In opt/rtems/make/, you'll find a README. Read it. I won't go into much details here because all there is to know is in this README, but rather demonstrate it.

Everything rely on a single environment variable that you have to define, RTEMS_MAKEFILE_PATH. If you study a bit the templates makefiles, you'll see that it's relative to this path that the build system expect to find other makefiles, config files and libraries ready to be linked with your source code. For such files to be available when the build will need them, you must perform the install step for the BSP that you'll want to use. Let's say, to continue our example, for the efi332 and UNIX BSPs. You don't want to do such install every other day, so you can do this with the more bloated configuration that you can think about so that libraries ready to be linked will be ready to use once for all: -enable-cxx and -enable-networking are good candidate even if you don't think you'll be using these features for a while.

Once you've done such install for the UNIX BSP and your target BSP (example efi332), you'll find:

These are the directories where your environment variable RTEMS_MAKEFILE_PATH should point to, according to the target you want to build for.

Put this to use. In your home working directory, create a tree like this copying the sources from the 'hello' sample of the RTEMS sources.
`-- my_hello
    |-- init.c
    `-- system.h
Now copy the templates makefiles from /opt/rtems/make/Templates:
|-- Makefile.dir
`-- my_hello
    |-- Makefile.leaf
    |-- init.c
    `-- system.h
Rename these makefiles and edit them according to the build system described in the README. That's to say, in the directory makefile the line:
And in the leaf makefile the lines:
Don't forget to clean up the lines where OAR states things like ``add your local stuff here''. You end up with this:
|-- Makefile
`-- my_hello
    |-- Makefile
    |-- init.c
    `-- system.h
Now is the time to define our environment variable:
export RTEMS_MAKEFILE_PATH=/opt/rtems/m68k-rtems/efi332
You can now issue make and voilaà, you have a nice hello application build in an new o-optimize subdirectory, ready to load and run on your target. Want to change for an UNIX build?
make clean
export RTEMS_MAKEFILE_PATH="/opt/rtems/i586-pc-linux/posix
It's done.

If you've ever tried setting such a cross-development build system from scratch, you'll be glad OAR did this for us (truth to be said, if they didn't RTEMS would be very difficult to use at all). Enjoy.

10. Other

Here are some pieces of RTEMS information that don't fit in other sections but still may be useful.

10.1 An HTML tables of content for RTEMS single processor test suite

Save yourself a few keystrokes and wanderings in RTEMS sources using these tables of content.

What is it?

In the RTEMS documentation, RTEMS C User's Guide is RTEMS API reference manual. As a reference manual, it's not a tutorial showing RTEMS primitives in action on real applications. For this learning purpose, the sp (Single Processor) test suite in the source code of RTEMS itself is best suited, and said to "test 98% of RTEMS library". You'll need it also to understand the code layout that is supposed to be used (i.e. system.h, init.c, then probably some task_xxx.c files).

Of course you can explore randomly among these sp test source directory: each of them include a .doc file describing the features tested. Unfortunately, there is no central .doc file to use as a table of content when you're looking for something in peculiar.

Say you're looking for something about messages: this is demonstrated in the sp13 test.

The files below are simply concatenation of the sp test's .doc files, hence the table of content, in HTML. For each test a link allow a visit of the source directory.

Testing with Mozilla, Galeon, Konqueror, lynx, Netscape Navigator and MS Internet Explorer, some on Linux, Mac OS X or MS Windows raises the need for two files:

My advice: use lynx.

Furthermore, lynx display C syntax in color. Of the other navigator tested, only Konqueror do that.

Just save this files, put them above your RTEMS source directory, and browse (you may have to edit the path to your RTEMS sources). ,