VBOX-3610

Introduction

The ERIKA3 RTOS can be run as a guest OS of the Jailhouse hypervisor on the VBOX-3610 platform containing a dual-core Intel i7 processor.

Such support has been developed in the context of the RETINA European project.

This section explains how to build and install Jailhouse on the platform and how to create an ERIKA3 guest (AKA Jailhouse inmate) running a simple application.

Platform setup for Jailhouse

The Jailhouse hypervisor requires a contiguous piece of RAM for itself and each additional cell. This can be done by adding

memmap=68M$0x3b000000

as parameter to the command line of the Linux kernel.
Note that if you plan to put this parameter in GRUB2 variables (e.g. in the /etc/default/grub file), then you will need three escape characters before the dollar (e.g. GRUB_CMDLINE_LINUX_DEFAULT="memmap=68M\\\$0x3b000000").

Additionally, if the inmate needs access to the serial console (like in the example shown below), then the Linux kernel command line parameters must not include the serial console.
In this case, it can be useful to manually initialize the console through the following command just before enabling the hypervisor:

sudo stty -F /dev/ttyS0 115200

Jailhouse build and installation

Information about how to download and build Jailhouse for a Intel platform can be found on the official project page.

In brief:

1. Download the hypervisor: git clone https://github.com/siemens/jailhouse.git
2. Enter the Jailhouse directory: cd jailhouse
3. Build the hypervisor: sudo make install
4. Create the root cell configuration: sudo jailhouse config create configs/x86/sysconfig.c
5. Create the ERIKA cell configuration in configs/x86/erika_cell.c:

   #include <jailhouse/types.h>
   #include <jailhouse/cell-config.h>
   
   #define ARRAY_SIZE(a) sizeof(a) / sizeof(a[0])
   
   struct {
   	struct jailhouse_cell_desc cell;
   	__u64 cpus[1];
   	struct jailhouse_memory mem_regions[2];
   	struct jailhouse_cache cache_regions[1];
   	__u8 pio_bitmap[0x2000];
   } __attribute__((packed)) config = {
   	.cell = {
   		.signature = JAILHOUSE_CELL_DESC_SIGNATURE,
           	.revision = JAILHOUSE_CONFIG_REVISION,
           	.flags = JAILHOUSE_CELL_PASSIVE_COMMREG,
   
   		.name = "erika",
   
   		.cpu_set_size = sizeof(config.cpus),
   		.num_memory_regions = ARRAY_SIZE(config.mem_regions),
   		.num_cache_regions = ARRAY_SIZE(config.cache_regions),
   		.num_irqchips = 0,
   		.pio_bitmap_size = ARRAY_SIZE(config.pio_bitmap),
   		.num_pci_devices = 0,
   	},
   
   	.cpus = {
   		0x8,
   	},
   
   	.mem_regions = {
   		/* RAM */ {
   			.phys_start = 0x3f000000,
   			.virt_start = 0,
   			.size = 0x00100000,
   			.flags = JAILHOUSE_MEM_READ | JAILHOUSE_MEM_WRITE |
   				JAILHOUSE_MEM_EXECUTE | JAILHOUSE_MEM_LOADABLE,
   		},
   		/* communication region */ {
   			.virt_start = 0x00100000,
   			.size = 0x00001000,
   			.flags = JAILHOUSE_MEM_READ | JAILHOUSE_MEM_WRITE |
   				JAILHOUSE_MEM_COMM_REGION,
   		},
   	},
   
   	.cache_regions = {
   		{
   			.start = 0,
   			.size = 2,
   			.type = JAILHOUSE_CACHE_L3,
   		},
   	},
   
   	.pio_bitmap = {
   		[     0/8 ...  0x3f7/8] = -1,
   		[ 0x3f8/8 ...  0x3ff/8] = 0,
   		[ 0x400/8 ...  0xa2f/8] = -1,
   		[ 0xa30/8 ...  0xa37/8] = ~0x70,
   		[ 0xa38/8 ... 0xe00f/8] = -1,
   		[0xe010/8 ... 0xe017/8] = 0,
   		[0xe018/8 ... 0xffff/8] = -1,
   	},
   };
   

6. Build the cell configurations: sudo make

RT-Druid set-up

Once Jailhouse has been successfully built and installed onto the platform, you have to set-up the RT-Druid development environment to compile the ERIKA3 RTOS.

Follow the next instructions for installing RT-Druid on the platform:

1. Download the RT-Druid package from the download section of the ERIKA3 website
2. Extract the downloaded archive
3. Open a shell and type

   export JAILHOUSE_VERSION=0.8
   export JAILHOUSE_DIR=/path/to/compiled/jailhouse
   

   Note that RT-Druid allows to set these variables also from within Eclipse. Just press the right mouse button on the Eclipse project and select Properties as shown in the following figure.

   

   Figure 1: Eclipse project properties.

   Then, select Generator properties, enable project specific settings (as shown in the next figure), and set the desired values.

   

   Figure 2: Generator properties.
4. Finally, using the same shell where the environment variables have been set, enter the directory containing the extracted archive and run

   ./eclipse

Simple application

We now show a simple "helloworld" application consisting of two tasks printing on the serial interface.

1. Run the RT-Druid tool as explained above
2. Create a new project by clicking on New → RT-Druid v3 Oil and C/C++ Project as shown in the next Figure:
   

   Figure 3: Create a new RT-Druid project.
3. Name the new project (e.g., mytest) as shown in the next Figure:
   

   Figure 4: Naming the new RT-Druid project.
4. Check the box for using an existing template and select x86-64 → Jailhouse → Helloworld OSEK demo on Jailhouseas shown in the next Figure:
   

   Figure 5: Selecting the Helloworld template.
5. Eclipse will then show the new project, and RT-Druid will generate the configuration files, as shown in the next Figure:
   

   Figure 6: New Helloworld project created.
6. Click with the right mouse key on the project and select Build project as shown in the next Figure:
   

   Figure 7: Building the Helloworld project.
7. Install the Jailhouse driver: sudo modprobe jailhouse
8. Enable Jailhouse: sudo jailhouse enable configs/x86/sysconfig.cell
9. Create the cell for ERIKA3: sudo jailhouse cell create configs/x86/erika_cell.cell
10. Load the ERIKA3 application: sudo jailhouse cell load erika erika_inmate.bin
11. Start the ERIKA3 application:sudo jailhouse cell start erika
12. Then, on the serial interface, you will see the two tasks printing alternatively on the serial interface, as shown in the next figure:
    

    Figure 8: Output of the helloworld example.

Libc support

If the application on ERIKA needs to use services provided by the libc library (e.g. memcpy()) please refer to the "Libc support" section on the wiki page about Jailhouse for building the Jailhouse inmate library (and also ERIKA) using a bare-metal toolchain.