Notice: We have migrated to GitLab launching 2024-05-01 see here:

Version 28 (modified by Tony Richardson, on 12/14/19 at 20:58:04) (diff)


RTEMS on Virtualbox

You can run RTEMS in the VirtualBox x86 emulator.

The main advantage of VirtualBox over other emulators is that it provides several board/controller emulation options, including a SATA controller and several network adapters.

This page describes two options for booting RTEMS - over the virtual network from a TFTP server or off of a virtual hard disk.

A solution for debugging RTEMS remotely through VirtualBox serial port is also described.

Booting RTEMS over A Virtual Network

This page describes how to setup a “one click solution” for booting RTEMS in VirtualBox; if the RTEMS application gets updated, it is just a matter of rebooting the virtual machine to boot the new updated application.

What we will need?

Get Virtual Box

The first step is to get and install VirtualBox.

You can get Virtual box from here; you can download the file suited for your Linux distribution or setup the VirtualBox repository.

The pre-requirements for this installation are:

  • Qt 4.4.0 or higher;
  • SDL 1.2.7 or higher (this graphics library is typically called libsdl or similar)
  • DKMS

They should be already installed, if not install them from your distro’s repository:

yum install qt
yum install SDL
yum install dkms

Assuming that you added the VirtualBox repository you only have to issue:

yum install VirtualBox

VirtualBox installations can become quite tricky because a kernel module needs to be installed, so please refer to the VirtualBox documentation if you have any problem.

Get opentftp

Opentftp is a tftp(Trivial File Transfer Protocol) server that will enable us to boot a file from the host computer(the RTEMS application) on the virtual machine.

You can get opentftp from here. The opentftp server comes already compiled, so you only need to run it. The README explains various options for the server, including how to run it as a linux service.

We need to change the directory that is mapped in the server to the directory where our rtems applications is( In my case /home/cdcs/testbed-build/). You can do this be opening the opentftp.ini file that stores the server options. In this file find the "[HOME]" marker and place there the path to your application. This is how my file looked:

#You should specify home directory(s) here
#The home directory can be specified
#in two different ways, with alias or 
#bare names without aliases. Using alias you
#can specify upto 8 directories like
#without aliases, only one directory can
#be specified, which will become root
#directory for tftp.
#mixup of bare names and aliases not allowed
#default will be home directory of user

This option will map the root of the server to "/home/cdcs/testbed-build/". This means that when you access "tftp://" you are accessing "/home/cdcs/testbed-build/test.exe"; similarly "tftp://" will access "/home/cdcs/testbed-build/apps/test.exe". You can also specify up to 8 aliases, eg: "myhome=/home/cdcs" will map "tftp://" to "/home/cdcs/test.exe".

You also need to change the "username=" option in "[TFTP-OPTIONS]" to your username. eg:"username=cdcs"

Once you have made these changes you are ready to run the server (you may need to use root privileges):

./opentftp -v -i opentftp.ini

This command should produce a similar output to the following one:

[root@cdcs opentftp]# ./opentftpd -v -i opentftpd.ini 
TFTP Server MultiThreaded Version 1.62 Unix Built 1621

starting TFTP...
username: cdcs
alias / is mapped to /home/cdcs/testbed-build/
permitted clients: all
server port range: all
max blksize: 65464
default blksize: 512
default timeout: 3
file read allowed: Yes
file create allowed: No
file overwrite allowed: No
thread pool size: 1
listening on:

Now that we have the tftp server up and running let's go to the next step...

Get the bootloader

Now we must get the bootloader that will fetch our application remotely and boot it. For this purpose we will use the etherboot bootloader.

A floppy image with the bootloader can be configured and obtained online. To do so you need to go here and select the most recent production release of gPXE.

This will lead to a configuration page with several bootloader options. For the time being just get sure that the first option(Choose an output format:) is in "Floppy bootable image" and press "Get Image".

The virtual machine

Now we must configure a virtual machine for RTEMS use.

Start VirtualBox and choose "New".

File:Main.png? Give a name to the virtual machine and select "Other"/"Other(Unknown)" in the first page of the virtual machine configuration.

In the second page you have to select the available memory for RTEMS(eg:128Mb).

The third configuration page will allow you to create or select a virtual disk. If you want a virtual harddisk create one and select its size. Creating a Virtual disk is not mandatory, you can still boot RTEMS without having one.

Now that we have concluded creating the virtual machine, we will need to change some options. Select the virtual machine in VirtualBox and press "Settings".The virtual machine settings page will open. This page allows to add disks, change allocated memory, change number of processors among other options.

Select "Storage" on the right panel and then press "Empty" that is underneath the "Floppy Controller". Now press the Browse button that is in front of "Floppy Device" and a new window will open. Press "Add", then change the "Filter:" option in the browse windows from "Image Files" to "All files" and select the .dsk floppy image file that you downloaded earlier.

This is how it should look:

File:Settings.png? File:Add floppy.png?

In the "Network" options the "Adapter-1" shall be attached to "NAT".

Now we are ready to the next step.= First boot =

You shall now have the virtual machine configured with the bootloader floppy image and the opentftp server configured and running with the path to your application.

In VirtualBox press Start to initiate the virtual machine. The bootloader should start to run, and you have to press "Ctrl+B" to start the gPXE command line.

Once in the command line issue:

dhcp net0

Then a set of network parameters will be printed. Write Down the "gateway" parameter(eg:

Now it is the time to test if everything is as expected... Issue the following commands:

kernel tftp://

Where is the gateway parameter you wrote down earlier and test.exe is the name of your application. If everything is running fine the RTEMS application should boot.

If it fails with a "permision denied" please chown and chmod your executable. If it fails with "not found" or similar please check your tftp server configuration(check your server root).

Automate the boot loader

Now we will automate the booting process.

First go back to the bootloader configuration page, but this time select the "Customize" option. If you know what you are doing you can deselect several drivers and protocols, if not let it be.

Now go to the "Embedded Script:" area in the bottom of the page and add this:

dhcp net0
kernel tftp://

Where is the gateway parameter you wrote down earlier and test.exe is the name of your application.

Now press "Get Image" and replace the old one in the virtual machine. Next Time you boot the virtual machine the booting process will be fully automated and will be no need for interaction.

Booting RTEMS from a Virtual Drive

As an alternative to booting RTEMS from the virtual network via TFTP it can also be booted from a virtual drive.

The steps below describe how to create a virtual drive and install a boot manager (GRUB2) on the virtual drive. You will need some way to transfer RTEMS applications from the host to the virtual drive. A few methods for doing this are discussed below.

Creating the Disk Image

You will need a Linux SystemRescueCD image to partition the virtual drive, format the partition and install GRUB. You only need to attach this CD image to the virtual machine when you create the virtual drive.

1) Create a new virtual machine with a fixed-size, VHD hard disk. (Be sure to create a VHD disk and not a VDI or VMDK disk.) The drive needs to be at a least 10 MB just to hold the boot manager (GRUB2). Additional space is required for your RTEMS applications. I use a 100 MB drive. Attach the SystemRescueCD image as the optical drive.

A) I created a 32-bit Ubuntu compatible machine. (It has to have enough resources to run Linux from the SystemRescueCD. You can decrease the amount of some of the resources used by the machine after the disk is created.)

B) You can probably use a VHD dynamically sized disk if you only want to mount the disk from Windows (using the Disk Management tool). A VHD fixed-size disk is just a hard disk image with an added footer, so you can mount it in Linux (via loopback) and/or access it with mtools (or other hard disk image manipulation tools).

C) Fixed-size VDI or VMDK disks may also work. If they are just disk images with an added header or footer they probably would. In that case you can transfer files from the host using mtools or using a Linux loopback device. Windows only has built-in support for attaching to VHD type disks, so that is what I chose.

2) Boot the virtual machine from the SystemRescueCD. When you get to a command prompt, startup the graphical interface by typing "startx". Start the "GParted" tool from the "System" menu. Create an "msdos" partition table on the disk (from the Device menu). Create a new 1 MB primary, ext4 partition for grub (the boot manager). Align the partition to a cylinder. Create a second primary, FAT32 partition that takes up the remainder of the space. Again, align the partition to a cylinder (not necessary if you don't intend to use mtools). Be sure to apply the operations by clicking on the big green check mark. Right-click on the first partition (/dev/sda1), select "Manage Flags" and click on "bios_grub". Right-click on the second partition (/dev/sda2) and format to FAT32. Close GParted.

A) I just used the default options during the SystemRescueCD boot.

B) The grub partition can be of any type (it won't be formatted), I just used the default ext4.

C) Aligning the partitions to a cylinder instead of a Megabyte prevents some mtools warnings that may occur later.

D) You can choose filesystems other than FAT, but you want to choose something that is understood by both GRUB and your host operating system.

3) Open a terminal window and mount the new partition by entering:

     mount /dev/sda2 /mnt/custom

Install GRUB2 by entering:

     grub-install --boot-directory=/mnt/custom/boot /dev/sda

An "ls /mnt/custom" command should now show a "boot" directory. Shut down the virtual machine.

4) Use the VirtualBox Virtual Media Manager to change the type of the VHD disk from "normal" to "immutable". This will prevent VirtualBox from opening the disk image with write-access. This detaches the disk from the Virtual Machine, so you will need to reattach it. Remove the SystemRescueCD from the machine. Restart the Virtual Machine (booting it from the new virtual drive now) and verify that it boots to a grub prompt.

A) Changing the type to "immutable" allows you to open the disk image with some other tool while also using it in VirtualBox. (Although read-only is perhaps more desirable, VirtualBox will not allow you to use the read-only type with hard disk images.)

Alternative Method (FreeDOS)

The method above creates a single virtual disk that contains RTEMS applications. I find it convenient to install FreeDOS to a first (dynamically sized) virtual disk and then use a second (fixed size) disk to hold RTEMS applications. After installing FreeDOS, attach the virtual disk to a SystemRescueCD machine and install GRUB to the disk. You can use the methods below to copy RTEMS applications to the second disk. You can also boot FreeDOS to manage the files on the second disk.

Accessing the Disk Image from the Host

There are several ways to read and write files to the disk image from the host machine. I will mention three. (My preferred method is mtools.)

mtools (Windows, Linux)

Download the mtools source code archive. Extract the source code and build and install the tools. You will need a UNIX-like build environment. I use Windows, and have successfully built and used mtools from cygwin.

You will want to create an .mtoolsrc configuration file in order to simplify using mtools with your virtual disk. My .mtoolsrc file looks like this:

  drive r:
        file="c:/Users/ar63/VirtualBox VMs/RTEMS/RTEMSGPT.vhd" offset=8225280

I found the offset by opening the VHD file in a binary editor and searching for a string (mkfs.fat) in the boot sector. The offset should be to the beginning of the boot sector not the string! The offset should be a multiple of 512, so find the nearest multiple of 512 below the string location.

Alternatively you can let mtools know that the image is a partitioned image and use a .mtoolsrc file like this:

  drive r:
        file="c:/Users/ar63/VirtualBox VMs/RTEMS/RTEMSGPT.vhd"

The mtools work directly with the fat file system on the image. There is no need to mount the image. mdir gives a directory listing of the current directory on the image. mcd changes current directories on the image. mcopy copies files to and from the image. mtype displays the contents of a file. There is no medit, but you can copy a file from the image to the host, edit it and then copy it back. Here are a few example commands:

   mcd r:                     # Make r: current mtools drive
   mdir                       # Get a directory listing
   mcopy hello.exe r:         # Copy from host to partition
   mcd boot/grub              # Change directories on r: drive
   mtype r:grub.conf          # Display file contents
   mcopy r:grub.conf .        # Copy file from r: drive to current host dir

I've used mtools without problem under Cygwin and Msys2. When building under Msys2 be sure to use the Msys2 shell instead of one of the MinGW shells.

Disk Management Tool (Windows)

Use the Disk Management Tool to attach the VHD to the system (from the Action menu). Use the Windows Explorer to copy/edit files on the disk image. Write-caching may cause files written to the image from the host to not be immediately visible in the Virtual Machine. However, when I try to turn write-caching off, Windows disconnects the image. It is probably safest to detach the image after accessing it from the host.

Loopback Device (Linux)

Enter the commands:

   losetup -o 8225280 /dev/loop0 RTEMSGPT.vhd
   mount -t vfat /dev/loop0 /mnt

or as a single command:

   mount -t vfat RTEMSGPT.vhd /mnt -o loop,offset=8225280

You will need to find the correct offset to the start of the FAT partition.

Using GRUB

To boot an RTEMS application named hello.exe from the grub command prompt:

multiboot (hd0,2)/hello.exe

The (hd0,2) notation tells grub to look on the second partition of the first disk.

It is a lot easier to use the grub menu to load RTEMS. Grub looks for a file named grub.cfg in the boot/grub directory. I find it more convenient to keep my configuration file in the root directory of the image. I do this by creating a grub.cfg file in the boot/grub directory that looks like this:

configfile (hd0,2)/grub.cfg

This causes grub to read a second configuration file (also named grub.cfg) from the root directory of the image. The grub.cfg file in the root directory looks like this:

menuentry "HELLO" {
  multiboot (hd0,2)/hello.exe

menuentry "tftp" {
  insmod chain
  set root=(fd0)
  chainloader +1

menuentry "reboot" {

You can edit this menu to add additional items. The second entry in the menu chainloads an etherboot image from an attached floppy. This allows you to either boot RTEMS applications from the virtual disk or via TFTP.

Serial Port Access (Linux Host)

We can use the VirtualBox serial port for remote console or for debugging purposes. If your application is compiled with the RTEMS gdbstub you can remotely debug it from the gdb on your host computer.

To achieve this we will need to activate the serial port in VirtualBox.Go to your virtual machine settings and choose “Serial Ports”. Enable the serial port as “COM1” with the Mode “Host Pipe”. Select create Pipe and select the place where to create the pipe (eg:/tmp/vboxsp)

Now we will need to install socat. You can obtain it from here or install from your disto’s repositories:

yum install socat 

Now lets use socat to create a pseudo terminal. Run the Virtual Machine and open a terminal in your host. Issue the folowing command:

socat -d -d /tmp/vboxsp pty

You should obtain a output similar to the following one:

[root@cdcs testbed]# socat -d -d /tmp/vboxsp pty
2010/06/10 15:08:54 socat[3331] N opening connection to AF=1 "/tmp/vboxsp"
2010/06/10 15:08:54 socat[3331] N successfully connected from local address AF=1 "\xB@\xAE<\xA9\xB@\xAEA\xA9\xB@\xAEA\xA9\xB@\xAE,\xBA\x06\bB\xA9\xB@\xAE"
2010/06/10 15:08:54 socat[3331] N successfully connected via 
2010/06/10 15:08:54 socat[3331] N PTY is /dev/pts/4
2010/06/10 15:08:54 socat[3331] N starting data transfer loop with FDs [3,3] and [4,4]

Write down the PTY that outputted by socat; in this case /dev/pts/4.

Now if your application has the RTEMS gdb stub you can start i386-rtems4.10-gdb and issue the following commands to start debugging the application remotely:

set remotebaud 115200
target remote /dev/pts/4

You can also use socat to channel the serial port to a network connection( for connecting with telnet or similar):

socat UNIX-CONNECT:/tmp/vboxsp TCP-LISTEN:7777
telnet localhost 7777

Networking Applications

XXX: Determine if/how to run RTEMS network applications with the VirtualBox emulator.