RIOT/cpu/native/README

VALGRIND SUPPORT
================

If you want to use valgrind, you should recompile native with either
HAVE_VALGRIND_H or HAVE_VALGRIND_VALGRIND_H depending on the location
of the valgrind header (i.e. <valgrind.h> or <valgrind/valgrind.h>)
like this:

    CFLAGS="-DHAVE_VALGRIND_VALGRIND_H -g" make

That way native will tell valgrind about RIOTs stacks and prevent
valgrind from reporting lots of false positives.
The debug information flag "-g" is not strictly necessary, but passing
it allows valgrind to tell you precisely which code triggered the error.

Usage:
Simply pass the ordinary command to valgrind like this:

    valgrind ./bin/native/default.elf tap0

This will yield some information whenever valgrind detects an invalid
memory access.

In order to debug the program when this occurs you can pass the
--db-attach parameter to valgrind like this:

    valgrind --db-attach=yes ./bin/native/default.elf tap0

Now, you will be asked whether you would like to attach the running
process to gdb whenever a problem occurs.

In order for this to work under Linux 3.4 or newer, you might need to
disable the ptrace access restrictions:
As root call:

    echo 0 > /proc/sys/kernel/yama/ptrace_scope

Another helpful valgrind parameter is "--track-origins=yes" which
will allow valrgind to tell you where references to uninitialized
values stem from.


NETWORK SUPPORT
===============

If you compile RIOT for the native cpu and include the native_net
module, you need to specify a network interface like this:

    ./bin/native/default.elf tap0


SETTING UP A TAP NETWORK
========================

There is a shellscript in RIOT/cpu/native called tapsetup.sh which you
can use to create a network of tap interfaces.

Usage:
To create a bridge and two (or count at your option) tap interfaces:

    ./tapsetup.sh create [count]

To delete the bridge and all tap interfaces:

    ./tapsetup.sh delete


OSX TAP NETWORKING
==================

For tun/tap networking in OSX you will need:
http://tuntaposx.sourceforge.net/

For OSX there is a seperate script called tapsetup-osx.sh.
Run it, (it instructs you to start the RIOT instances).
In contrast to linux you will need to run 'tapsetup-osx.sh delete'
after killing your instances and rerun 'tapsetup-osx.sh create' before
restarting.


DAEMONIZATION
=============

You can daemonize a riot process. This is useful for larger networks.
Valgrind will fork along with the riot process and dump its output in
the terminal.

Usage:
    ./bin/native/default.elf -d

Use uart redirection if you want to use a shell or get stderr/stdout
output with/from a daemonized process.


UART REDIRECTION
================

You can redirect the processes stdin/stdout/stderr by specifying
options.

Usage:
To redirect stdio to a UNIX socket run:
    ./bin/native/default.elf -u -d
    RIOT pid: 18663

Attach this UNIX socket:
    nc -U /tmp/riot.tty.18663

To redirect stdio to a TCP socket:
    ./bin/native/default.elf -t 4711 -d
    RIOT pid: 18663

Attach this TCP socket:
    nc localhost 4711

Stop the process:
    kill 18663

To redirect stderr to a file:
    ./bin/native/default.elf -d -e
    RIOT pid: 18663

Read from it:
    tail -f /tmp/riot.stderr.18663

To redirect stdout to a file:
    ./bin/native/default.elf -d -o
    RIOT pid: 18663

Read from it:
    tail -f /tmp/riot.stdout.18663

The stdout redirection only writes to file while no socket connection
is established.

Socket redirection is only available when the uart module has been
compiled in.