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 :
- 0001-Soft-tracing-with-lttng-ust.patch
- 0002-Thread-fosi_internal-clean-free-of-names-and-zeroing.patch
- 0003-Thread-add-setName-method.patch
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 :
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 :
- http://www.eclipse.org/linuxtools/projectPages/lttng/
- http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide
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). ThePeriodicActivity
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), theActivity
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...