191 lines
6.5 KiB
Groff
191 lines
6.5 KiB
Groff
.\" $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
|