[src/trunk]: src/sys/rump/librump/rumpkern update a bit

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

details:   https://anonhg.NetBSD.org/src/rev/c97308618f45
branches:  trunk
changeset: 757370:c97308618f45
user:      pooka <pooka%NetBSD.org@localhost>
date:      Thu Aug 26 22:48:36 2010 +0000

description:
update a bit

diffstat:

 sys/rump/librump/rumpkern/rump.3 |  176 +++++++++++++++++++++++---------------
 1 files changed, 105 insertions(+), 71 deletions(-)

diffs (213 lines):

diff -r 491c4eea7a12 -r c97308618f45 sys/rump/librump/rumpkern/rump.3
--- a/sys/rump/librump/rumpkern/rump.3  Thu Aug 26 19:56:07 2010 +0000
+++ b/sys/rump/librump/rumpkern/rump.3  Thu Aug 26 22:48:36 2010 +0000
@@ -1,6 +1,6 @@
-.\"     $NetBSD: rump.3,v 1.8 2010/05/11 09:45:59 pooka Exp $
+.\"     $NetBSD: rump.3,v 1.9 2010/08/26 22:48:36 pooka Exp $
 .\"
-.\" Copyright (c) 2008 Antti Kantee.  All rights reserved.
+.\" 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
@@ -23,90 +23,122 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 25, 2009
+.Dd August 26, 2010
 .Dt RUMP 3
 .Os
 .Sh NAME
 .Nm rump
-.Nd rump kernel
+.Nd The Rump Anykernel
 .Sh LIBRARY
 rump Library (librump, \-lrump)
 .Sh SYNOPSIS
 .In rump/rump.h
 .In rump/rump_syscalls.h
-.In rump/rumpvnode_if.h
 .Sh DESCRIPTION
 .Nm
-emulates portions of the kernel in order to be able to run kernel code
-from a userspace application.
-For most parts kernel code is directly used, but in some cases such as
-with vm and device drivers a reimplementation suitable for userspace
-is provided.
-All of the routines in
-.Nm
-have been compiled in the kernel namespace with
-.Dv \-D_KERNEL .
-.Pp
-Although
-.Nm
-includes many kernel routines directly, userspace applications should
-not attempt to include
-.Nx
-system headers and call kernel functions directly.
-Instead,
-.Nm
-routines should be called.
-In case applications attempt to include
-.In sys
-headers from the
-.Nx
-tree, collisions will result on other platforms.
-.Pp
-Three classes of routines are provided by
-.Nm :
-.Bl -tag -width XXX -offset indent
-.It Native
-These routines have been handwritten for
+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
-operation.
-Some are useful purely for
-.Nm ,
-while others are merely interfaces to existing kernel routines.
-An example of the former is
-.Fn rump_fakeblk_register ,
-while an example of the latter class is
-.Fn rump_vfs_unmount .
+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
-The routines available in this class can be found from the header
-.In rump.h .
-.It System Calls
-It is possible to execute certain system calls from
-.Nm .
-However, contrary to real system calls, the kernel is never entered,
-but the system call backend code compiled into
-.Nm
-is merely called as a direct function call.
-.Pp
-The autogenerated list of system calls currently available in
-.Nm
-can be found from the header
-.In rump_syscalls.h .
-.It Vnode Interface
-To sort out namespace collisions for
-.Pf non- Nx
-platforms, the whole
-vnode interface set is provided under a special namespace.
-The operation is the same as in the kernel, but the interface names
-begin with the prefix RUMP_VOP.
-.Pp
-This class of routines is available from the autogenerated header
-.In rumpvnode_if.h .
+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
-Before use
-.Nm
-must be initialized by calling
-.Fn rump_init .
+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 ,
@@ -149,6 +181,8 @@
 .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