From: Francois-Frederic Ozog <f...@ozog.com>

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 <f...@ozog.com>
---
 man/man8/jailhouse-cell.8   | 129 ++++++++++++++++++++++++++++++++++++++++++++
 man/man8/jailhouse-enable.8 |  63 ++++++++++++++++++++++
 man/man8/jailhouse.8        |  93 ++++++++++++++++++++++++++++++++
 3 files changed, 285 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..954fa495
--- /dev/null
+++ b/man/man8/jailhouse-cell.8
@@ -0,0 +1,129 @@
+'\" 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 inamte\&.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
+    # load 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\&.
+.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 processor specific:
+.RE
+.RS 4
+- On x86 this is offset 0x100 (see inmates/lib/x86/inmate\&.lds)
+.RE
+.RS 4
+- On arm64, this is offset 0x1000 (see inmates/lib/arm64/inmate\&.lds\&.S)
+.RE
+.RS 4
+.sp
+The command line string capacity is fixed (256 bytes by defaylt) by 
CMDLINE_BUFFER_SIZE
+in inmates/lib/cmdline\&.c\&.
+.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 happens to be char* 
cmdline for
+inmates that uses Jailhouse inmates library\&.
+.sp
+Note: on an 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
+The string in the -s need to be less than 255 characters long 
(CMDLINE_BUFFER_SIZE - terminating \\0)
+otherwise it will silently overwrite existing code\&.
+
+.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..f5177194
--- /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 but the hardware devices destined to future cells\&. 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 jailhouse-dev+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to