Document jailhouse in general, jailhouse enable and parts of jailhouse cell user can enter man jailhouse cell or man jailhouse-cell
No install procedure is yet provided Signed-off-by: Francois-Frederic Ozog <[email protected]> --- man/man8/jailhouse-cell.8 | 128 ++++++++++++++++++++++++++++++++++++++++++++ man/man8/jailhouse-enable.8 | 63 ++++++++++++++++++++++ man/man8/jailhouse.8 | 93 ++++++++++++++++++++++++++++++++ 3 files changed, 284 insertions(+) create mode 100644 man/man8/jailhouse-cell.8 create mode 100644 man/man8/jailhouse-enable.8 create mode 100644 man/man8/jailhouse.8 diff --git a/man/man8/jailhouse-cell.8 b/man/man8/jailhouse-cell.8 new file mode 100644 index 00000000..fd84b606 --- /dev/null +++ b/man/man8/jailhouse-cell.8 @@ -0,0 +1,128 @@ +'\" t +.\" Title: jailhouse +.\" Author: [see the "Authors" section] +.\" Date: 14/04/2018 +.\" Manual: Jailhouse Manual +.\" Source: Git 0.8 +.\" Language: English +.\" +.TH "JAILHOUSE-CELL" "8" "14/04/2018" "Jailhouse 0\&.8\&.0" "Jailhouse Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +jailhouse-cell \- controlling cells +.SH "SYNOPSIS" +.sp +.nf +\fIjailhouse\fR cell [collect | create | destroy | linux | load | shutdown | start | stats] [<args>] +.fi +.sp +.SH "DESCRIPTION" +.sp +.PP +\fBjailhouse cell load\fR { ID | [--name] NAME } { <image_information> } ... +.RS 4 +.sp +Where <image_information> is { IMAGE | { -s | --string } "STRING" } [-a | --address ADDRESS]} +.RE +.RS 4 +.sp +Valid forms are: +.sp + # loads inmate\&.bin (offset 0 assumed) + jailhouse cell load foocell inmate\&.bin +.sp + # same as above with explicit location + jailhouse cell load foocell inmate\&.bin -a 0 +.sp + # loads three binary objects (in order) + jailhouse cell load foocell \\ + inmate\&.bin \\ + sharedobject\&.so -a 0x1000000 \\ + ramfs\&.bin -a 0x2000000 +.RE +.RS 4 +.sp +The first example assumes "-a 0"\&. +.sp +The last example, loads in the order specified, three binary objects, +the first one at offset 0, the second one at 0x1000000\&. +Should inmate.bin be larger than 0x1000000, the upper part will be overridden +by sharedobject\&.so\&. +.sp +Whatever load order, execution starts in the cell at offset 0 unless otherwise specified in the cell config (cpu_reset_address).\&. +.sp +This multi-image loading capability can be used to patch images and +pass parameters to the image\&. The following explains how parameters are passed +with the inmate library\&. +.sp +The inmate library assumes a command line string to be located at a fixed +location that is architecture specific: +.RE +.RS 4 +- On x86 this is offset 0x100 (see inmates/lib/x86/inmate\&.lds) +.RE +.RS 4 +- On arm/arm64, this is offset 0x1000 (see for instance inmates/lib/arm64/inmate\&.lds\&.S) +.RE +.RS 4 +.sp +The command line string capacity is defined during compile time by CMDLINE_BUFFER_SIZE +in inmates/lib/cmdline\&.c or by defining a non weak instance of CMDLINE_BUFFER()\&. +Please note that capacity includes trailing \\0. +.sp +Here is an example to pass parameters stored in the file +commandline.txt to the last example on an x86 system: +.sp + OFFSET=0x100 + jailhouse cell load foocell \\ + inmate\&.bin \\ + commanline\&.txt -a $OFFSET \\ + sharedobject\&.so -a 0x1000000 \\ + ramfs\&.bin -a 0x2000000 +.sp +This command patches inmate.bin at offset 0x100 that corresponds to the "char* cmdline" location as +controlled by the link script for inmates\&. +.sp +Note: on an arm/arm64 we would set OFFSET=0x1000 +.sp +To be more practical and avoid using a text file, there is an image-as-string +option: +.sp + OFFSET=0x100 + jailhouse cell load foocell \\ + inmate\&.bin \\ + -s "<command line parameters here>" -a $OFFSET \\ + sharedobject\&.so -a 0x1000000 \\ + ramfs\&.bin -a 0x2000000 +.sp + +.RE + +.SH "SEE ALSO" +jailhouse(8) jailhouse-enable(8) jailhouse.ko(8) +.SH "AUTHORS" +.sp +Jailhouse was started by Jan Kiszka\&. Contributions have come from the Jailhouse mailing list <\m[blue]\fBjailhouse\-dev@googlegroups\&.com\fR\m[]\&\s-2\u\d\s+2>\&. +.sp +If you have a clone of jailhouse\&.git itself, the output of \fBgit-shortlog\fR(1) and \fBgit-blame\fR(1) can show you the authors for specific parts of the project\&. +.SH "REPORTING BUGS" +.sp +Report bugs to the Jailhouse mailing list <\m[blue]\fBjailhouse\-dev@googlegroups\&.com\fR\m[]\&\s-2\u\d\s+2> where the development and maintenance is primarily done\&. You do not have to be subscribed to the list to send a message there\&. diff --git a/man/man8/jailhouse-enable.8 b/man/man8/jailhouse-enable.8 new file mode 100644 index 00000000..63de4236 --- /dev/null +++ b/man/man8/jailhouse-enable.8 @@ -0,0 +1,63 @@ +'\" t +.\" Title: jailhouse +.\" Author: [see the "Authors" section] +.\" Date: 14/04/2018 +.\" Manual: Jailhouse Manual +.\" Source: Git 0.8 +.\" Language: English +.\" +.TH "JAILHOUSE-ENABLE" "8" "14/04/2018" "Jailhouse 0\&.8\&.0" "Jailhouse Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +jailhouse-enable \- start the lightweight partitioning hypervisor and wraps the running Linux into the root-cell +.SH "SYNOPSIS" +.sp +.nf +\fIjailhouse enable\fR <sysconfig.cell> +.fi +.sp +.SH "DESCRIPTION" +Once the jailhouse\&.ko driver is active in the kernel, Jailhouse has to be enabled: +.sp +.RS +\fIjailhouse enable\fR <sysconfig.cell> +.sp +<sysconfig.cell> is a Jailhouse binary configuration file that describe all present hardware or the necessary hardware for the root cell to be operational\&. This binary configuration file is obtained by compiling a config file in C language format. On x86, the following command can be used to generate a C language configuration file that represent all known hardware: +.sp +.RS +\fIjailhouse cell create\fR <sysconfig.c> +.sp +From this file, the system administrator can remove all hardware that should be dedicated to future cells. Simplest way to compile this file into a <sysconfig.cell> is to copy it in <path to configs/x86/ directory> and launch a build\&. +.RE +.sp +.RE +.PP +.RE +.SH "SEE ALSO" +jailhouse(8) jailhouse-cell(8) jailhouse.ko(8) +.SH "AUTHORS" +.sp +Jailhouse was started by Jan Kiszka\&. Contributions have come from the Jailhouse mailing list <\m[blue]\fBjailhouse\-dev@googlegroups\&.com\fR\m[]\&\s-2\u\d\s+2>\&. +.sp +If you have a clone of jailhouse\&.git itself, the output of \fBgit-shortlog\fR(1) and \fBgit-blame\fR(1) can show you the authors for specific parts of the project\&. +.SH "REPORTING BUGS" +.sp +Report bugs to the Jailhouse mailing list <\m[blue]\fBjailhouse\-dev@googlegroups\&.com\fR\m[]\&\s-2\u\d\s+2> where the development and maintenance is primarily done\&. You do not have to be subscribed to the list to send a message there\&. diff --git a/man/man8/jailhouse.8 b/man/man8/jailhouse.8 new file mode 100644 index 00000000..d5d31390 --- /dev/null +++ b/man/man8/jailhouse.8 @@ -0,0 +1,93 @@ +'\" t +.\" Title: jailhouse +.\" Author: [see the "Authors" section] +.\" Date: 14/04/2018 +.\" Manual: Jailhouse Manual +.\" Source: Git 0.8 +.\" Language: English +.\" +.TH "JAILHOUSE" "8" "14/04/2018" "Jailhouse 0\&.8\&.0" "Jailhouse Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +jailhouse \- the lightweight partitioning hypervisor +.SH "SYNOPSIS" +.sp +.nf +\fIjailhouse\fR <command> [<args>] +.fi +.sp +.SH "DESCRIPTION" +.sp +Jailhouse is a partitioning Hypervisor based on Linux\&. It is able to run bare-metal applications or (adapted) operating systems besides Linux\&. For this purpose, it configures CPU and device virtualization features of the hardware platform in a way that none of these domains, called "cells" here, can interfere with each other in an unacceptable way\&. +.sp +Jailhouse is optimized for simplicity rather than feature richness\&. Unlike full-featured Linux-based hypervisors like KVM or Xen, Jailhouse does not support overcommitment of resources like CPUs, RAM or devices\&. It performs no scheduling and only virtualizes those resources in software, that are essential for a platform and cannot be partitioned in hardware\&. +.sp +Once Jailhouse is activated, it runs bare-metal, i\&.e\&. it takes full control over the hardware and needs no external support\&. However, in contrast to other bare-metal hypervisors, it is loaded and configured by a normal Linux system\&. Its management interface is based on Linux infrastructure\&. So you boot Linux first, then you enable Jailhouse and finally you split off parts of the system's resources and assign them to additional cells\&. +.SH "USAGE FLOW" +.sp +Once the jailhouse\&.ko driver is active in the kernel, Jailhouse has to be enabled with the following command: +.sp +.RS +\fIjailhouse enable\fR <sysconfig.cell> +.sp +This activates the hypervisor and wraps the executing Linux execution environment into a cell called the "root cell"\&. It is then possible to create and tear down cells with jailhouse cell commands\&. <sysconfig.cell> is a Jailhouse binary configuration file that describe all present hardware but the hardware devices destined to future cells\&. +.sp +.RE +Jailhouse enabled, then it is possible to create and terminate cells with the following set of commands: +.sp +.RS 4 +.nf +\fIjailhouse cell create\fR -name <cellname> <cellconfig.cell> +\fIjailhouse cell load\fR -name <cellname> <args> +\fIjailhouse cell start\fR -name <cellname> +\fIjailhouse cell destroy\fR -name <cellname> +.fi +.RE +.sp +To terminate jailhouse alltogether, all cells must be destroyed and then hypervisor itself terminated with: +.sp +.RS +\fIjailhouse disable\fR +.sp +This unwraps the root cell into a bare metal environment\&. The jalhouse\&.ko driver can be unloaded once Jailhouse has been disabled\&. +.RE +.SH "JAILHOUSE COMMANDS" +.sp +.PP +\fBjailhouse-cell\fR(8) +.PP +\fBjailhouse-console\fR(8) +.PP +\fBjailhouse-disable\fR(8) +.PP +\fBjailhouse-enable\fR(8) +.PP +\fBjailhouse-hardware\fR(8) +.SH "SEE ALSO" +jailhouse-cell(8) jailhouse-enable(8) jailhouse.ko(8) +.SH "AUTHORS" +.sp +Jailhouse was started by Jan Kiszka\&. Contributions have come from the Jailhouse mailing list <\m[blue]\fBjailhouse\-dev@googlegroups\&.com\fR\m[]\&\s-2\u\d\s+2>\&. +.sp +If you have a clone of jailhouse\&.git itself, the output of \fBgit-shortlog\fR(1) and \fBgit-blame\fR(1) can show you the authors for specific parts of the project\&. +.SH "REPORTING BUGS" +.sp +Report bugs to the Jailhouse mailing list <\m[blue]\fBjailhouse\-dev@googlegroups\&.com\fR\m[]\&\s-2\u\d\s+2> where the development and maintenance is primarily done\&. You do not have to be subscribed to the list to send a message there\&. -- 2.11.0 -- You received this message because you are subscribed to the Google Groups "Jailhouse" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
