Module Name: src Committed By: pooka Date: Thu May 2 11:32:44 UTC 2013
Modified Files: src/lib/librump: rump.3 Log Message: update and bump date To generate a diff of this commit: cvs rdiff -u -r1.11 -r1.12 src/lib/librump/rump.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/lib/librump/rump.3 diff -u src/lib/librump/rump.3:1.11 src/lib/librump/rump.3:1.12 --- src/lib/librump/rump.3:1.11 Tue Apr 30 21:21:24 2013 +++ src/lib/librump/rump.3 Thu May 2 11:32:44 2013 @@ -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. -.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 +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 +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 @@ If set to 0, prevents the rump kernel fr 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 @@ As expected, this option has effect only 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 @@ kernel module boundaries. .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 @@ kernel module boundaries. .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 .