214 lines
7.6 KiB
Groff
214 lines
7.6 KiB
Groff
.\" $NetBSD: rump.3,v 1.10 2011/04/15 22:57:05 jym Exp $
|
|
.\"
|
|
.\" Copyright (c) 2008-2011 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 March 25, 2011
|
|
.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 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
|
|
.Xr rumphijack 3 .
|
|
.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 rump_server 1 ,
|
|
.Xr p2k 3 ,
|
|
.Xr rump_etfs 3 ,
|
|
.Xr rump_lwproc 3 ,
|
|
.Xr rumpclient 3 ,
|
|
.Xr rumphijack 3 ,
|
|
.Xr rumpuser 3 ,
|
|
.Xr ukfs 3 ,
|
|
.Xr rump_sp 7
|
|
.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
|
|
appeared as an experimental concept in
|
|
.Nx 5.0 .
|
|
The first stable version was released in
|
|
.Nx 6.0 .
|
|
.Sh AUTHORS
|
|
.An Antti Kantee Aq pooka@iki.fi
|