unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (NetBSD-6.1.5)
Page:
Section:
Apropos / Subsearch:
optional field

RUMP(3)                    Library Functions Manual                    RUMP(3)

NAME
     rump -- The Rump Anykernel

LIBRARY
     rump Library (librump, -lrump)

SYNOPSIS
     #include <&lt;rump/rump.h>&gt;
     #include <&lt;rump/rump_syscalls.h>&gt;

DESCRIPTION
     rump is part of the realization of a flexible anykernel architecture for
     NetBSD.  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.  rump 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 p2k(3)) and being able to write standalone
     applications which understand file system images.

     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.

     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 rump_sp(7).  It is also possible to use unmodified application
     binaries as remote clients with rumphijack(3).

     A rump kernel is bootstrapped by calling rump_init().  Before
     bootstrapping the kernel, it is possible to control its functionality by
     setting various environment variables:

     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.

     RUMP_VERBOSE     If set to non-zero, activates bootverbose.

     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.

     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.

     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.

     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, rump_sys_socket() takes the same parameters as 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.

     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 rump_pub_module_init() which initializes a prelinked kernel
     module.

     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.

     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 dlopen() to link a shared library into a rump kernel and
     initializing with rump_pub_module_init() or specifying a module on the
     file system to 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.

SEE ALSO
     rump_server(1), p2k(3), rump_etfs(3), rump_lwproc(3), rumpclient(3),
     rumphijack(3), rumpuser(3), ukfs(3), rump_sp(7)

     Antti Kantee, "Environmental Independence: BSD Kernel TCP/IP in
     Userspace", Proceedings of AsiaBSDCon 2009, pp. 71-80, March 2009.

     Antti Kantee, "Kernel Development in Userspace - The Rump Approach",
     BSDCan 2009, May 2009.

     Antti Kantee, "Rump File Systems: Kernel Code Reborn", Proceedings of the
     2009 USENIX Annual Technical Conference, pp. 201-214, June 2009.

     Arnaud Ysmal and Antti Kantee, "Fs-utils: File Systems Access Tools for
     Userland", EuroBSDCon 2009, September 2009.

     Antti Kantee, "Rump Device Drivers: Shine On You Kernel Diamond",
     Proceedings of AsiaBSDCon 2010, pp. 75-84, March 2010.

HISTORY
     rump appeared as an experimental concept in NetBSD 5.0.  The first stable
     version was released in NetBSD 6.0.

AUTHORS
     Antti Kantee <pookaATiki.fi>

NetBSD 6.1.5                    March 25, 2011                    NetBSD 6.1.5