[src/trunk]: src add a high-level rumpkernel.7 manpage

[pooka <pooka%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/71ef55cd47e8
branches:  trunk
changeset: 804829:71ef55cd47e8
user:      pooka <pooka%NetBSD.org@localhost>
date:      Tue Dec 02 01:51:45 2014 +0000

description:
add a high-level rumpkernel.7 manpage

diffstat:

 distrib/sets/lists/man/mi            |    5 +-
 sys/rump/share/man/man7/Makefile     |    4 +-
 sys/rump/share/man/man7/rumpkernel.7 |  147 +++++++++++++++++++++++++++++++++++
 3 files changed, 153 insertions(+), 3 deletions(-)

diffs (195 lines):

diff -r 08863e56f560 -r 71ef55cd47e8 distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Mon Dec 01 23:08:15 2014 +0000
+++ b/distrib/sets/lists/man/mi Tue Dec 02 01:51:45 2014 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1489 2014/11/22 01:29:05 pettai Exp $
+# $NetBSD: mi,v 1.1490 2014/12/02 01:51:45 pooka Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -2238,6 +2238,7 @@
 ./usr/share/man/cat7/release.0                 man-reference-catman    .cat
 ./usr/share/man/cat7/rfc6056.0                 man-reference-catman    .cat
 ./usr/share/man/cat7/rump_sp.0                 man-reference-catman    .cat,rump
+./usr/share/man/cat7/rumpkernel.0                      man-reference-catman    .cat,rump
 ./usr/share/man/cat7/script.0                  man-reference-catman    .cat
 ./usr/share/man/cat7/security.0                        man-reference-catman    .cat
 ./usr/share/man/cat7/setuid.0                  man-reference-catman    .cat
@@ -5186,6 +5187,7 @@
 ./usr/share/man/html7/release.html             man-reference-htmlman   html
 ./usr/share/man/html7/rfc6056.html             man-reference-htmlman   html
 ./usr/share/man/html7/rump_sp.html             man-reference-htmlman   html,rump
+./usr/share/man/html7/rumpkernel.html          man-reference-htmlman   html,rump
 ./usr/share/man/html7/script.html              man-reference-htmlman   html
 ./usr/share/man/html7/security.html            man-reference-htmlman   html
 ./usr/share/man/html7/setuid.html              man-reference-htmlman   html
@@ -8109,6 +8111,7 @@
 ./usr/share/man/man7/release.7                 man-reference-man       .man
 ./usr/share/man/man7/rfc6056.7                 man-reference-man       .man
 ./usr/share/man/man7/rump_sp.7         man-reference-man       .man,rump
+./usr/share/man/man7/rumpkernel.7              man-reference-man       .man,rump
 ./usr/share/man/man7/script.7                  man-reference-man       .man
 ./usr/share/man/man7/security.7                        man-reference-man       .man
 ./usr/share/man/man7/setuid.7                  man-reference-man       .man
diff -r 08863e56f560 -r 71ef55cd47e8 sys/rump/share/man/man7/Makefile
--- a/sys/rump/share/man/man7/Makefile  Mon Dec 01 23:08:15 2014 +0000
+++ b/sys/rump/share/man/man7/Makefile  Tue Dec 02 01:51:45 2014 +0000
@@ -1,5 +1,5 @@
-#      $NetBSD: Makefile,v 1.1 2014/11/09 17:39:38 pooka Exp $
+#      $NetBSD: Makefile,v 1.2 2014/12/02 01:51:45 pooka Exp $
 
-MAN=   rump_sp.7
+MAN=   rumpkernel.7 rump_sp.7
 
 .include <bsd.man.mk>
diff -r 08863e56f560 -r 71ef55cd47e8 sys/rump/share/man/man7/rumpkernel.7
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/rump/share/man/man7/rumpkernel.7      Tue Dec 02 01:51:45 2014 +0000
@@ -0,0 +1,147 @@
+.\"     $NetBSD: rumpkernel.7,v 1.1 2014/12/02 01:51:45 pooka Exp $
+.\"
+.\" Copyright (c) 2008-2014 Antti Kantee.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd December 1, 2014
+.Dt RUMPKERNEL 7
+.Os
+.Sh NAME
+.Nm rump kernel
+.Nd The Anykernel and Rump Kernels
+.Sh DESCRIPTION
+Rump kernels provide portable, componentized, kernel quality drivers
+such as file systems, POSIX system call handlers, PCI device drivers, a
+SCSI protocol stack, virtio and a TCP/IP stack.
+The fundamental enabling technology is the anykernel architecture of
+.Nx ,
+which enables the use of unmodified
+.Nx
+kernel drivers.
+The minimalistic
+.Xr rumpuser 3
+interface integrates a rump kernel to the host platform.
+Suitable and readily supported platforms include for example POSIX
+userspace (such as NetBSD), hypervisors (such as Xen and KVM), and bare
+metal hardware.
+.Pp
+Rump kernels are component-oriented, which means that they consist
+of libraries which are linked together to form runtime images.
+If the platform supports it, dynamic linking may be used to load
+components at runtime, allowing the creation of services where the
+runtime component configuration is specified when the service is run (see
+.Xr rump_server 1
+for an example).
+.Pp
+A rump kernel provides its own set of namespaces, such as a file system
+hierarchy and TCP ports, that are independent of the ones on the host
+and of any other rump kernel instances.
+It should be noted that the presence of the provided namespaces
+depends on the components that the rump kernel was constructed with.
+For example, networking and file systems are components, and it is
+possible to construct a rump kernel which supports neither.
+.Pp
+A rump kernel accepts the following bootstrap parameters.
+The exact way of specifying the parameters depends on the host
+platform; for example in POSIX userspace the parameters are
+environment variables.
+.Bl -tag -width RUMP_MEMLIMITXX
+.It Dv RUMP_NCPU
+If set, the value indicates the number of virtual cores configured into a
+rump kernel, i.e. the number of threads which can be concurrently
+executing code inside the rump kernel.
+.Pp
+The special value "host" can be used to specify the number of
+of host cores available (note: not available on all platforms).
+If this parameter is unset, two cores will be configured.
+.It Dv RUMP_VERBOSE
+If set to non-zero, causes bootstrap messages to be displayed on the
+console.
+.It Dv RUMP_MEMLIMIT
+If set, indicates the maximum amount of memory that a rump kernel will
+attempt to allocate from the host.
+If this parameter is unset, the rump kernel attempt to allocate
+host memory until allocation fails.
+When the rump kernel is close to the allocation limit, or when host
+allocation fails, the rump kernel will attempt to make more memory
+available by invoking its internal pagedaemon to flush caches.
+.El
+.Sh SEE ALSO
+.Lk http://rumpkernel.org/
+.Rs
+.%A Antti Kantee
+.%A Justin Cormack
+.%T Rump Kernels: No OS? No Problem!
+.%D October 2014
+.%I USENIX
+.%J ;login:
+.%N No. 5
+.%V Vol. 39
+.Re
+.Rs
+.%A Antti Kantee
+.%D 2012
+.%J Aalto University Doctoral Dissertations
+.%T Flexible Operating System Internals: The Design and Implementation of the Anykernel and Rump Kernels
+.Re
+.Rs
+.%A Antti Kantee
+.%D March 2010
+.%B Proceedings of AsiaBSDCon 2010
+.%P pp. 75-84
+.%T Rump Device Drivers: Shine On You Kernel Diamond
+.Re
+.Rs
+.%A Arnaud Ysmal
+.%A Antti Kantee
+.%D September 2009
+.%B EuroBSDCon 2009
+.%T Fs-utils: File Systems Access Tools for Userland
+.Re
+.Rs
+.%A Antti Kantee
+.%D June 2009
+.%B Proceedings of the 2009 USENIX Annual Technical Conference
+.%P pp. 201-214
+.%T Rump File Systems: Kernel Code Reborn
+.Re
+.Rs
+.%A Antti Kantee
+.%D May 2009
+.%B BSDCan 2009
+.%T Kernel Development in Userspace - The Rump Approach
+.Re
+.Rs
+.%A Antti Kantee
+.%D March 2009
+.%B Proceedings of AsiaBSDCon 2009
+.%P pp. 71-80
+.%T Environmental Independence: BSD Kernel TCP/IP in Userspace
+.Re
+.Sh HISTORY
+An experimental concept for the anykernel and rump kernels was first seen
+during the
+.Nx 5.0
+development cycle.
+A stable concept was ready for
+.Nx 6.0 .