Orocos RTT Frequently Asked Questions (FAQ)

Open RObot COntrol Software

8 November 2006

Revision History
Revision 0.113 Jan 2005PS
Initial version.
Revision 0.21 March 2005PS
Updated broken links and RTAI version info.
Revision 0.31 May 2005PS
Added 'Testing Orocos' section.
Revision 0.48 Nov 2006PS
Updated to Orocos 1.0
Revision 0.517 Nov 2006PS
Fixed wrong links.
Revision 0.63 May 2007PS
Updated to RTT 1.2

Abstract

This document provides answers to frequently asked questions (faq) about installing, configuration and usage of the Real-Time Toolkit.


Table of Contents

1. About Orocos
1. General Questions
Q: What is Orocos - Real-Time Toolkit ?
Q: Where can a find a quick overview of what features the Real-Time Toolkit currently has ?
Q: Where can I find the latest RTT documentation?
Q: Where can I find download and installation instructions?
Q: Where can I ask Orocos software related questions (even newbie questions) ?
Q: Where can I ask Orocos 'philosophical' questions ?
2. Configuring and Compiling Orocos RTT
Q: Where can I find the latest configuration instructions?
Q: Which Linux version should I use?
Q: Which RTAI version should I use?
Q: How should I configure my Linux Kernel?
Q: How should I configure RTAI?
Q: How can I configure the RTT ?
Q: What are the system requirements of Orocos RTT?
3. Testing Orocos RTT
Q: Where can I find a quick demo application ?
Q: Why doesn't the demo application compile ?
4. Run-time Problems/Crashes with Orocos RTT
Q: The first message I get is 'Segmentation fault' !
5. Run-time Problems with RTAI/LXRT
Q: The first message I get is 'Segmentation fault' !
Q: Orocos RTT hangs after the first threads are created !
Q: The first message I get is 'LXRT NOT INITIALISED IN THIS THREAD pid=1234, BUT TRIES TO INVOKE LXRT FUNCTION >>rtos_mutex_init<< ANYWAY'. What did I do wrong ?
Q: The real-time performance is Terrible !
Q: make check crashes my (RTAI) system. What did I do wrong ?
6. Orocos Design Questions
Q: Does Orocos run on Embedded Systems ?
Q: Is the Orocos RTT Portable ?
Q: What future ports are most likely ?
Q: What is the overhead of all this C++, can it be real-time ?

1. General Questions

Q: What is Orocos - Real-Time Toolkit ?
Q: Where can a find a quick overview of what features the Real-Time Toolkit currently has ?
Q: Where can I find the latest RTT documentation?
Q: Where can I find download and installation instructions?
Q: Where can I ask Orocos software related questions (even newbie questions) ?
Q: Where can I ask Orocos 'philosophical' questions ?

Q:

What is Orocos - Real-Time Toolkit ?

A:

Orocos stands for Open Robot Control Software and was a EU funded project to write Free Software for robots. This FAQ is about the Real-Time Toolkit library for writing hard real-time control applications in C++. It supports hard real-time RTAI/LXRT and Xenomai and normal GNU/Linux programs.

Q:

Where can a find a quick overview of what features the Real-Time Toolkit currently has ?

A:

In the Orocos in 3 slides Overview Presentation.

Q:

Where can I find the latest RTT documentation?

A:

In the Manuals Section of the Orocos website, you can find all on-line documents (and this FAQ). Also, the RTT Documentation Section contains links to the manuals.

Q:

Where can I find download and installation instructions?

A:

In the Download Section of the Orocos website and the Orocos Installation Manual.

Q:

Where can I ask Orocos software related questions (even newbie questions) ?

A:

On the Orocos-dev mailing list (medium traffic) or the forum.

Q:

Where can I ask Orocos 'philosophical' questions ?

A:

On the Orocos mailing list (very low traffic ).

2. Configuring and Compiling Orocos RTT

Q: Where can I find the latest configuration instructions?
Q: Which Linux version should I use?
Q: Which RTAI version should I use?
Q: How should I configure my Linux Kernel?
Q: How should I configure RTAI?
Q: How can I configure the RTT ?
Q: What are the system requirements of Orocos RTT?

Q:

Where can I find the latest configuration instructions?

A:

In the Orocos RTT Installation Manual.

Q:

Which Linux version should I use?

A:

The RTT works with vanilla Linux 2.4 and 2.6 kernels.

Q:

Which RTAI version should I use?

A:

The RTT works with RTAI 3.0r5 ( you need to apply a patch if you use 3.0r(1-4) ), RTAI 3.1, 3.2, 3.3 and 3.4 (no patching required).

Q:

How should I configure my Linux Kernel?

A:

Disable anything that is remotely 'Experimental' or not necessarily needed. The following Linux options must be disabled to guarantee the most stable performance:

  • Disable APM / ACPI. These can interfere with scheduling and RTAI.

  • Disable MTRR. This can interfere when using RTAI.

  • Disable CONFIG_REGPARM. This option causes BIG problems when using LXRT, and renders it completely unusable all together.

The following Linux options must be enabled to guarantee the most stable performance:

  • Enable your USB driver ( or disable USB in your BIOS ). The aim of using a Linux USB driver is to disable the BIOS USB driver.

  • Enable your IDE chip-set and choose the correct CPU. Wrong settings for one of these will cause lock-ups.

Q:

How should I configure RTAI?

A:

The following RTAI options must be enabled (and modules must be loaded):

  • LXRT scheduler (rtai_hal+rtai_lxrt)

  • Semaphores (rtai_sem)

  • FPU Support

  • RealTime Memory Manager (with vmalloc)

Q:

How can I configure the RTT ?

A:

Use the cmake .. command in your build directory , which will pop-up the configuration menu. See the the Installation Manual .

Or, use ../configure --help in your build directory for configuring only basic options.

Q:

What are the system requirements of Orocos RTT?

A:

For compiling the RTT, you need a very fast machine with minimum 256MB RAM, and 512MB RAM to be comfortable.

A:

For running a full-featured Orocos application, you need an Intel Pentium-like or PowerPC processor with minimum 32MB RAM if all options are enabled, but much depends on the application itself.

3. Testing Orocos RTT

Q: Where can I find a quick demo application ?
Q: Why doesn't the demo application compile ?

Q:

Where can I find a quick demo application ?

A:

You can download the Orocos Component Library (OCL), install it and check out the examples you can download on the Orocos RTT page as well.

Q:

Why doesn't the demo application compile ?

A:

Did you read the README ? Did you install Orocos in /usr/local/orocos ? Otherwise, set ORO_PATH to the correct location in the Makefile or specify it in make ORO_PATH=/path/to/install

4. Run-time Problems/Crashes with Orocos RTT

Q: The first message I get is 'Segmentation fault' !

This section covers 'general' causes of crashes. If you are using RTAI, also check out the next Section.

Q:

The first message I get is 'Segmentation fault' !

A:

Maybe you are mixing C++ libraries or compiler versions. In this case, the linker shows a warning, which most users ignore though. In order to check if your libraries are correctly setup, do:

$ cd build/tests;
$ ldd core-test
        linux-gate.so.1 =>  (0xffffe000)
        libcppunit-1.10.so.2 => /usr/lib/libcppunit-1.10.so.2 (0xb7f54000)
        libdl.so.2 => /lib/tls/i686/cmov/libdl.so.2 (0xb7f4f000)
        libpthread.so.0 => /lib/tls/i686/cmov/libpthread.so.0 (0xb7f3c000)
        libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0xb7e56000)
        libm.so.6 => /lib/tls/i686/cmov/libm.so.6 (0xb7e33000)
        libgcc_s.so.1 => /lib/libgcc_s.so.1 (0xb7e28000)
        libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7cfa000)
        /lib/ld-linux.so.2 (0xb7fcc000)

You should only see one libstdc++ library listed, thus if you see:

  ....
        libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0xb78a9000)
        libgcc_s.so.1 => /lib/libgcc_s.so.1 (0xb789e000)
        libc.so.6 => /lib/tls/i686/cmov/libc.so.6 (0xb7770000)
        libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0xb76b6000)
        ....

the double occurence of 'libstdc++' is the cause of the crash.

Compile all your libraries (cppunit, Orocos,...) with the same compiler.

5. Run-time Problems with RTAI/LXRT

Q: The first message I get is 'Segmentation fault' !
Q: Orocos RTT hangs after the first threads are created !
Q: The first message I get is 'LXRT NOT INITIALISED IN THIS THREAD pid=1234, BUT TRIES TO INVOKE LXRT FUNCTION >>rtos_mutex_init<< ANYWAY'. What did I do wrong ?
Q: The real-time performance is Terrible !
Q: make check crashes my (RTAI) system. What did I do wrong ?

This section documents causes of crashes that only occur when you run Orocos for LXRT and disappear when you run the same program under GNU/Linux. See also the section above.

Q:

The first message I get is 'Segmentation fault' !

A:

Check if your rtai_lxrt and rtai_sem kernel modules are loaded and rtai_up is not loaded.

If that does not help, set

export ORO_LOGLEVEL=6

and send the output to the Orocos-dev mailing list.

Q:

Orocos RTT hangs after the first threads are created !

A:

Check if the LXRT user space tests work. Orocos should be compiled with the same compiler as RTAI and Linux. RTAI/LXRT is quite sensitive about the chosen compiler. Problems have been reported with Red Hat's GCC 3.4 compiler for example.

Q:

The first message I get is 'LXRT NOT INITIALISED IN THIS THREAD pid=1234, BUT TRIES TO INVOKE LXRT FUNCTION >>rtos_mutex_init<< ANYWAY'. What did I do wrong ?

A:

You tried to use RTAI's functions while RTAI was not yet initialised. This happens if you use global objects which contain Mutexes. Examples are Event and some DataObjects, Buffers and the Logger class. The solution is not to use global objects, but use global pointers and create the objects in ORO_main() with new.

A:

You did not put your program in the ORO_main() function. ( see The Installation Manual and The Orocos OS Manual. )

Q:

The real-time performance is Terrible !

A:

Well, that is not a question really, but anyway... Did you read the section about Priority Inversions in the RTT CoreLib Manual ?

A:

Are you calling Linux system calls from a hard-real-time thread ? See this document for what you can and can't do within hard-real-time LXRT tasks.

Q:

make check crashes my (RTAI) system. What did I do wrong ?

A:

The RTT test cases test the system to its limits and may crash RTAI if not properly configured. Especially RTAI 3.0 and older. Also, verify that the RTAI/LXRT (aka 'user space') test programs work before blaming Orocos. Choosing a different compiler ( GCC 3.3 ) mostly solves that problem.

6. Orocos Design Questions

Q: Does Orocos run on Embedded Systems ?
Q: Is the Orocos RTT Portable ?
Q: What future ports are most likely ?
Q: What is the overhead of all this C++, can it be real-time ?

Q:

Does Orocos run on Embedded Systems ?

A:

Orocos is targeted at 32bit or 64bit systems and can run on systems with < 1MB of RAM (for code&data & application code) although with reduced functionality.

Orocos has an 'Embedded Systems' flag which disables C++ exceptions in order to save in terms of memory footprint. However, this means that the 'Scripting' language of Orocos can not be used.

Orocos contains tiny XML for parsing XML scripts on embedded systems as well, but you can disable XML completely.

The Orocos Logger can be disabled at compile time to save on memory footprint.

Various parts of the Execution Engine can be disabled at compile time to save on memory footprint.

It can be cross compiled. See the installation manual..

Q:

Is the Orocos RTT Portable ?

A:

Orocos RTT runs on eCos, standard GNU/Linux, Xenomai and RTAI and supports cross-compiling. For eCos, you need to create a specially crafted C++ GNU tool chain, see libstdc++ for eCos.

A:

The minimum requirements for running the RTT on a different target are for the CPU: floating point unit (FPU) or FPU emulation (will degrade performance), compare-and-swap instruction ( CAS, cmpxch ), and is targeted at 32 or 64 bit processors. The target Operating System (OS) must support the GNU C/C++ compiler with the Standard Template Library, periodic threads, semaphores and recursive mutexes.

The RTT has a very thin wrapper around the above OS functions in the 'OS' package, this is the only place of the RTT you need to port, where the 'gnulinux' package is a good starting point if you intend to port to a POSIX compliant OS. See also The OS Reference.

Q:

What future ports are most likely ?

A:

The Orocos developers are very willing to assist you in porting the RTT to your Operating System.

Q:

What is the overhead of all this C++, can it be real-time ?

A:

C++ is a fundamental pillar of Orocos' design. If you need to be convinced that this actually works, take a look at Demonstration movies , and read a Technical Report on C++ Performance , but Google can point you to lots more documents. We are still finding ways to measure the overhead of using Orocos itself, and much depends on the application, but the minimum system requirements to run it are a Pentium-class processor or PowerPC with 32 MB of RAM.

1. About Orocos

Please your Orocos questions to orocos-users at lists.mech.kuleuven.be .

These pages are maintained by the Orocos team.

For questions related to the use of the Orocos Software, please consult these web pages and the Orocos RTT manuals. If that fails, the Orocos-dev at lists.mech.kuleuven.be mailing list might help. Please send comments on these web pages and the development of Orocos to our developer mailing list at Orocos-dev at lists.mech.kuleuven.be . All of our lists have public archives ( dev public archive ) .

Copyright (C) Peter Soetens, FMTC

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.