An RTEMS Application Framework - RKI

Building and Running an RTEMS Application

---

Introduction

In the previous entries, I described how to set up an RTEMS development environment for the Raspberry Pi on an Ubuntu 12.10 system, build RTEMS, and run a sample program on the Pi. This entry will describe how to build and run a more complicated application.

---

RTEMS Kernel Image

The name of my application is called the RTEMS Kernel Image or RKI. You may have noticed that RTEMS is hard enough to set up a development environment. Unless you are using the examples that can be downloaded, it can be a bit more work to put together your first standalone RTEMS application. Other real time operating systems such as vxWorks have the tools to configure and create a base "kernel image" for your processor card. This RKI project is an attempt to provide a similar environment. If nothing else, it will provide an example of how to put together an RTEMS application that consists of multiple C files.

---

Installation

If you have the arm-rtems4.11 tools installed, and the Raspberry Pi RTEMS BSP compiled and installed on your development machine, then this next step is pretty simple.

---

1. Clone my RKI git repository:

$ git clone http://github.com/alanc98/rki.git

---

2. Switch to the rki/build-arm-rpi directory

$ cd rki/build-arm-rpi

---

3. Edit the Makefile and adust the environment

In this case, I am using the same directories we used in the tool setup.

Set the following variables in the makefile

## ## paths for the RTEMS tools and RTEMS BSP ## RTEMS_TOOL_BASE=$HOME/development/rtems/compiler/4.11 RTEMS_BSP_BASE=$HOME/development/rtems/bsps/4.11

---

4. Now, just build:

$ make

You will end up with a binary file called rki.bin. Copy that to your SD card as kernel.img and you are ready to try it out.

For more details, see the readme file in the project, and spend some time checking out how the application is put together.

github RKI site

---

Whats next?

Eventually, I would like to see full perpheral support for the Raspberry Pi. We still need to add support for things like:

• SD Card support - Ability to mount, read, and write files

• USB and Network support

• HDMI Console Support

• Some sort of Graphics support - Could RTEMS use the GPU?

In addition, RTEMS has a few things on the horizon including a dynamic loader and support for porting BSD drivers.

Setting up an RTEMS Development Environment for Windows

---

Update

I have updated the windows setup with a set of newly built mingw32 toolchains for RTEMS. Now the arm-rtems tools match the ones I build with the RTEMS source builder tool. In fact, these mingw tools are compiled using the RTEMS source builder on FreeBSD. I’m pretty sure this would work on linux as well.

---

Introduction

In a previous entry, I described how to set up an RTEMS development environment for the Raspberry Pi on an Ubuntu 12.10 system. This entry will describe how to setup a similar environment on Windows 7 and/or Windows 8.

To have a working RTEMS development environment on Windows, you need a few development packages:

Windows Tools Needed

• A MinGW native GCC compiler for windows

• A collection of GNU build utilities known as MSYS

• One or more RTEMS MinGW cross compilers

Let’s look at each one of these:

---

1. MinGW

The MinGW project that provides the native x86 gcc compiler seems to be going through a transition. There are a few different MinGW projects:

MinGW Projects

• The original 32 bit MinGW

• The newer unrelated 64 bit Mingw-w64

• Other builds of the MinGW system such as: TDM-Dragon MinGW

I use the TDM-Dragon MinGW installation.

---

2. MSYS

To build RTEMS, you also need some Unix run-time tools to properly configure RTEMS with the automake/autoconf tools. These run-time tools are provided by a set of ports called MSYS. I use a package of these tools that include the automake/autoconf tools, git, make, a nice unix shell, etc.

---

3. RTEMS MinGW cross compiler

The RTEMS project provides MinGW RTEMS cross compilers for all of the architectures, including ARM. MinGW is a port of the GNU compiler to the native Win32 environment. You also need the RTEMS cross compiler for either Mingw or Cygwin. These are provided by the RTEMS project.

---

My Windows 7 RTEMS compiler setup

Here is exactly what I used to setup my Raspberry Pi RTEMS environment for Windows 7 64 bit:

1. The TDM-Dragon MinGW compiler

2. A pre-built Msys collection. This is a nice package because it includes git, which will be needed to check out RTEMS.

3. The RTEMS mingw arm-rtem4.11 compiler from the RTEMS project

Here is where I put everything:

Table 1. Directory Structure

Path	Description
C:\opt	The base directory for all Tools
C:\opt\mingw	Install directory for TDM-GCC Mingw
C:\opt\msys	Install directory for the msys bundle
C:\opt\rtems-4.11	Install directory for the RTEMS compiler tools

---

Installation

Do the following steps:

• Install TDM-MinGW in C:\opt\mingw

• Set the Windows system Path to include C:\opt\mingw\bin

• Unpacked the msys bundle into C:\opt\msys

• Set the Windows system Path to include C:\opt\msys\bin

• Edit the file c:\opt\msys\etc\fstab to include the following lines:

c:/opt/mingw /mingw c:/opt /opt

The fstab setup will make sure when you unpack the RTEMS tools, they will go in the right place.

Download the arm-rtems4.11 tools from the RTEMS project here: http://www.rtems.org/ftp/pub/rtems/people/chrisj/source-builder/4.11/mingw32/

I downloaded:

rtems-4.11-arm-rtems4.11-1.tar.bz2

These compilers are all updated often, and will change! You may need to re-download and unzip the compiler when it is updated.

I recommend putting the files you download in C:\opt so they can be uncompressed in the correct directory.

Unpack all of the files you downloaded To do this, open a command prompt, and run the bash shell:

sh

Your command prompt should change to this:

$

Change to the "opt" directory and unpack:

$ cd /c/opt $ tar -xf rtems-4.11-arm-rtems4.11-1.tar.bz2

When you are done, you should see all of the tools in C:/opt/rtems-4.11/bin

Set the Windows system path to include:

C:\opt\rtems-4.11\bin

So at this point your path should include:

c:\opt\mingw\bin;c:\opt\msys\bin;c:\opt\rtems-4.11\bin

I recommend putting these path entries at the start of the PATH environment variable, because msys "find" command is needed by the configure script. If these paths are at the end of the environment variable string, the windows "find" program will be used instead and the RTEMS configure tools will not work.

If you have everything set up correctly, you should be able to open a command prompt and type:

$ arm-rtems4.11-gcc -v

You should see the compiler version message. The compiler is installed and ready to use! If you are using the unix sh, then the commands will work the same way they do in linux. In fact, there is a nice program called "mintty" that provides a resizeable unix shell window. I have been able to use this mintty, the old DOS style command prompt and the Windows PowerShell to build code.

Next: Download and build RTEMS

Running your first RTEMS program on the Raspberry Pi

So now you have RTEMS compiled and installed, what about getting an RTEMS program to actually run on the Pi ?

In case you missed anything:

Introduction to RTEMS on the Raspberry Pi Setting up an RTEMS development environment for the Raspberry Pi Compiling and Installing RTEMS for the Raspberry Pi

Did you notice the enable-tests=samples option in the configure script? It compiled some examples for you. Lets get one ready to run on the Pi:

$ arm-rtems4.11-objcopy -Obinary \ $HOME/development/rtems/bsps/4.11/arm-rtems4.11/raspberrypi/lib/rtems-4.11/tests/ticker.exe kernel.img

Now you can copy the kernel.img file on your SD card and see if it works! Remember to back up kernel.img on your SD card before you copy this.

Currently, the RTEMS port for the Raspberry Pi uses the UART port for it’s console. You will need to get a USB UART cable like the following:

http://www.adafruit.com/products/954

If you are using Ubuntu you can use the “minicom” program to connect to the serial port. If you are using Windows, you can use a program such as: uCon

http://www.umonfw.com/ucon/

However you connect to the serial port, set the serial port to 115k baud and 8N1.

When you boot the Pi with the SD card containing your kernel.img file, you should see output like this:

*** CLOCK TICK TEST *** TA1 - rtems_clock_get_tod - 09:00:00 12/31/1988 TA2 - rtems_clock_get_tod - 09:00:00 12/31/1988 TA3 - rtems_clock_get_tod - 09:00:00 12/31/1988 TA1 - rtems_clock_get_tod - 09:00:05 12/31/1988 TA1 - rtems_clock_get_tod - 09:00:10 12/31/1988 TA2 - rtems_clock_get_tod - 09:00:10 12/31/1988 TA1 - rtems_clock_get_tod - 09:00:15 12/31/1988 TA3 - rtems_clock_get_tod - 09:00:15 12/31/1988 TA1 - rtems_clock_get_tod - 09:00:20 12/31/1988 TA2 - rtems_clock_get_tod - 09:00:20 12/31/1988 TA1 - rtems_clock_get_tod - 09:00:25 12/31/1988 TA1 - rtems_clock_get_tod - 09:00:30 12/31/1988 TA3 - rtems_clock_get_tod - 09:00:30 12/31/1988 TA2 - rtems_clock_get_tod - 09:00:30 12/31/1988 *** END OF CLOCK TICK TEST ***

The program should take 35 seconds to run.

Next: Building and running an RTEMS Application

Compiling and installing RTEMS for the Raspberry Pi

OK, The RTEMS compiler is ready to go on your Ubuntu machine, so it’s time to download and build RTEMS for the Raspberry Pi.

If you have not installed the compiler, then go back and follow that step

---

Step 1: Download and Prepare RTEMS:

Start by check out the RTEMS head build from the git repository

$ cd $HOME/development/rtems $ git clone git://git.rtems.org/rtems.git rtems-git

Before RTEMS can be built, the autotools scripts must be generated ( Don’t forget the ./ in front of bootstrap )

$ cd rtems-git $ ./bootstrap

Now, RTEMS is ready to build for the Pi. When you compile RTEMS, you choose the architecture, Board Support Package (BSP) and a few other options such as POSIX API, networking, etc. When you compile RTEMS in this next step, you are not really compiling something you run on the Pi just yet. You are compiling all of the operating system libraries, drivers, and installing them along with the headers. When you build your own RTEMS application, you will then use these headers and libraries.

---

Step 2: Configure RTEMS:

$ cd $HOME/development/rtems $ mkdir build-rtems-rpi $ cd build-rtems-rpi

To build RTEMS for the Raspberry Pi use the following command:

$ ../rtems-git/configure --target=arm-rtems4.11 \ --enable-rtemsbsp=raspberrypi \ --enable-tests=samples \ --enable-networking \ --enable-posix \ --prefix=$HOME/development/rtems/bsps/4.11

When this step is is complete you should see something like this:

target architecture: arm. available BSPs: raspberrypi. 'make all' will build the following BSPs: raspberrypi. other BSPs can be built with 'make RTEMS_BSP="bsp1 bsp2 ..."' config.status: creating Makefile

---

Step 3: Now, build and install:

$ make install

When the make and make install is complete, the RTEMS libraries, headers, and some sample programs are in:

$HOME/development/rtems/bsps/4.11/arm-rtems4.11/raspberrypi

All of these directories may seem a little complicated, but it starts to make sense when you want to have different RTEMS versions, different architectures, and different BSPs all on the same development machine, without getting anything mixed up.

So now you have a cross compiler, and have RTEMS compiled and installed, so what about getting an RTEMS program to actually run on the Pi ?

Next: Run an RTEMS program on the Raspberry Pi

Setting up an RTEMS development environment for the Raspberry Pi

For this tutorial, I’m going to use Ubuntu 12.10 64 bit (updated to 14.10 LTS on April 2014). It is possible to do RTEMS development on almost any recent version of Linux, OS X, FreeBSD, and Windows. The RTEMS project provides pre-built compilers for all RTEMS architectures for a number of different development hosts including Fedora, CentOS, Suse, and Windows.

In addition to the pre-built compilers provided, there is a tool called RTEMS Source Builder that can download, patch, build, and install the compiler for you. This is what we will use for our Ubuntu setup.

You will need a RTEMS compiler, an ARM bare metal GCC will not do. I have posted some instructions for setting up the environment for Windows 7 here The following instructions start with a fresh install of Ubuntu 14.10 LTS 64 bit, with all updates applied.

Install Ubuntu prerequisites:

$ sudo apt-get install build-essential $ sudo apt-get install git $ sudo apt-get install python-dev $ sudo apt-get build-dep binutils gcc g++ gdb unzip git

Decide where the RTEMS tools and projects will reside

Here is the directory structure we will be using:

Path	Description
$HOME/development/rtems	The base directory for all RTEMS work
$HOME/development/rtems/compiler	Where the compiler is installed
$HOME/development/rtems/rtems-git	Where the RTEMS source code is checked out
$HOME/development/rtems/bsps	Where the RTEMS board support packages/libs are installed
$HOME/development/rtems/rtems-source-builder	The RTEMS source builder tool

Table 1. Directory Structure

Lets get started on this:

$ cd $HOME $ mkdir development $ cd development $ mkdir rtems $ cd rtems $ mkdir compiler

Build the RTEMS ARM cross compiler

The RTEMS Source builder documentation is located here:
http://www.rtems.org/ftp/pub/rtems/people/chrisj/source-builder/source-builder.html

1. Check out the RTEMS source builder tool

$ cd $HOME/development/rtems $ git clone git://git.rtems.org/chrisj/rtems-source-builder.git

2. Double check that all source builder dependencies are present:

$ cd rtems-source-builder $ source-builder/sb-check

This command should return the following:

RTEMS Source Builder environment is OK

The separate autotools build is no longer needed. The source builder will install them for you.

3. Build and install the toolchain

$ cd $HOME/development/rtems/rtems-source-builder/rtems $ ../source-builder/sb-set-builder \ --log=build-log.txt \ --prefix=$HOME/development/rtems/compiler/4.11 \ 4.11/rtems-arm

After the full download and build process, the toolchain is installed in:
$HOME/development/rtems/compiler/4.11

This whole process can take about 10 to 30 minutes depending on your computer specs. This has been run on a Raspberry Pi: Expect that to take all day!

4. Add the toolchain bin directory to your path, and you are ready to download and build RTEMS:

$ cd $HOME

Using your favorite editor, edit the .profile file and add the following line at the end of the file

PATH=$HOME/development/rtems/compiler/4.11/bin:$PATH

5. Now, logout and log back in. Open a terminal and type:

$ arm-rtems4.11-gcc -v

You should see the compiler version message. The compiler is installed and ready to use!

Next: How to download and build RTEMS

RTEMS on the Raspberry Pi

---

What is the Raspberry Pi?

The Raspberry Pi is a neat little ARM SoC (System on a Chip) based computer that runs Linux and a growing number of small/embedded operating systems. There is a $25 model A with 256MB of RAM and one USB port. There is a $35 Model B that has 512MB of RAM, 2 USB ports, and a 10/100 ethernet port. The Pi runs Debian Linux from an SD card and provides a full desktop environment.

The Raspberry Pi was created primarily as a way of encouraging kids to learn how to program, but it has quickly been adopted by over a million people as an inexpensive embedded computer.

Find out more about it here: http://www.raspberrypi.org

---

What is RTEMS?

RTEMS stands for Real Time Executive for Multiprocessor Systems. RTEMS is an open source real time embedded operating system. RTEMS is similar to vxWorks in size and functionality. It has many features including a network stack, file systems, POSIX APIs and more. It runs on the x86, PowerPC, m68k/Coldfire, ARM, MIPS, SPARC, and AVR architectures. RTEMS is used in many embedded applications including quite a few satellites. I have used RTEMS on few satellites for my job.

More info about RTEMS is available here: http://www.rtems.org

---

RTEMS on the Raspberry Pi

Once I received my Raspberry Pi (of course, I had to have one), it was not too long before I looked at what it would take to get RTEMS working on it. Most of the boards I have used RTEMS on cost $200 or more, so the chance to have an RTEMS target that everyone could buy for $35 was pretty appealing to me.

There is a great community of coders on the Raspberry Pi forums, so I studied many of the samples from the Bare Metal programming forum over at raspberrypi.org

With some help from the RTEMS community I was able to put together a bare minimal BSP that runs on the Pi. It only supports the timer and the UART at this point, but it’s a good starting point. I hope that others can find it useful and over time we can add support for all of the devices on the Pi such as the USB, Network, SD Card, etc.

---

Trying out RTEMS on the Raspberry Pi

Getting an RTEMS development environment up and running can sometimes be a little bit of work. In the next few blog entries, I will walk you through setting up an RTEMS development environment and getting some simple RTEMS programs running on your Raspberry Pi.

Next: Setting up an RTEMS development Environment for the Raspberry Pi