On 2018-04-24 15:25, Francois-Frederic Ozog wrote: > 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\&. >
Thanks, applied to next, but I moved them directly into tools/ - to keep them close to the tool they describe. Installation patch will follow in a minute. Jan -- Siemens AG, Corporate Technology, CT RDA IOT SES-DE Corporate Competence Center Embedded Linux -- 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.
