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.

Jailhouse 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. Build the hypervisor: sudo make install
3. Create the root cell configuration: sudo jailhouse config create configs/x86/sysconfig.c
4. 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,
   		.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,
   		},
   	},
   
   /* I need to access 0xa35 and 0xa36 only, but I have to open 0xa37 too,
      don't know why... (mask should be ~0x30, not ~0x70)
   */
   	.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,
   	},
   };
   

5. Build the cell configurations: sudo make </ul>

   x86 host platform setup

   A cross-compiler for aarch64 is needed. On Ubuntu (tested on version 16.04), this can be installed by typing

   sudo apt install gcc-aarch64-linux-gnu
   

   Jailhouse cross-compiling

   The README available on the Jailhouse tree on our GitHub explains how to cross-compile and install Jailhouse. Note that the information is provided for the default Linux kernel by Nvidia (not Vanilla). You can refer to the original Jailhouse page in case you run a Vanilla Linux kernel.

   RT-Druid set-up

   Once Jailhouse has been successfully built, transferred and installed onto the Jetson 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 host platform used for cross-compiling:

   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
      export JAILHOUSE_AARCH64_GCCPREFIX=aarch64-linux-gnu-
      

      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. Then, using the same shell, enter 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) and select the Cross-GCC 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 aarch64 → 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. In the the conf.oil file, set:
      • SOC_DATA=NVIDIA_TEGRA_X1 for TX1
      • SOC_DATA=NVIDIA_TEGRA_X2 for TX2
   7. 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.
   8. Open a shell, enter the workspace and transfer the erika_inmate.bin binary to the Jetson platform (e.g. using scp)
   9. Then, on the Jetson platform:
      1. Install the Jailhouse driver: sudo modprobe jailhouse
      2. Enable Jailhouse:
         • For TX1: sudo jailhouse enable jetson-tx1.cell
         • For TX2: sudo jailhouse enable jetson-tx2.cell
      3. Create the cell for ERIKA3:
         • For TX1: sudo jailhouse cell create jetson-tx1-demo.cell
         • For TX2: sudo jailhouse cell create jetson-tx2-demo.cell
      4. Load the ERIKA3 application:
         • For TX1: sudo jailhouse cell load jetson-tx1-demo erika3_inmate.bin
         • For TX2: sudo jailhouse cell load jetson-tx2-demo erika3_inmate.bin
      5. Start the ERIKA3 application:
         • For TX1: sudo jailhouse cell start jetson-tx1-demo
         • For TX2: sudo jailhouse cell start jetson-tx2-demo
   10. Then, on the Jetson platform, 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.