WARNING

THIS IS A WORK IN PROGRESS. Nothing is included in the main tree yet.

Orocos

Orocos is an open source toolchain that allow to create real-time robotics applications using modular, run-time configurable software components. It's almost written in C++.

It is free software distributed according to the terms of the GPL 3.0.

LTT in Orocos

The LTTng project aims at providing highly efficient tracing tools for Linux. We will use the Userspace module of LTT.

It allow to introduces tracepoints with rich context at a low performance cost. We would like to introduce the usage of such a tool in OROCOS.

This is an experimental feature which is currently submitted for inclusion in OROCOS. Comments for improvement are welcome.

This work is mainly developed and tested under Linux.

Installation

LTTNG

Get Userspace rcu from your package manager or from sources :

Build and install.

./configure --prefix=${PREFIX}
make
make install

Get Lttng-ust from your package manager or from source, or from git repo :

git clone git://git.lttng.org/lttng-ust.git

Build and install.

./configure --prefix=${PREFIX} LDFLAGS=-L${PREFIX}/lib CPPFLAGS=-I${PREFIX}/include
make
make install

Get Lttng-tools from your package manager or from sources, or from git repo :

git clone git://git.lttng.org/lttng-tools.git

Build and install.

./configure --prefix=${PREFIX} LDFLAGS=-L${PREFIX}/lib CPPFLAGS=-I${PREFIX}/include
make
make install

OROCOS

Get Orocos toolchain.

Get the patches :

Build RTT and OCL. In order to enable the traces, check that :

OS_THREAD_SCOPE is OFF (default)
OROBLD_DISABLE_LTTNG_UST is OFF (default)
Lttng_ust_INCLUDE_DIRS and Lttng_ust_LIBRARIES (in advanced) are set.

Description of changes

The trace initialisation is done in rtt/os/startstop.cpp if HAVE_LTTNG_UST is defined. The trace provider is instanciated once in this file because the TRACEPOINT_DEFINE and TRACEPOINT_PROBE_DYNAMIC_LINKAGE are defined, and the rtt/os/gnulinux/traces/lttng_ust.h tracepoint provider is included.

The trace invocation is done in rtt/os/Thread.cpp if HAVE_LTTNG_UST is defined. The tracepoints are declared thanks to the inclusion of rtt/os/gnulinux/traces/lttng_ust.h, and triggered by calling the tracepoint function.

When you launch your app, no traces will be activated, and no additional cost will be added by tracepoints.

The traces are implemented in an external library called orocos-rtt-traces-${OROCOS_TARGET}. This lib instanciate the tracepoint in rtt/os/gnulinux/traces/lttng_ust.c because TRACEPOINT_CREATE_PROBES is defined and the rtt/os/gnulinux/traces/lttng_ust.h tracepoint provider is included.

So in order to enable tracing you will had to LD_PRELOAD this trace library like this :

LD_PRELOAD=/path/to/liborocos-rtt-traces-${OROCOS_TARGET}.so ./your-app

Then launch a trace session :

lttng create
lttng enable-event -u -a
lttng add-context -u -t vpid -t vtid -t procname
lttng start
lttng stop
lttng destroy

That will create a trace in your $HOME/lttng-traces directory.

You can view traces with :

babeltrace --clock-seconds $HOME/lttng-traces/ust/*

The available context for userspace trace are procname, pthread_id, vpid, vtid. See :

http://lists.lttng.org/pipermail/lttng-dev/2012-June/018012.html

For more example on lttng-ust see :

the man page http://lttng.org/files/doc/man-pages/man3/lttng-ust.3.html
tests/demo directory of the project.

I haven't found any viewer for userspace traces. However, you can watch :

Exemple

Here is a sample component with a deployment script to run basic tests.

About the naming of threads

First of all, the thread name is not always directly mapped to the TaskContext names. Sometimes, there can be several TC that run on the same thread.

The Thread naming is a bit scattered in the rtt sources. For instance :

when you create a periodic task, it will probably use a PeriodicActivity (ocl/deployment/DeploymentComponent.cpp line 1973). The PeriodicActivity uses a timer thread instance (rtt/extras/PeriodicActivity.hpp line 226) that is used by all periodic activities with the same period (rtt/extras/TimerThread.cpp TimerThread::Instance line 66). So all activities, will have the same task name "TimerThreadInstance" :(
when you create a default activity (ocl/deployment/DeploymentComponent.cpp line 1969), the Activity ctor (rtt/Activity.cpp line 75) will name the tasm with the component name.
when you create a NonPeriodicActivity (ocl/deployment/DeploymentComponent.cpp line 1976), the Activity ctor (rtt/Activity.cpp line 75) will be called with the default argument for the name. So the task will always be named "Activity" :(
i haven't search what it does for other activities (SlaveActivity, FileDescriptorActivity, etc.).

With the provided patch, the threads are named at creation with the pthread_setname_np function. It allow to have thread names in the traces context and with some tools like top :

# top -H -p <pid>

TODO

check that the API stay the same with or without traces...