Documentation/non-root-linux.txt

   1 Booting Linux in non-root cells
   2 ===============================
   3
   4 Jailhouse exposes only a minimal environment to inmates of non-root cells.
   5 Specifically on x86, the available resources are insufficient to boot standard
   6 operating systems without modifications. This document describes the necessary
   7 steps to configure Linux for booting in a non-root cell.
   8
   9
  10 Kernel patches
  11 --------------
  12
  13 We currently maintain a queue of patches to enable booting of Linux in an x86
  14 non-root cell:
  15
  16     git://git.kiszka.org/linux.git queues/jailhouse
  17
  18 Note that this branch may be rebased from time to time to move it to a more
  19 recent kernel version or to cleanup and adjust the patches. The plan is to
  20 push those patches upstream once their usefulness and correctness have been
  21 confirmed.
  22
  23
  24 Kernel configuration
  25 --------------------
  26
  27 After checking out the above kernel branch, create a configuration that
  28 contains at least the following adjustments:
  29
  30 - enable CONFIG_JAILHOUSE_GUEST
  31 - disable CONFIG_SERIO
  32 - disable CONFIG_PM_TRACE_RTC
  33
  34 Note that only 64-bit kernels are supported.
  35
  36 The proper UART configuration depends on the desired console setup. There is
  37 currently no console available via the inter-cell communication channel, thus
  38 it may be useful for testing purposes to configure the first physical UART for
  39 the non-root cell. CONFIG_SERIAL_8250_RUNTIME_UARTS should therefore be set to
  40 1, and the root cell should avoid using the first UART for its own purposes
  41 (the linux-x86-demo will revoke the access for the root cell). As the non-root
  42 Linux cells have no IOAPIC support, there is also no IRQ support for the UART.
  43 The patch queue currently contains a hack to disable the interrupt for that
  44 UART and switch Linux to timer-based polling mode. If you don't use a UART,
  45 CONFIG_SERIAL_8250_RUNTIME_UARTS should be set to 0.
  46
  47 In general, the non-root Linux kernel configuration should be tuned to disable
  48 all unneeded drivers and features so that no undesired probing will take place
  49 and the image size as well as the memory footprint is minimized.
  50
  51
  52 Non-root Linux start
  53 --------------------
  54
  55 The easiest way to start a non-root Linux inmate is via the jailhouse tool:
  56
  57     jailhouse cell linux CELLCONFIG KERNEL [-i | --initrd FILE]
  58                          [-c | --cmdline "STRING"] [-w | --write-params FILE]
  59
  60 To create, load and start a Linxu cell and use the first UART as console, issue
  61
  62     jailhouse cell linux /path/to/linux.cell /path/to/bzImage \
  63         -i /path/to/initrd -c "console=ttyS0,1152000"
  64
  65 Alternatively, you can prepare the required configuration image in advance via
  66
  67     jailhouse cell linux /path/to/linux.cell /path/to/bzImage \
  68         -i /path/to/initrd -c "console=ttyS0,1152000" -w /path/to/linux-params
  69
  70 and then issue the basic tool commands on the target as printed by the command
  71 above.