[src/trunk]: src Move the manpage from the kernel sources into lib, 'cause th...

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

details:   https://anonhg.NetBSD.org/src/rev/d56d04196616
branches:  trunk
changeset: 757376:d56d04196616
user:      pooka <pooka%NetBSD.org@localhost>
date:      Fri Aug 27 08:21:43 2010 +0000

description:
Move the manpage from the kernel sources into lib, 'cause that's
where it's used.

diffstat:

 lib/librump/rump.3               |  191 +++++++++++++++++++++++++++++++++++++++
 sys/rump/librump/rumpkern/rump.3 |  191 ---------------------------------------
 2 files changed, 191 insertions(+), 191 deletions(-)

diffs (truncated from 390 to 300 lines):

diff -r a67c61077a6c -r d56d04196616 lib/librump/rump.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/librump/rump.3        Fri Aug 27 08:21:43 2010 +0000
@@ -0,0 +1,191 @@
+.\"     $NetBSD: rump.3,v 1.1 2010/08/27 08:21:43 pooka Exp $
+.\"
+.\" Copyright (c) 2008-2010 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 August 26, 2010
+.Dt RUMP 3
+.Os
+.Sh NAME
+.Nm rump
+.Nd The Rump Anykernel
+.Sh LIBRARY
+rump Library (librump, \-lrump)
+.Sh SYNOPSIS
+.In rump/rump.h
+.In rump/rump_syscalls.h
+.Sh DESCRIPTION
+.Nm
+is part of the realization of a flexible anykernel architecture for
+.Nx .
+An anykernel architecture enables using kernel code in a number of
+different kernel models.
+These models include, but are not limited to, the original monolithic
+kernel, a microkernel server, or an exokernel style application
+library.
+.Nm
+itself makes it possible to run unmodified kernel components in a regular
+userspace process.
+Most of the time "unmodified" means unmodified source code, but some
+architectures can also execute unmodified kernel module binaries
+in userspace.
+Examples of different use models are running file system drivers
+as userspace servers (see
+.Xr p2k 3 )
+and being able to write standalone applications which understand
+file system images.
+.Pp
+Regardless of the kernel model used, a rump kernel is a fullfledged
+kernel with its own virtual namespaces,
+including a file system hierarchy, CPUs, TCP/UDP
+ports, device driver attachments and file descriptors.
+This means that any modification to the system state on the host
+running the rump kernel will not show up in the rump kernel and
+vice versa.
+A rump kernel may also be significantly more lightweight that the
+host, and might not include include for example file system support
+at all.
+.Pp
+A rump kernel is bootstrapped by calling
+.Fn rump_init .
+Before bootstrapping the kernel, it is possible to control its
+functionality by setting various environment variables:
+.Bl -tag -width RUMP_MEMLIMITXX
+.It Dv RUMP_NCPU
+If set, indicates the number of virtual CPUs configured into a
+rump kernel.
+The default is the number of host CPUs.
+The number of virtual CPUs controls how many threads can enter
+the rump kernel simultaneously.
+.It Dv RUMP_VERBOSE
+If set to non-zero, activates bootverbose.
+.It Dv RUMP_THREADS
+If set to 0, prevents the rump kernel from creating any kernel threads.
+This is possible usually only for file systems, as other subsystems
+depend on threads to work.
+.It Dv RUMP_MEMLIMIT
+If set, indicates how many bytes of memory a rump kernel will
+allocate before attempting to purge caches.
+The default is as much as the host allows.
+.El
+.Pp
+A number of interfaces are available for requesting services from
+a rump kernel.
+The most commonly used ones are the rump system calls.
+They are exactly like regular system calls but with the exception
+that they target the rump kernel of the current process instead of
+the host kernel.
+For example,
+.Fn rump_sys_socket
+takes the same parameters as
+.Fn socket
+and will open a socket in the rump kernel.
+The resulting file descriptor may be used only in other rump system
+calls and will have undefined results if passed to the host kernel.
+.Pp
+Another set of interfaces specifically crafted for rump kernels are
+the rump public calls.
+These calls reside in the rump_pub namespace.
+An example is
+.Fn rump_pub_module_init
+which initializes a prelinked kernel module.
+.Pp
+A rump kernel is constructed at build time by linking a set of
+libraries with application level code.
+The mandatory libraries are the kernel base (librump) and the rump
+hypercall library (librumpuser) which a rump kernel uses to request
+services from the host.
+Beyond that, there are three factions which define the flavour of
+a rump kernel (librumpdev, librumpnet and librumpvfs) and driver
+components which use features provided by the base and factions.
+Notably, components may have interdependencies.
+For example, a rump kernel providing a virtual IP router requires
+the following components: rumpnet_netinet rumpnet_net, rumpnet
+rumpnet_virtif, rump and rumpuser.
+A rump kernel providing an NFS client requires the above and
+additionally rumpfs_nfs and rumpvfs.
+.Pp
+In addition to defining the configuration at link time, it is also
+possible to load components at runtime.
+There are two ways of doing this: using
+.Fn dlopen
+to link a shared library into a rump kernel and initializing with
+.Fn rump_pub_module_init
+or specifying a module on the file system to
+.Fn rump_sys_modctl
+and letting the rump kernel do the linking.
+Notably, in the latter case debugging with symbols is not possible
+since the host gdb does not know about symbols loaded by the rump
+kernel.
+Generally speaking, dynamically loadable components must follow
+kernel module boundaries.
+.Sh SEE ALSO
+.Xr p2k 3 ,
+.Xr rumpuser 3 ,
+.Xr ukfs 3
+.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
+.Rs
+.%A Antti Kantee
+.%D May 2009
+.%B BSDCan 2009
+.%T Kernel Development in Userspace - The Rump Approach
+.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 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 March 2010
+.%B Proceedings of AsiaBSDCon 2010
+.%P pp. 75-84
+.%T Rump Device Drivers: Shine On You Kernel Diamond
+.Re
+.Sh HISTORY
+.Nm
+first appeared in
+.Nx 5.0 .
+It underwent a huge number of changes for
+.Nx 6.0 .
+.Sh AUTHORS
+.An Antti Kantee Aq pooka%iki.fi@localhost
+.Sh NOTE
+.Nm
+is highly experimental and may change in header location, library
+name, API and/or ABI without warning.
diff -r a67c61077a6c -r d56d04196616 sys/rump/librump/rumpkern/rump.3
--- a/sys/rump/librump/rumpkern/rump.3  Fri Aug 27 08:15:30 2010 +0000
+++ /dev/null   Thu Jan 01 00:00:00 1970 +0000
@@ -1,191 +0,0 @@
-.\"     $NetBSD: rump.3,v 1.9 2010/08/26 22:48:36 pooka Exp $
-.\"
-.\" Copyright (c) 2008-2010 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 August 26, 2010
-.Dt RUMP 3
-.Os
-.Sh NAME
-.Nm rump
-.Nd The Rump Anykernel
-.Sh LIBRARY
-rump Library (librump, \-lrump)
-.Sh SYNOPSIS
-.In rump/rump.h
-.In rump/rump_syscalls.h
-.Sh DESCRIPTION
-.Nm
-is part of the realization of a flexible anykernel architecture for
-.Nx .
-An anykernel architecture enables using kernel code in a number of
-different kernel models.
-These models include, but are not limited to, the original monolithic
-kernel, a microkernel server, or an exokernel style application
-library.
-.Nm
-itself makes it possible to run unmodified kernel components in a regular
-userspace process.
-Most of the time "unmodified" means unmodified source code, but some
-architectures can also execute unmodified kernel module binaries
-in userspace.
-Examples of different use models are running file system drivers
-as userspace servers (see
-.Xr p2k 3 )
-and being able to write standalone applications which understand
-file system images.
-.Pp
-Regardless of the kernel model used, a rump kernel is a fullfledged
-kernel with its own virtual namespaces,
-including a file system hierarchy, CPUs, TCP/UDP
-ports, device driver attachments and file descriptors.
-This means that any modification to the system state on the host
-running the rump kernel will not show up in the rump kernel and
-vice versa.
-A rump kernel may also be significantly more lightweight that the
-host, and might not include include for example file system support
-at all.
-.Pp
-A rump kernel is bootstrapped by calling
-.Fn rump_init .
-Before bootstrapping the kernel, it is possible to control its
-functionality by setting various environment variables:
-.Bl -tag -width RUMP_MEMLIMITXX
-.It Dv RUMP_NCPU
-If set, indicates the number of virtual CPUs configured into a
-rump kernel.
-The default is the number of host CPUs.
-The number of virtual CPUs controls how many threads can enter
-the rump kernel simultaneously.
-.It Dv RUMP_VERBOSE
-If set to non-zero, activates bootverbose.
-.It Dv RUMP_THREADS
-If set to 0, prevents the rump kernel from creating any kernel threads.
-This is possible usually only for file systems, as other subsystems
-depend on threads to work.
-.It Dv RUMP_MEMLIMIT
-If set, indicates how many bytes of memory a rump kernel will
-allocate before attempting to purge caches.
-The default is as much as the host allows.
-.El
-.Pp
-A number of interfaces are available for requesting services from
-a rump kernel.
-The most commonly used ones are the rump system calls.
-They are exactly like regular system calls but with the exception
-that they target the rump kernel of the current process instead of
-the host kernel.
-For example,
-.Fn rump_sys_socket
-takes the same parameters as
-.Fn socket