doc: add emulator documentation

doc/doxygen/riot.doxyfile

@@ -772,6 +772,7 @@ INPUT                  = ../../doc.txt \
                          src/kconfig/kconfig.md \
                          src/using-cpp.md \
                          src/advanced-build-system-tricks.md \
+                         src/emulators.md \
                          src/changelog.md \
                          ../../LOSTANDFOUND.md
 

doc/doxygen/src/emulators.md

@@ -0,0 +1,146 @@
+Emulators                                                 {#emulators}
+=========
+
+RIOT supports the [Qemu](https://www.qemu.org/) and [Renode](https://renode.io/)
+emulation tools. The emulation offers a hardware-free development environment
+for quickly testing applications.
+
+From the build system point of view, the emulation support in RIOT is
+transparent compared to the usual workflow: simply add `EMULATE=1` to the
+command line and the emulator supported by the board will be called instead of
+the board flashing/debugging tool.
+Targets compatible with `EMULATE=1` are `term`, `cleanterm`, `debug`,
+`debugserver` and `test`.
+
+If a board supports multiple emulators, the emulator backend can be selected
+with the `RIOT_EMULATOR` variable. Possible values are `qemu` and `renode`.
+If no emulator is specified by the board configuration (e.g. in its
+`Makefile.include`), the default emulator is `renode`.
+
+## Features
+
+Be aware that not all hardware features provided by a board - and described as
+such in the build system by `FEATURES_PROVIDED` - are implemented in emulators.
+For example, the `hifive1b` provides the RTC peripheral feature but this is not
+implemented by the renode driver.
+So you may expect some failures when running advanced applications on the
+emulator.
+
+## Usage
+
+All emulators can be used the same way. Just add `EMULATE=1` to the command
+line.
+
+To start an emulator and connect to the serial port of the emulated board, run:
+
+```
+$ EMULATE=1 make BOARD=<board> -C <application directory> all term
+```
+
+To start an emulator with a GDB server and connect a GDB client to it, run:
+
+```
+$ EMULATE=1 make BOARD=<board> -C <application directory> all debug
+```
+
+To start an automatic test script with the emulated board, run:
+
+```
+$ EMULATE=1 make BOARD=<board> -C <test application directory> all test
+```
+
+The `EMULATOR_SERIAL_PORT` variable can be used to specify a custom serial port
+on the host running the emulator.
+The default value is built based on the board and application names:
+`/tmp/riot_$(APPLICATION)_$(BOARD)_uart`.
+This variable is useful to allow several emulated sessions of the same
+application with the same board to run in parallel.
+
+# Qemu
+
+## Overview
+
+[Qemu](https://www.qemu.org/) is a machine emulator and virtualizer. It can
+be used to emulate regular computer architectures but also some microcontroller
+based boards such as the @ref boards_microbit.
+
+## Installation
+
+Qemu is usually available via the package manager of common Linux distributions.
+Depending on your local system, the installation procedure is described on the
+[qemu website](https://www.qemu.org/download/).
+
+## Boards supported
+
+So far, in RIOT, only the @ref boards_microbit board is supported with qemu.
+
+## Configuration
+
+The QEMU emulated serial port is exposed on a local TCP server, redirected to a
+local PTY file (using [socat](http://www.dest-unreach.org/socat/)). This makes
+it possible to open the PTY file a regular serial port.
+To allow multiple emulated sessions in parallel, the TCP port of the TCP server
+can be configured using the `QEMU_SERIAL_TCP_PORT`. The default value is 5555.
+
+# Renode
+
+## Overview
+
+[Renode](http://renode.io) is a virtual development tool for multinode embedded
+networks (both wired and wireless) enabling a scalable workflow for building
+effective, tested and secure IoT systems, created by
+Antmicro](http://antmicro.com/blog/2017/08/renode-press-release/).
+It can easily be used to run applications on a broad range of embedded platforms
+without any changes in the code itself, as if you were running on real
+hardware - but with more possibilities.
+
+## Installation
+
+### From package
+
+Packages for macOS, deb-based and rpm-based systems, for Windows and for Arch
+Linux are available on [GitHub](https://github.com/renode/renode/releases/latest).
+
+### From source
+
+Follow the installation instructions on Renode's
+[GitHub](https://github.com/renode/renode#installation) page.
+
+If you choose to build renode from source, after the compilation is successful,
+ensure that `renode` is available on your `PATH`.
+One way to do so, is via symlink:
+
+```
+sudo ln -s path/to/renode/repository/renode /usr/local/bin/renode
+```
+
+### Testing
+
+After installation, verify that Renode is working using `renode --help`. You
+should be presented with a help screen.
+
+## Documentation
+
+Documentation for Renode can be found on [Read The Docs](https://renode.readthedocs.io).
+
+## Usage
+
+From within RIOT-OS, add `EMULATE=1` to start the emulation. The emulation
+expects a board definition file in `boards/<BOARD>/dist/board.resc`.
+
+The board definition file will tell Renode how to setup an emulation session.
+The application binary file (`*.elf`) is available using the variable
+`$image_file`.
+
+For an example, refer to `boards/cc2538dk/dist/board.resc`.
+
+The renode logging level can be configured from the command line using the
+following variables:
+- `RENODE_SHOW_LOG`: set it to 1 to show the logs in the standard output
+- `RENODE_LOG_LEVEL`: set it to the desired log level, default is 2 (warning)
+
+The renode monitor and serial console GUI windows are hidden by default but
+they can be displayed by setting `RENODE_SHOW_GUI` to 1 in the command line.
+
+If uart0 is not the default serial port used for stdio, use `RENODE_SYSBUS_UART`
+to specify a custom one in the board `Makefile.include`.