sys/rump/librump/rumpkern/rump.3

   1 .\"     $NetBSD: rump.3,v 1.5 2009/06/30 15:28:01 pooka Exp $
   2 .\"
   3 .\" Copyright (c) 2008 Antti Kantee.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd May 25, 2009
  27 .Dt RUMP 3
  28 .Os
  29 .Sh NAME
  30 .Nm rump
  31 .Nd Runnable Userspace Meta Program kernel
  32 .Sh LIBRARY
  33 rump Library (librump, \-lrump)
  34 .Sh SYNOPSIS
  35 .In rump/rump.h
  36 .In rump/rump_syscalls.h
  37 .In rump/rumpvnode_if.h
  38 .Sh DESCRIPTION
  39 .Nm
  40 emulates portions of the kernel in order to be able to run kernel code
  41 from a userspace application.
  42 For most parts kernel code is directly used, but in some cases such as
  43 with vm and device drivers a reimplementation suitable for userspace
  44 is provided.
  45 All of the routines in
  46 .Nm
  47 have been compiled in the kernel namespace with
  48 .Dv \-D_KERNEL .
  49 .Pp
  50 Although
  51 .Nm
  52 includes many kernel routines directly, userspace applications should
  53 not attempt to include
  54 .Nx
  55 system headers and call kernel functions directly.
  56 Instead,
  57 .Nm
  58 routines should be called.
  59 In case applications attempt to include
  60 .In sys
  61 headers from the
  62 .Nx
  63 tree, collisions will result on other platforms.
  64 .Pp
  65 Three classes of routines are provided by
  66 .Nm :
  67 .Bl -tag -width XXX -offset indent
  68 .It Native
  69 These routines have been handwritten for
  70 .Nm
  71 operation.
  72 Some are useful purely for
  73 .Nm ,
  74 while others are merely interfaces to existing kernel routines.
  75 An example of the former is
  76 .Fn rump_fakeblk_register ,
  77 while an example of the latter class is
  78 .Fn rump_vfs_unmount .
  79 .Pp
  80 The routines available in this class can be found from the header
  81 .In rump.h .
  82 .It System Calls
  83 It is possible to execute certain system calls from
  84 .Nm .
  85 However, contrary to real system calls, the kernel is never entered,
  86 but the system call backend code compiled into
  87 .Nm
  88 is merely called as a direct function call.
  89 .Pp
  90 The autogenerated list of system calls currently available in
  91 .Nm
  92 can be found from the header
  93 .In rump_syscalls.h .
  94 .It Vnode Interface
  95 To sort out namespace collisions for
  96 .Pf non- Nx
  97 platforms, the whole
  98 vnode interface set is provided under a special namespace.
  99 The operation is the same as in the kernel, but the interface names
 100 begin with the prefix RUMP_VOP.
 101 .Pp
 102 This class of routines is available from the autogenerated header
 103 .In rumpvnode_if.h .
 104 .El
 105 .Pp
 106 Before use
 107 .Nm
 108 must be initialized by calling
 109 .Fn rump_init .
 110 .Sh SEE ALSO
 111 .Xr p2k 3 ,
 112 .Xr rumpuser 3 ,
 113 .Xr ukfs 3
 114 .Rs
 115 .%A Antti Kantee
 116 .%D March 2009
 117 .%B Proceedings of AsiaBSDCon 2009
 118 .%P pp. 71-80
 119 .%T Environmental Independence: BSD Kernel TCP/IP in Userspace
 120 .Re
 121 .Rs
 122 .%A Antti Kantee
 123 .%D May 2009
 124 .%B BSDCan 2009
 125 .%T Kernel Development in Userspace - The Rump Approach
 126 .Re
 127 .Rs
 128 .%A Antti Kantee
 129 .%D June 2009
 130 .%B Proceedings of the 2009 USENIX Annual Technical Conference
 131 .%P pp. 201-214
 132 .%T Rump File Systems: Kernel Code Reborn
 133 .Re
 134 .Rs
 135 .%A Arnaud Ysmal
 136 .%A Antti Kantee
 137 .%D September 2009
 138 .%B EuroBSDCon 2009
 139 .%T Fs-utils: File Systems Access Tools for Userland
 140 .Re
 141 .Sh HISTORY
 142 .Nm
 143 first appeared in
 144 .Nx 5.0 .
 145 .Sh AUTHORS
 146 .An Antti Kantee Aq pooka@iki.fi
 147 .Sh NOTE
 148 .Nm
 149 is highly experimental and may change in header location, library
 150 name, API and/or ABI without warning.