PaRTiKle users manual

M. Masmano, I. Ripoll, A. Crespo

March 10, 2008

 Abstract

To be written.
Chapter 1

Introduction

1.1 PaRTiKle Overview

PaRTiKle is a new open source real-time kernel for embedded systems, distributed under the terms of the GNU
Public License. It is important to note that applications that use PaRTiKle system calls are not considered as
derived work ; therefore, PaRTiKle applications do not need to be GPL or even GPL compatible1 . It is also
royalty and buyout free. In short, PaRTiKle license schema is the same that the one used in the Linux kernel. If
you can write Linux applications then you can write PaRTiKle applications.
It is a full-featured, flexible, configurable, real time embedded kernel. The kernel provides thread schedul-
ing, synchronization, timer, and communication primitives. It handles hardware resources such as interrupts,
exceptions, memory, timers, etc.
PaRTiKle was designed to be POSIX compatible. The native API is “C” POSIX threads. But also, provides
support for C++, Ada and Java (tasking, synchronisation, protected objects, exception handling, etc.). Besides
POSIX compatibility, PaRTiKle also provides the RTLinux/GPL non-portable POSIX extensions; therefore, it
should be possible to compile RTLinux/GPL applications on PaRTiKle to get all the benefits.
PaRTiKle has been initially developed by the Real-Time Systems Group2 of the Universidad Politecnica de
Valencia3 , Spain.
PaRTiKle has been designed to support applications with real-time requirements, providing features such
as full preemptability, minimal interrupt latencies, and all the necessary synchronization primitives, scheduling
policies, and interrupt handling mechanisms needed for these type of applications.
At this moment, PaRTiKle is available for i386 processors and the runtime can be configurated for three
different execution environments:

• As a stand-alone system on a bare machine: The generated code (runtime plus application) can be executed
directly on i386 boards. See section 2.1.2 for GRUB configuration.

• As a Linux process: This environment is intented for testing purposes. The generated code is be executed
as a regular Linux process.

• As a XtratuM domain: XtratuM is an hypervisor that provides hardware virtualisation and allows to
execute several kernels (or run-times) concurrently. PaRTiKle can be built to be XtratuM aware and then
executed in a XtratuM domain.

The last execution environment provides an execution framework which is very close to that provided by
RTLinux/GPL, RTAI and Xenomai. In this case, applications written for RTLinux/GPL should run on Xtra-
tuM+PaRTiKle with minor modifications.

1 Although we recomend to use GPL.

2 http://www.gii.upv.es
3 http://www.upv.es

2
Chapter 2

PaRTiKle installation

2.1 System requirements

The development environment requires Intel architecture PC running Linux. Disk space requirements are minimal
(less than 1Gb).
Compiler and tools that are known to be needed:
• GCC 3.4 or 4.0 for kernel and “C” applications.
• GNAT 2005 compiler for Ada applications.
• C++ 3.4 (with 4.x is known not to work1 )
• Java 3.4 (with 4.x is known not to work for the same reasons that for C++).
• Make
• ncurses (5.0 or above).
• bash
Since it is not possible to test the compatibility of all the developing tools, bellow is a list of the tools/versions
used to build PaRTiKle. We use have used kubuntu 6.06.1. Note that since the Ada compiler is not included in
most distributions for legal reasons, it has to be downloaded from AdaCore2 .

Gnu C 3.4.6
Gnu make 3.81beta4
binutils 2.16.91
util-linux 2.12r
module-init-tools 3.2.2
Linux C Library 2.3.6
Dynamic linker (ldd) 2.3.6
Procps 3.2.6
Net-tools 1.60
Console-tools 0.2.3
ncurses-lib 5.0

Table 2.1: Summary of tools that are known to compile PaRTiKle.

Due to the rapid and continuous development of the GNU “C” compiler it is possible (and common) to have
installed and operative several compiler versions. By default, the path of the compiler used by PaRTiKle is
1 The DWARF support has been changed and is not backward compatible.
2 http://www.adacore.com/home/academia/gap

3
/usr/bin/gcc, which is a link to the actual executable. Many distributions let the responsibility of creating this
link to the user. You have to create the link with:
# ln -s /usr/bin/gcc-3.4 /usr/bin/gcc
Also if you have a Debian or Ubuntu distribution, then you can update the link with:
# update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-3.4 1
PaRTiKle can be downloaded from http://rtportal.upv.es/partikle.

2.1.1 PaRTiKle configuration

In the PaRTiKle directory, execute the configuration menu.
$ make menuconfig
In this menu you can configure:
The first option, Target, allows to select your target execution environment.
Enabling “Verbose Compiling” will display complete information during the compilation process. All that
output information is usually not needed except for developers. It is advisable to disable this option.
If you plan to debug your application with a run time code debugger then you have to enable “Debugging
support” option to add debugging symbols to the final executable.
If you select a language support, paths for compiler and linker has to be provided.

Figure 2.1: Configuration screen-shoots.

2.1.2 PaRTiKle building

PaRTiKle has to be compiled to generate the code for the selected configuration.
$ make

>> Target architecture: [xm_i386]:

..
>> Building the PaRTiKle kernel:
..........................
>> Building languages support:
> DWARF2 support: ...
> Ada support: ..

>> PaRTiKle done.

4
 The result of the compilation process is a file called core/partikle core.o that is an object file which contains
the kernel selected; and a set of libraries (user/ulibc/libc/ulibc.a, user/lang support/gcc/libgcc eh.a,
user/lang support/libsupc++.a, etc.) which depends on the selected languages.
Now you can test PaRTiKle by running some examples. To compile and build the example, follow these steps:
1. Go to user/examples/c examples folder.
2. Run the the make command.
3. The build process creates a file with named [example] .prtk for each example, which contains the PaRTiKle
kernel and the application example.
The way to launch the application depends on the target execution environment:
Stand-alone The PaRTiKle system is, in this case, a multi-boot compliant ELF file. Copy the file to the /boot
directory of the target machine; and add the following lines to the grub configuration file /boot/grub/menu.lst
(assuming that the folder /boot is located in the first partition of the first ATA disk):

title PaRTiKle
root (hd0,0)
kernel /boot/example.prk
boot

Then reboot the target computer and select the PaRTiKle boot target.
XtratuM domain The target Linux system has to be modified and recompiled to support XtratuM (the reader
is referred to the XtratuM installation instructions). The XtratuM module (xm.ko) has to be loaded before
PaRTiKle system can be launched. Use the loader.xm utility to load the PaRTiKle system (supposing
that XM variable points to the XtratuM directory):

# insmod $XM/xm.ko
# $XM/user_tools/xmloader/loader.xm example.prtk

Linux process In this case, the PaRTiKle application is a normal Linux executable:

# ./example.prtk

2.2 Application building

PaRTiKle provides a script, named ldkernel, to ease the building process of PaRTiKle’s applications. This
script syntax is:

$ ldkernel -f <output> <file1.o> [<file2.o> ...]

where <output> is the name of the target executable, and <file1.o>, <file2.o>, etc., are the object files
obtained when the application is compiled using GCC with the option -c.
The steps perfomed by this script are:

1. It links the application jointly with the user “C” library and the suitable run-time (the run-time is selected
depending on the language used to implement the application).
2. It turns every application’s symbol into a local symbol, except start user app.
3. Eventually, the script links the resulting object file together with the kernel object file to create the executive.

For example, to compile the example A (implemented in the file example.c), we should compile this file using
GCC with the next flags: The line that has to be issued to comple example.c is:

5
 FLAG Comment
-Wall enable all warning messages.
-O2 optimize for speed (advisable).
-c do not link (the ldkernel script will do it).
-fno-builtin do not use compiler builtin functions (cross compiling)
-nostdlib use only the PaRTiKle specific libraries.
-nostdinc use only the PaRTiKle include files.
-Dxm i386 declare the execution environment used.
-I<PaRTiKle> /user/ulibc/include use PaRTiKle includes.
-fomit-frame-pointer the frame pointer (EBP) is not needed.

# gcc -Wall -O2 -c -fno-builtin -nostdlib -nostdinc -Dxm_i386 \

-I<PaRTiKle>/user/ulibc/include \
-fomit-frame-pointer -o example.o example.c

The the application contains more than one source file, then each file has to be compiled separately and then
linked together with the ldkernel script.
After that, we invoke the ldkernel script as follows:

$ ldkernel -o example.prtk example.o

The result is a file named example.prk, ready to be executed in the selected execution environment. Figure 2.2
sumarises the whole process of building a PaRTiKle system.

Figure 2.2: Configuration screen-shoots.

Invoking directly the compiler is not the most convenient way to build an application. It is advisable to use
make (or other dependency manager) to build complex. You can use the following Makefile as a template:
1 ##################################################################
2 # Customisable section #
3 ##################################################################
4
5 #### Name o f t h e t a r g e t f i l e .
6 TARGET := a p p l i c a t i o n . p r t k
7
8 #### Path t o t h e PaRTiKle r o o t ( i t can be r e l a t i v e or a b s o l u t e )
9 PaRTiKle PATH := . . / . . / . . / . . / p a r t i k l e
10

6
 11 #### A l l t h e ‘ ‘C’ ’ f i l e s o f t h e c u r r e n t f o l d e r a r e p a r t o f t h e a p p l i c a t i o n .
12 #### SOURCES can be a e x p l i c i t l i s t o f f i l e s .
13 SOURCES := $ ( w i l d c a r d ∗ . c )
14
15 #### Commen t h e f o l l o w i n l i n e t o c o m p i l e q u i e t l y .
16 V := 1
17
18 ##################################################################
19 # Not c u s t o m i s a b l e s e c t i o n #
20 ##################################################################
21
22 OBJECTS := $ ( a d d s u f f i x . o , $ ( basename $ (SOURCES) ) )
23
24 a l l : $ (TARGET)
25
26 $ (TARGET) : $ (OBJECTS)
27 $ (LDKERNEL) −f $@ $<
28
29 %o : %c
30 $ (CC) $ (CFLAGS) −c −o $@ $<
31
32 clean :
33 rm −f ∗ . p r t k ∗ . k t r ∗ . o ∗˜
34
35 i n c l u d e $ ( PaRTiKle PATH ) / c o n f i g . mk
36 i n c l u d e $ ( PaRTiKle PATH ) / u s e r / r u l e s . mk

This Makefile can be found in the PaRTiKle distribution in the folder: user/examples/template. You can
move (copy) the template folder to some place outside the PaRTiKle tree. In this case, do not forget to update
the PaRTiKle PATH variable of the Makefile.

2.3 Tracing PaRTiKle

Tracing does ease the validation of the execution of any real-time application. Currently, PaRTiKle supports
tracing application when running in a Linux execution environment3 . This section presents a step by step guide
to enable and to visualise the resulting traces.
To support tracing, once enabled, PaRTiKle generates an extra file named sched trace.ktr. This file contains
a sequence of trace logs jointly with the time when they took place.
In order to analyse this data, PaRTiKle includes the kiwi 2.3.2 graphical tool.

2.3.1 Configuration options

Setting the option CONFIG_PORT_DEVTRACE in the configuration menu enables the tracing support in PaR-
TiKle. Internally, selecting this option means that the function log event() is called, printing in a file named
sched trace.ktr each event as a kiwi event.

2.3.2 Using kiwi

Kiwi is a graphic application which displays tasks execution trace logs. It has been entirely written in Tcl/TK,
which makes it very portable. Its main features are: impressive zoom, rich set of graphical elements, output to
eps files, events driven navigation and full customizable colors. Kiwi is mainly focused on real-time systems, but
you can use it for represent any kind of concurrent application or system.
To analyse a sched trace.ktr file, kiwi can be run from command-line with:
3 So far, tracing is only supported in the Linux execution environment, however, it is planned to support this feature in the other

environments

7
 Figure 2.3: kiwi showing context switches while accessing a shared resource

$ kiwi <sched_trace.ktr>

8
Appendix A

Application example

The code below creates a single thread, waits for ten seconds, and then cancels the thread. The thread prints
every second its reference.
1
2 #include <s t d i o . h>
3 #include < s t d l i b . h>
4 #include <time . h>
5 #include <p t h r e a d . h>
6
7 void ∗ t h r e a d m a i n ( void ∗ a r g s ) {
8 struct t i m e s p e c s l e e p i n g t i m e = { 1 , 0 } , r e m a i n i n g ;
9
10 while ( 1 ) {
11 p r i n t f ( ” I ’m t a s k 1 : %p\n” , pthread self ());
12 i f ( n a n o s l e e p (& s l e e p i n g t i m e , &r e m a i n i n g ) == −1)
13 p r i n t f ( ” r e m a i n i n g : s e g %d n s e g : %d\n” ,
14 remaining . tv sec ,
15 remaining . tv nsec ) ;
16 }
17 return ( void ∗ ) 0 ;
18 }
19
20 i n t main ( i n t argc , char ∗∗ argv ) {
21 pthread t task1 ;
22 struct t i m e s p e c t i m e o u t = { 1 0 , 0 } ;
23
24 p t h r e a d c r e a t e (& t a s k 1 , NULL, thread main , NULL ) ;
25 n a n o s l e e p (& timeout , NULL ) ;
26
27 p r i n t f ( ” Request t o f i n i s h \n” ) ;
28
29 pthread cancel ( task1 ) ;
30 p t h r e a d j o i n ( t a s k 1 , NULL ) ;
31 return 0 ;
32 }

9
Appendix B
system calls
Function
pthread create
pthread exit
pthread join
pthread detach
pthread once
pthread self
pthread equal
pthread setschedparam
pthread getschedparam
sched get priority max
sched get priority min
pthread yield
pthread attr init
pthread attr destroy
pthread attr setstackaddr
pthread attr getstackaddr
pthread attr setdetachstate
pthread attr getdetachstate
pthread attr setinheritsched
pthread attr getinheritsched
pthread attr setschedpolicy
pthread attr getschedpolicy
pthread attr setschedparam
pthread attr getschedparam
pthread setcancelstate
pthread cancel
pthread cleanup push
pthread cleanup pop
pthread mutex init
pthread mutex destroy
pthread mutex lock
pthread mutex trylock
pthread mutex timedlock
pthread mutex unlock
pthread mutex setprioceiling
pthread mutex getprioceiling
Description
create a new thread
terminate the calling thread
wait for termination of another thread
put a running thread in the detached state
once-only initialisation
return identifier of current thread
compare two thread identifiers
control thread scheduling parameters
control thread scheduling parameters
get maximum static priority range
get minimum priority range
releases the processor
initialize threads attributes object
destroy threads attributes object
set stackaddr attribute
get stackaddr attribute
set detachstate attribute
get detachstate attribute
set/get scheduling policy and scheduling parameters
set/get scheduling policy and scheduling parameters
set/get scheduling policy and scheduling parameters
set/get scheduling policy and scheduling parameters
set/get scheduling policy and scheduling parameters
set/get scheduling policy and scheduling parameters
set cancelability state
cancel execution of a thread
establish cancelation handlers
remove cancelation handlers
initialize a mutex
destroy and initialize a mutex
lock a mutex
try to lock a mutex
lock a mutex with timeout
unlock a mutex
set the priority ceiling of a mutex
get the priority ceiling of a mutex
10
 Function Description
pthread mutexattr init initialize mutex attributes object
pthread mutexattr destroy destroy and initialize mutex attributes object
pthread mutexattr setprotocol set protocol attribute of mutex attributes object
pthread mutexattr getprotocol get protocol attribute of mutex attributes object
pthread mutexattr setprioceiling set prioceiling attribute of mutex attributes object
pthread mutexattr getprioceiling get prioceiling attribute of mutex attributes object
pthread mutexattr settype set a mutex type attribute
pthread mutexattr gettype get a mutex type attribute
pthread cond init initialize condition variables
pthread cond destroy destroy and initialize condition variables
pthread cond signal signal a condition
pthread cond broadcast broadcast or signal a condition
pthread cond wait wait on a condition
pthread cond timedwait wait on a condition with timeout
pthread condattr init initialize condition variable attributes object
pthread condattr destroy destroy and initialize condition variable attributes object
pthread key create thread-specific data key creation
pthread key delete thread-specific data key deletion
pthread setspecific thread-specific data management
pthread getspecific thread-specific data management
sigaction examine and change signal action
sigqueue queue a signal to a process
pthread kill send a signal to a thread
pthread sigmask examine and change blocked signals
sigwait wait for queued signals
sigsuspend wait for a signal
sigpending examine pending signals
sigemptyset initialize and empty a signal set
sigfillset initialize and fill a signal set
sigaddset add a signal to a signal set
sigdelset delete a signal from a signal set
sigismember test for a signal in a signal set
sigismember test for a signal in a signal set
mktime convert broken-down time into time since the Epoch
localtime r convert a time value to a broken-down local time
localtime convert a time value to a broken-down local time
nanosleep pause execution for a specified time
usleep suspend execution for microsecond intervals
clock settime set the time of a given block
clock gettime get the time of a given block
clock getres get the resolution of any clock
gettimeofday get time
open open a file
close close a file
read read bytes from a file
write write bytes to a file
install irq handler install a handler to manage an interrupt
install trap handler install a handler to manage a trap
hw disable irq disable an interrupt
hw enable irq enable an interrupt
hw ack irq acknowledged an interrupt
hw end irq end the management of an interrupt

11
 Function Description
hw cli disable all interrupts
hw sti enable all interrupts
hw restore flags restore system’s flags
hw save flags save system’s flags
hw save flags and cli save system’s flags and disable interrupt
dirname strip non-directory suffix from file name
basename strip directory and suffix from filenames
getpid get process identification
getppid get parent process identification
malloc allocate dynamic memory
free release dynamic memory
realloc change the size of a block
calloc allocate dynamic memory
mmap allocate a chunk of memory (only flag MAP ANONYMOUS)
munmap deallocate a previously allocated chunk of memory
memset fill memory with a constant byte
memcpy copy memory area
memmove copy memory area
strcpy copy a string
strncpy copy a string. bounded
strcat concatenate two strings
strcmp compare two strings
strlen calculate the length of a string
strchr locate character in string
strrchr locate character in string. reverse search
strstr locate a substring
printf format and print data
putchar output of characters
sscanf input format conversion
scanf input format conversion
fgetc input of characters
ungetc push a character back
fputs output string
puts output string
sprintf format and print data

12