On 2018-04-16 14:28, f...@ozog.com wrote:
> Document jailhouse in general, jailhouse enable and parts of jailhouse cell
> user can enter
> man jailhouse cell
> or
> man jailhouse-cell

Cool, will have a look ASAP.

> 
> No install procedure is yet provided

Yeah, that's likely easy to add later on.

Thanks,
Jan

> 
> 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
> 
-- 
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 jailhouse-dev+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to