[src/trunk]: src/lib/librump update and bump date

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

details:   https://anonhg.NetBSD.org/src/rev/c7d418054967
branches:  trunk
changeset: 786577:c7d418054967
user:      pooka <pooka%NetBSD.org@localhost>
date:      Thu May 02 11:32:44 2013 +0000

description:
update and bump date

diffstat:

 lib/librump/rump.3 |  190 +++++++++++++++++++++-------------------------------
 1 files changed, 77 insertions(+), 113 deletions(-)

diffs (252 lines):

diff -r 9f2b7d204156 -r c7d418054967 lib/librump/rump.3
--- a/lib/librump/rump.3        Thu May 02 07:17:35 2013 +0000
+++ b/lib/librump/rump.3        Thu May 02 11:32:44 2013 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: rump.3,v 1.11 2013/04/30 21:21:24 pooka Exp $
+.\"     $NetBSD: rump.3,v 1.12 2013/05/02 11:32:44 pooka Exp $
 .\"
 .\" Copyright (c) 2008-2011 Antti Kantee.  All rights reserved.
 .\"
@@ -23,65 +23,58 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd March 25, 2011
+.Dd May 2, 2013
 .Dt RUMP 3
 .Os
 .Sh NAME
 .Nm rump
-.Nd The Rump Anykernel
+.Nd Rump Kernel
 .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.
+A rump kernel is a virtualized kernel instance which retains only part
+of the NetBSD kernel.
+Rump kernels are aimed at virtualizing kernel drivers and do not support
+for example creating processes, managing virtual memory address spaces
+or scheduling threads.
+These features are unnecessary overhead when virtualizing drivers.
+Rump kernels are created by linking a desired set of components together.
+On NetBSD, these components are available as userspace libraries with
+the prefix
+.Pa librump .
+The high-level
+.Xr rumpuser 3
+hypercall interface is used by a rump kernel to request resources and
+services from the host it runs on.
+Like any virtualized kernel, a rump kernel also 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.
 .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 than the
-host, and might not include for example file system support
-at all.
-.Pp
-Clients using services provided by rump kernels can exist either
-in the same process as the rump kernel or in other processes.
-Local clients access the rump kernel through direct function calls.
-They also naturally have access to the kernel memory space.
-This document is geared towards local clients.
-For more information on remote clients,
-see
-.Xr rump_sp 7 .
-It is also possible to use unmodified application binaries as
-remote clients with
+Since a rump kernel does not provide support for applications processes,
+existing entities are used as rump kernel clients.
+The relationship between the client and the rump kernel defines the
+execution model of the rump kernel.
+A local client will reside in the same address space and manipulate the
+rump kernel with function calls and direct memory references.
+Remote and microkernel clients are disjoint from the rump kernel
+and make requests though various protocols, see for example
+.Xr p2k 3 ,
+.Xr rump_sp 7
+and
 .Xr rumphijack 3 .
+Remote clients will also work over a TCP/IP network, or other similar
+communication medium.
 .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:
+A number of environment variables set before a rump kernel is bootstrapped
+will affect how it works.
+Some examples includes:
 .Bl -tag -width RUMP_MEMLIMITXX
 .It Dv RUMP_NCPU
 If set, indicates the number of virtual CPUs configured into a
@@ -96,8 +89,11 @@
 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.
+If set, indicates the maximum amount of memory that a rump kernel will
+request from the hypervisor via
+.Fn rumpuser_malloc .
+When the rump kernel is close to the allocation limit, it will attempt
+to make more memory available by flushing its caches.
 The default is as much as the host allows.
 .It Dv RUMP_NVNODES
 Sets the value of the kern.maxvnodes sysctl node to the indicated amount.
@@ -109,56 +105,22 @@
 The current default is 1024 vnodes.
 .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.
+The standardized way for a client to make requests into a rump kernel
+is to use rump kernel system calls, which have equivalent syntax and
+semantics with regular
+.Nx
+system calls.
+The parameters are expected to be in the NetBSD type system unless a system
+call translation component, for example librumpkern_sys_linux,
+is linked into the rump kernel, in which case system call parameters
+will be automatically translated from the client type system into
+the NetBSD type system and back.
+The rump kernel system calls are made available to a client by
+including
+.In rump/rump_syscalls.h .
+It is also possible to configure unmodified binaries to make syscalls
+into a rump kernel with
+.Xr rumphijack 3 .
 .Sh SEE ALSO
 .Xr rump_server 1 ,
 .Xr p2k 3 ,
@@ -177,19 +139,6 @@
 .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
-.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
@@ -204,14 +153,29 @@
 .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
+.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 Antti Kantee
+.%D May 2009
+.%B BSDCan 2009
+.%T Kernel Development in Userspace - The Rump Approach
+.Re
+.Pp
+Web page with more information, including links to the publications:
+.Lk http://www.NetBSD.org/docs/rump/
 .Sh HISTORY
-.Nm
-appeared as an experimental concept in
+Rump kernels appeared as an experimental concept in
 .Nx 5.0 .
 The first stable version was released in
 .Nx 6.0 .