Module Name: src Committed By: pooka Date: Fri Aug 27 08:21:43 UTC 2010
Added Files: src/lib/librump: rump.3 Removed Files: src/sys/rump/librump/rumpkern: rump.3 Log Message: Move the manpage from the kernel sources into lib, 'cause that's where it's used. To generate a diff of this commit: cvs rdiff -u -r0 -r1.1 src/lib/librump/rump.3 cvs rdiff -u -r1.9 -r0 src/sys/rump/librump/rumpkern/rump.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Added files: Index: src/lib/librump/rump.3 diff -u /dev/null src/lib/librump/rump.3:1.1 --- /dev/null Fri Aug 27 08:21:43 2010 +++ src/lib/librump/rump.3 Fri Aug 27 08:21:43 2010 @@ -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 po...@iki.fi +.Sh NOTE +.Nm +is highly experimental and may change in header location, library +name, API and/or ABI without warning.