NetBSD/lib/librump/rump.3

.\"     $NetBSD: rump.3,v 1.5 2010/11/19 17:35:04 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 November 19, 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 than 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.
.It Dv RUMP_NVNODES
Sets the value of the kern.maxvnodes sysctl node to the indicated amount.
Adjusting this may be useful for example when testing vnode reclaim
code paths.
While the same value can be set by means of sysctl, the env variable
is often more convenient for quick testing.
As expected, this option has effect only in rump kernels which support VFS.
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.
.Sh SEE ALSO
.Xr p2k 3 ,
.Xr rump_lwproc 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
.Sh NOTE
.Nm
is highly experimental and may change in header location, library
name, API and/or ABI without warning.