Documentation: Add how-to for non-root Linux cells

[jailhouse.git] / Documentation / non-root-linux.txt

diff --git a/Documentation/non-root-linux.txt b/Documentation/non-root-linux.txt
new file mode 100644 (file)
index 0000000..cecda6b
--- /dev/null
+++ b/Documentation/non-root-linux.txt
@@ -0,0 +1,71 @@
+Booting Linux in non-root cells
+===============================
+
+Jailhouse exposes only a minimal environment to inmates of non-root cells.
+Specifically on x86, the available resources are insufficient to boot standard
+operating systems without modifications. This document describes the necessary
+steps to configure Linux for booting in a non-root cell.
+
+
+Kernel patches
+--------------
+
+We currently maintain a queue of patches to enable booting of Linux in an x86
+non-root cell:
+
+    git://git.kiszka.org/linux.git queues/jailhouse
+
+Note that this branch may be rebased from time to time to move it to a more
+recent kernel version or to cleanup and adjust the patches. The plan is to
+push those patches upstream once their usefulness and correctness have been
+confirmed.
+
+
+Kernel configuration
+--------------------
+
+After checking out the above kernel branch, create a configuration that
+contains at least the following adjustments:
+
+- enable CONFIG_JAILHOUSE_GUEST
+- disable CONFIG_SERIO
+- disable CONFIG_PM_TRACE_RTC
+
+Note that only 64-bit kernels are supported.
+
+The proper UART configuration depends on the desired console setup. There is
+currently no console available via the inter-cell communication channel, thus
+it may be useful for testing purposes to configure the first physical UART for
+the non-root cell. CONFIG_SERIAL_8250_RUNTIME_UARTS should therefore be set to
+1, and the root cell should avoid using the first UART for its own purposes
+(the linux-x86-demo will revoke the access for the root cell). As the non-root
+Linux cells have no IOAPIC support, there is also no IRQ support for the UART.
+The patch queue currently contains a hack to disable the interrupt for that
+UART and switch Linux to timer-based polling mode. If you don't use a UART,
+CONFIG_SERIAL_8250_RUNTIME_UARTS should be set to 0.
+
+In general, the non-root Linux kernel configuration should be tuned to disable
+all unneeded drivers and features so that no undesired probing will take place
+and the image size as well as the memory footprint is minimized.
+
+
+Non-root Linux start
+--------------------
+
+The easiest way to start a non-root Linux inmate is via the jailhouse tool:
+
+    jailhouse cell linux CELLCONFIG KERNEL [-i | --initrd FILE]
+                         [-c | --cmdline "STRING"] [-w | --write-params FILE]
+
+To create, load and start a Linxu cell and use the first UART as console, issue
+
+    jailhouse cell linux /path/to/linux.cell /path/to/bzImage \
+        -i /path/to/initrd -c "console=ttyS0,1152000"
+
+Alternatively, you can prepare the required configuration image in advance via
+
+    jailhouse cell linux /path/to/linux.cell /path/to/bzImage \
+        -i /path/to/initrd -c "console=ttyS0,1152000" -w /path/to/linux-params
+
+and then issue the basic tool commands on the target as printed by the command
+above.