.\"     $NetBSD: rump.3,v 1.15 2013/08/14 08:29:26 pooka 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 July 14, 2013
.Dt RUMP 3
.Os
.Sh NAME
.Nm rump
.Nd Rump Kernel
.Sh LIBRARY
rump Library (librump, \-lrump)
.Sh SYNOPSIS
.In rump/rump.h
.Sh DESCRIPTION
A rump kernel is a virtualized kernel instance which retains only part
of the
.Nx
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
.Nx ,
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 .
On a POSIX Host, environment variables can be used to adjust some
operating parameters:
.Bl -tag -width RUMP_MEMLIMITXX
.It Dv RUMP_NCPU
If set, the number indicates the number of virtual CPUs configured into a
rump kernel.
The special value "host" can be used to specify the number of
of host CPUs available.
If the value is unset, two CPUs will be configured.
.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 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.
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
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
.Nx
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
.Nx
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 ,
.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 2012
.%J Aalto University Doctoral Dissertations
.%T Flexible Operating System Internals: The Design and Implementation of the Anykernel and Rump Kernerls
.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 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
Rump kernels 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 Mt pooka@iki.fi