mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2025-12-16 18:13:49 +01:00
doc/guides: migrate emulators
Co-authored-by: crasbe <crasbe@gmail.com>
This commit is contained in:
AnnsAnn
parent
9fbbb62c2b
commit
749896fb8e
@ -1,151 +1,5 @@
|
|||||||
Emulators {#emulators}
|
Emulators (Deprecated) {#emulators}
|
||||||
=========
|
=========
|
||||||
|
|
||||||
RIOT supports the [Qemu](https://www.qemu.org/) and [Renode](https://renode.io/)
|
@deprecated Guides have moved to the [Guide Site](https://guide.riot-os.org/misc/emulators/).
|
||||||
emulation tools. The emulation offers a hardware-free development environment
|
This page will be removed after release 2026.04.
|
||||||
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`.
|
|
||||||
|
|
||||||
The boards with emulator supported can be listed using the
|
|
||||||
`info-emulated-boards` target:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ make info-emulated-boards
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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 a random temporary directory:
|
|
||||||
`$(EMULATOR_TMP_DIR)/uart`.
|
|
||||||
The randomness of this variable allows 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 Unix socket, redirected to a
|
|
||||||
local PTY file (using [socat](http://www.dest-unreach.org/socat/)). This makes
|
|
||||||
it possible to open the PTY file in a regular serial port.
|
|
||||||
|
|
||||||
# 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`.
|
|
||||||
|
|||||||
155
doc/guides/misc/emulators.md
Normal file
155
doc/guides/misc/emulators.md
Normal file
@ -0,0 +1,155 @@
|
|||||||
|
---
|
||||||
|
title: Emulators
|
||||||
|
description: Overview of emulators supported in RIOT-OS
|
||||||
|
---
|
||||||
|
|
||||||
|
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`.
|
||||||
|
|
||||||
|
The boards with emulator supported can be listed using the
|
||||||
|
`info-emulated-boards` target:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ make info-emulated-boards
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ 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:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ EMULATE=1 make BOARD=<board> -C <application directory> all debug
|
||||||
|
```
|
||||||
|
|
||||||
|
To start an automatic test script with the emulated board, run:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ 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 a random temporary directory:
|
||||||
|
`$(EMULATOR_TMP_DIR)/uart`.
|
||||||
|
The randomness of this variable allows 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 [BBC micro:bit](https://doc.riot-os.org/group__boards__microbit.html).
|
||||||
|
|
||||||
|
## 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
|
||||||
|
[BBC micro:bit](https://doc.riot-os.org/group__boards__microbit.html)
|
||||||
|
board is supported with qemu.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
The QEMU emulated serial port is exposed on a local Unix socket, redirected to a
|
||||||
|
local PTY file (using [socat](http://www.dest-unreach.org/socat/)). This makes
|
||||||
|
it possible to open the PTY file in a regular serial port.
|
||||||
|
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
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`.
|
||||||
Loading…
x
Reference in New Issue
Block a user