Skip to content

Remote Toolchain

Jump to bottom
Alex Hoffman edited this page Jul 8, 2020 · 9 revisions

Approaches

2 options are available if you do not want to run the Emulator locally.

VM-based approach

WARNING: MacOS support is worth a try, if the experience of developing inside the VM is very miserable. (However, the Docker-based solution is recommended in this case)

As a prerequisite you have to install VirtualBox which is a virtualization tool and can be downloaded here (or via apt-get on Debian based systems): https://www.virtualbox.org/wiki/Downloads

Use the same image as the recommended one for the local setup and add it to VirtualBox. Before booting the machine, you will have to do a small change in the Host Network Section VirtualBox of the Settings.

Open the * Host Network Manager* from the menu bar:

Menu Bar -> File -> Host Network Manager

In the case, that no network exists, yet you have to create one with the following properties:

IPv4 Address: 192.168.57.1
IPv4 Network Mask: 255.255.255.0
IPv6 Address: 
IPv6 Network Mask: 0

If there is already a network with the IP address space 192.168.57.*, please configure the second network adapter of your VM to be a 'Host-only Network Adapter' with the matching name which will likely be one of the following depending on your OS:

VirtualBox Host-Only Ethernet Adapter
vboxnet0
vboxnet1

Make sure to disable the DHCP Server for the network used to enable static IP configuration inside the virtual machine. From now on, you just have to keep an instance of the VM running. No interaction with the OS should be required except sending inputs to the running Emulator and observing the results.

You may want to use the Desktop Shortcut called ZOOM as explained with the VirtualBox Image to have a scaled look at the Emulator Window. After you‘re done, shut down the system either with the VirtualBox controls or using the menu in the rightmost corner of the taskbar.

Do not forget to run cmake -DTOOLCHAIN=vm .. from the build directory before getting into development.

Notes:

  • If you experience issues with the remote connection, you may want to check if you can ping the guest VM from your computer first. A simple ping 192.168.57.106 should give you an hint if a connection can be established. Also ssh rtos-sim@ 192.168.57.106 should result in a login prompt. If not, you will have to htake a closer look at the configuration on the VM-side. (Or you will probably be better off using another more sophisticated toolchain) If you really want to get this running, submit your problem diagnostics via a direct message after executing step steps mentioned before.
  • To make use of the features provided by the pre-installed VirtualBox guest additions, you might have to install the Oracle VM VirtualBox Extension Pack on your computer, which can be downloaded here: https://www.virtualbox.org/wiki/Downloads
  • As this toolchain relies on copying file via a SMB mount between the host and guest system, thing can get out-of-sync for random some reasons.

Container-based approach

WARNING: To enable the use of Docker on Windows hosts, you have to perform major changes, which will very likely break other virtualization software (like VirtualBox). Due to this reason, it is only recommended on MacOS. Using is on Linux installations should be trivial, but just use the local toolchain, if possible?

The approach for the emulator is based on Docker-Desktop and X11 which is heavily OS-dependent. To make the usage more generic a Makefile (See docker/Makefile) is available. The the folowing sections the initial required steps for setting up the development environment

Assuming you have Git installed on you computer, run the following in any shell you like to check out the Emulator branch of this repository.

git clone https://github.com/PhilippvK/FreeRTOS-Emulator.git
cd FreeRTOS-Emulator
git checkout emulator
git submodule update --init --recursive
cd docker # Main working directory for Emulator tasks

To setup the toolchain on your OS, please follow the instructions:

Debian/Ubuntu

Should be quite straightforward as an X Window Server is installed by default.

⚠️ Keep in mind: The authorization for the X11 Connection is implemented in a quite insecure way, which should normally not be a problem but can be improved at a later point

Windows

The initial setup is a little setup as docker commands have to be run in a Powershell Environment while the GNU Make utility requires UNIX-like tools.

  • Download & Install MSYS2 (https://www.msys2.org, 64 bit version)
  • Update PATH to include MinGW executables (Change C:\msys64\ if you have chosen different installation directory)
[Environment]::SetEnvironmentVariable("PATH", "$ENV:PATH;c:\msys64\usr\bin", "USER")
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
  • Reboot the Computer
  • Install VcXsrv Windows X Server (VcXsrv Windows X Server)
  • Start XLaunch and configure it using the default until you get to Extra Settings where you have to ensure, that "disable access control" is checked. Save the Configurating. The X Window Server should be running now. (Make sure, that software like Xming (OLD) is NOT running in parallel)
  • The Configuration file (C:\Users\USERNAME\AppData\Roaming\Xming\config.xlaunch) should look similar to this:
<?xml version="1.0"?>
<XLaunch xmlns="http://www.straightrunning.com/XmingNotes" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.straightrunning.com/XmingNotes XLaunch.xsd" WindowMode="MultiWindow" ClientMode="NoClient" Display="0" Clipboard="true" NoAccessControl="true"/>

You can also use PowerShell to pass the Configuration when Starting XLaunch:

C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Xming> .\XLaunch.lnk -run $env:APPDATA\config.xlaunch
  • This should be it (Do not forget to start XLaunch before trying to run the Emulator!)

MacOS

Using a Homebrew-based development environment, things are getting much easier. Please follow these steps (Run the command in the Terminal Application):

  • Get Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Install GNU Command Line Tools
brew install coreutils
brew install make
  • Make sure Git is installed (f.e. via Homebrew)
  • Install XQuartz X11 Server
brew cask install xquartz
  • Enable OpenGL Support as Administrator (Do not forget to reboot afterwards)
sudo defaults write org.macosforge.xquartz.X11 enable_iglx -bool true
sudo reboot
  • Try out the Emulator using the make targets explained below!

Remarks

  • Be aware of the fact, that the docker container used for the Emulation will not stop running automatically. Make sure to stop it using make down or respectively docker stop/kill/...
  • Anything related to Audio/Sound will not work as X11 Forwarding does not implement such feature

Do not forget to run cmake -DTOOLCHAIN=docker .. from the build directory before getting into development.

Makefile Targets

The two Makefiles supplied for both approaches can be found in the docker and remote directory. If you are using an IDE, you should not have to bother with them very much. Anyway you may have to get back to them to debug problems with the toolchain, kill hanging sessions or changing some constants.

# Check `remote/Makefile` and `docker/Makefile` for more details
# (Internal targets are mentioned but you will probably not need to use them)

# Available for Docker/VM approach
make (run)     # Default target, compiles and runs the emulator after setting up the remote connection
make cmake     # Runs `cmake ..` from within the build directory of the guest. Required after adding source files or changing the CMake configuration
make compile   # Compiles the program by running `make` on the remote
make clean     # Executes the `clean` target on the remote
make debug     # Initializes a GDB debugging session (with TUI)
make kill      # Kills potentially running Emulator/GDB/GDBServer instances
make shell     # Opens up a bash shell to work in a command line on the guest
make gdbserver # Starts a GDB Server on the device
make prepare   # Internal, VM: Changes screen resolution and hides taskbar, Docker: Runs command required to establish a X11 connection

# Available only for VM approach
make ping      # Internal, Checks if the VM is online
make mount     # Internal, Establishes a mount point between the host and guest
make sync      # Internal, Copies the project files to the guest
make quit      # Removes the Mountpoint to clean everything up

# Available only for Docker approach
make reload    # Restarts the container to reinitialize itself (for example after changing the project location)
make logs      # For debugging the boot process of the container
make docker    # Internal, Ensures that Docker Compose is available and Docker is running
make up        # Internal, Boots the container using docker-compose (only if not already running, or config changed)
make start     # Internal, Starts a stopped container
make stop      # Internal, Stops a running container without removing it
make down      # Internal, Removes the container

Typical Problems:

In the future workarounds and fixes for typically issues with the remote development setup should be listed here.

  • IP Configuration
  • SMB Share broken
  • SSH Connection
  • Screen Resolution
  • Debugging
  • Compiling
  • Running
  • CMake
  • Hanging Session
  • Keyboard Layout
  • Files not in Sync, Docker Building an old project: make down; make
  • Many Containers running -> Bad performance
  • Docker not running!
  • ...

Authors: Philipp van Kempen, Alex Hoffman

  1. Introduction
  2. Toolchain Setup
  3. Development Environment
  4. Example Projects
  5. Libraries and APIs
  6. Opponents
  7. FAQ
Clone this wiki locally