Next: 9 PIC Up: BOTZILLA PROJECT Previous: 7 Engineering advice Contents
Last updated:
$Date: 2002/11/25 20:24:19 $
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:
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:
http://www.oarcorp.com/~joel/rtems/mrm332.html
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.
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.
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.
You can't do much without this. That's around 95 MB.
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.
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.
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:
ftp://ftp.oarcorp.com/pub/For example for the C/C++ tools (binutils, gcc/newlib):
ftp://ftp.oarcorp.com/pub/rtems/snapshot/c_tools/LATEST_BINUTILS/
note: during october 2002, OAR made some changes:
http access to their ftp files is now possible:
http://www.oarcorp.com/ftp/
The documentation from the latest snapshot is now available online. Do use it at:
http://www.oarcorp.com/rtemsdoc-current/
Finally, you can now find a CD image here:
ftp://ftp.oarcorp.com/pub/rtems/cd-working
note:
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
In my example:
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:
ftp://ftp.oarcorp.com/pub/rtems/snapshots/rtems/current
The naming schemes is:
rtems-ss-YEARMONTHDAY.tar.bz2
For example the latest at the date of this writing is:
rtems-ss-20020301.tar.bz2
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.rpmAll OAR RPMs will install in /opt, except the documentation that goes cleanly in /usr/doc in an rtems sub-directory.
Reminder: to install an rpm, issue:
rpm -ivh name_of_the_rpm.rpmThese will check for dependencies first.
You should install first the generic, target independent tools if needed (see above):
Same rpm -ivh command, with my m68k example target for:
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=efi332This 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-networkingExplore rtems sources, README and configure script for available options. Try configure -help.
makeWait a few minutes. Your build directory will grown up to 140 MB.
../rtems-ss-20020301/configure --target=m68k-rtems --enable-rtemsbsp=efi332 \ --disable-itron --enable-testsAnd then make again.
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 makeThen 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.
./i586-pc-linux/posix/tests/hello.exeYou should see:
*** HELLO WORLD TEST *** Hello World *** END OF HELLO WORLD TEST ***That's it, it runs.
Essential readings among the various documentation that you installed in the steps above (look in your /opt/rtems/share/rtems/html/) are:
For information on RTEMS, see:
OAR site (http://www.oarcorp.com/)
For information on NF300, see the README file from this BSP:
README (http://botzilla.free.fr/rtems/README)
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 (http://botzilla.free.fr/rtems/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.patchMy 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.
patch -Np1 -verbose < rtems-ss-20020301_nf300.patchNow 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 makeA few remarks:
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:
|
`-- 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:
SUBDIRS=my_helloAnd in the leaf makefile the lines:
H_FILES=system.h C_PIECES=initDon'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/efi332You 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 makeIt's done.
Here are some pieces of RTEMS information that don't fit in other sections but still may be useful.
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:
botzilla@free.fr , http://botzilla.free.fr/