Family: native

• Known Issues
• Toolchains
• Dependencies
• Profiling
• Networking
• Daemonization
• UART

There's currently only one cpu/board in this family: Board: native

The RIOT native port uses system calls and signals to emulate hardware at the API level. That means that you can compile the complete RIOT software stack for your *NIX system and run it as a process. Reasons why you might want to do that are:

• You want to try out RIOT but don't have one of the supported hardware platforms
• You are developing an application for RIOT or you are hacking on RIOT itself and want to test and debug without the limitations and requirements of debugging on actual hardware
• You want to experiment with network protocols in a controlled environment

There is support for networking through tap interfaces. Emulators for some typical devices exist. If you are missing one it should be easy to add it.

Some aspects of a native RIOT instance can be configured at runtime. To get an overview invoke the program with the -h option. Example:

./bin/native/default.elf -h
usage: ./bin/native/default.elf <tap interface> [-t <port>|-u [path]] [-i <id>] [-d] [-e|-E] [-o]
 help: ./bin/native/default.elf -h

Options:
-h      help
-i      specify instance id (set by config module)
-d      daemonize
-e      redirect stderr to file
-E      do not redirect stderr (i.e. leave sterr unchanged despite socket/daemon io)
-o      redirect stdout to file when not attached to socket
-u      redirect stdio to UNIX socket
        if no path is given /tmp/riot.tty.PID is used
-t      redirect stdio to TCP socket

The order of command line arguments matters.

As with any platform, you can specify the sizes of your stacks, i.e. the amount of space your application can use. You may wish to use a more realistic stack size than natives MINIMUM_STACK_SIZE or KERNEL_CONF_STACKSIZE_DEFAULT to increase realism.

Known Issues

Check the list of open issues labeled native in the github issue tracker

Toolchains

Working:

• gnu libc 2.13
• gnu libc 2.19
• gcc 4.4.6
• gcc 4.9.0
• clang version 3.4

Not Working:

• gnu libc 2.15
• gcc 4.6.3 (only tried in conjunction with gnu libc 2.15)

Host Systems

As a rule of thumb: native is developed primarily on Arch Linux, so this should always be the most reliable platform.

Working:

• Arch Linux
• Debian 7 Wheezy (Stable)
• Ubuntu 12.04 Precise Pangloin (LTS) - is it? (comes with libc 2.15)
• Ubuntu 13.10 Saucy Salamander
• Ubuntu 14.04 Trusty Tahr
• Ubuntu 14.10 Utopic Unicorn
• …
• OS X 10.8 Mountain Lion
• OS X 10.9 Mavericks
• FreeBSD 10

Not Working:

• Windows - no plans for support exist (You can take a look at Vagrant and use a virtual Linux to run the virtual RIOT..)

Dependencies

Generally speaking, you only need your systems development packages (libc, compiler, make). Below is a list of specific instructions for certain distributions/systems.

Arch Linux

Build requirements: pacman -S base-devel

You probably want to install bridge-utils and valgrind as well: pacman -S valgrind bridge-utils

Multilib

If you have a 64 bit system, you need to enable multilib support. Edit /etc/pacman.conf and uncomment the multilib repository:

[multilib]
Include = /etc/pacman.d/mirrorlist

Install required packages (you will probably have to answer some questions regarding conflict resolution): pacman -S gcc-multilib valgrind-multilib

Debian 7.5 Stable

To install all required packages and make your user a sudoer (for tapsetup.sh) run (as root):

apt-get install build-essential pkg-config valgrind sudo bridge-utils
usermod -a -G sudo <your account>

amd64

When you're running a 64 bit Debian, you will additionally need to add support for 32 bit:

dpkg --add-architecture i386
apt-get update
apt-get install libc6-dev-i386 libc6-dbg:i386

Ubuntu

32-bit support

If you are running a 64-bit machine, you have to install the gcc-multilib package

sudo apt-get install gcc-multilib

to successfully compile RIOT.

Valgrind troubleshooting

You may encounter the following error message, even though libc6-dbg is installed:

==11361== Memcheck, a memory error detector
==11361== Copyright (C) 2002-2012, and GNU GPL'd, by Julian Seward et al.
==11361== Using Valgrind-3.8.1 and LibVEX; rerun with -h for copyright info
==11361== Command: ./bin/native/aodvv2_node.elf tap0
==11361== 

valgrind:  Fatal error at startup: a function redirection
valgrind:  which is mandatory for this platform-tool combination
valgrind:  cannot be set up.  Details of the redirection are:
valgrind:  
valgrind:  A must-be-redirected function
valgrind:  whose name matches the pattern:      strlen
valgrind:  in an object with soname matching:   ld-linux.so.2
valgrind:  was not found whilst processing
valgrind:  symbols from the object with soname: ld-linux.so.2
valgrind:  
valgrind:  Possible fixes: (1, short term): install glibc's debuginfo
valgrind:  package on this machine.  (2, longer term): ask the packagers
valgrind:  for your Linux distribution to please in future ship a non-
valgrind:  stripped ld.so (or whatever the dynamic linker .so is called)
valgrind:  that exports the above-named function using the standard
valgrind:  calling conventions for this platform.  The package you need
valgrind:  to install for fix (1) is called
valgrind:  
valgrind:    On Debian, Ubuntu:                 libc6-dbg
valgrind:    On SuSE, openSuSE, Fedora, RHEL:   glibc-debuginfo
valgrind:  
valgrind:  Cannot continue -- exiting now.  Sorry.

To enable the use of Valgrind, change the lines in /etc/apt/sources.list from something like

deb http://archive.ubuntu.com/ubuntu saucy main

to

deb [arch=i386,amd64] http://archive.ubuntu.com/ubuntu saucy main

and execute

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6-dbg:i386

If the version of dpkg is older than 1.16.2 you have to add the i386 architecture manually. Check if the only file present in /etc/dpkg/dpkg.cfg.d/ is "multiarch" and execute

sudo sh -c "echo 'foreign-architecture i386' > /etc/dpkg/dpkg.cfg.d/multiarch"

If there is no "multiarch" file replace the filename with the name of file present in that directory.

OS X

In order to use the nativenet network device, you will need to install TunTap.

FreeBSD 10 amd64

This section is work in progess..

Install dependencies:

# pkg install gmake
# pkg install gcc

Set up your environment and build:

$ export LINK=gcc47
$ export CC=gcc47
$ gmake clean all

GCC address sanitizer troubleshooting

As of GCC 4.8 has a build-in address sanitizer (see address sanitizer). There is however no build-in symbolizer in versions before GCC 4.9, so the stack backtraces will give you addresses instead of lines of code + function name. To get the later anyways you need to install the llvm-symbolizer and set two environment variables for libasan to use this symbolizer:

Ubuntu 14.04

sudo apt-get install llvm-symbolizer-3.4
export ASAN_SYMBOLIZER_PATH=/usr/bin/llvm-symbolizer-3.4
export ASAN_OPTIONS=symbolize=1

Profiling

Valgrind/cachegrind

You can use the Valgrind tool cachegrind to profile native processes.

Usage:

make -B clean all-cachegrind
make term-cachegrind
make eval-cachegrind

The cachegrind file name (cachegrind.out.*) contains the process ID as a suffix, so you can create profiles for several instances at the same time. You can also use the kcachegrind GUI to investigate the cachegrind files.

Valgrind/callgrind

Profiling with callgrind is not working at the moment.

gprof

The gprof profiler can be used to profile native processes.

Usage:

make -B clean all-gprof
make term-gprof
make eval-gprof

The gprof file name (gmon.out.*) contains the process ID as a suffix, so you can create profiles for several instances at the same time.

You can use the gprof profile to create a call graph with dot: http://code.google.com/p/jrfonseca/wiki/Gprof2Dot

Address sanitizer

clang>=3.1 and gcc>=4.8 have build-in address sanitizers to detect and display possible memory corruption bugs. For both compiler collections the -fsanitize=address flag is used to include this feature. RIOT has this feature integrated into its build system:

make all-asan
make term

Networking

See here: Virtual riot network

Daemonization

You can use the -d option to daemonize a RIOT process.

Example:

/bin/native/default.elf tap0 -d 
RIOT pid: 14363

The program prints the PID of the daemon process. A daemonized process is detached from the terminal in which is was created. You can use UART redirection to communicate with it. To stop the process, you can send a TERM signal to the process.

Example:

kill -SIGTERM 14363

UART

The native UART can be configured at runtime for IO redirection via sockets.

TCP

Use the -t parameter to specify a TCP port to listen at.

Example:

./bin/native/default.elf tap0 -d -t 4711
RIOT pid: 13704

Now you can connect to the processes UART by connecting to the TCP socket at the specified port.

Example:

nc localhost 4711
help
Command              Description
---------------------------------------
reboot               Reboot the node
id                   Gets or sets the node's id.
ps                   Prints information about running threads.
date                 Gets or sets current date and time.
cur                  Prints current and average power consumption.
rstcur               Resets coulomb counter.
addr                 Gets or sets the address for the transceiver
eui64                Gets or sets the EUI-64 for the transceiver
chan                 Gets or sets the channel for the transceiver
txtsnd               Sends a text message to a given node via the transceiver
pan                  Gets or sets the pan id for the transceiver
monitor              Enables or disables address checking for the transceiver
mersenne_init        initializes the PRNG
mersenne_get         returns 32 bit of pseudo randomness
>

UNIX

Use the -u option to redirect IO to a UNIX socket.

Example:

./bin/native/default.elf tap0 -u -d
RIOT pid: 13902

Now you can connect to the processes UART by connecting to the UNIX socket which is created in /tmp/riot.tty.PID

Example:

nc -U /tmp/riot.tty.13902
help
Command              Description
---------------------------------------
reboot               Reboot the node
id                   Gets or sets the node's id.
ps                   Prints information about running threads.
date                 Gets or sets current date and time.
cur                  Prints current and average power consumption.
rstcur               Resets coulomb counter.
addr                 Gets or sets the address for the transceiver
eui64                Gets or sets the EUI-64 for the transceiver
chan                 Gets or sets the channel for the transceiver
txtsnd               Sends a text message to a given node via the transceiver
pan                  Gets or sets the pan id for the transceiver
monitor              Enables or disables address checking for the transceiver
mersenne_init        initializes the PRNG
mersenne_get         returns 32 bit of pseudo randomness
>

File Output

To save output that happens while no socket is connected, you can use the -o option.

Example:

./bin/native/default.elf tap0 -d -u -o
RIOT pid: 14924

Now the process writes its output to /tmp/riot.stdout.PID where PID is the process ID. Note that the output is not written to the file while a socket is connected.

Data Type Sizes

sizeof(short): 2
sizeof(int): 4
sizeof(long): 4
sizeof(long long): 8
sizeof(float): 4
sizeof(double): 8