Module Name: src
Committed By: pooka
Date: Sun Nov 9 17:39:38 UTC 2014
Modified Files:
src/lib/librump: Makefile
src/lib/librumpuser: Makefile
src/lib/librumpvfs: Makefile
src/share/man: Makefile
src/sys/rump: Makefile
src/sys/rump/librump/rumpkern: Makefile.rumpkern
src/sys/rump/librump/rumpvfs: Makefile.rumpvfs
Added Files:
src/sys/rump/librump/rumpkern: rump.3 rump_lwproc.3
src/sys/rump/librump/rumpvfs: rump_etfs.3 rumpfs.4
src/sys/rump/share: Makefile
src/sys/rump/share/man: Makefile
src/sys/rump/share/man/man3: Makefile rumpuser.3
src/sys/rump/share/man/man7: Makefile rump_sp.7
Removed Files:
src/lib/librump: rump.3 rump_lwproc.3 rump_sp.7
src/lib/librumpuser: rumpuser.3
src/lib/librumpvfs: rump_etfs.3 rumpfs.4
Log Message:
Move rump kernel man pages from various sources to sys/rump
namely:
* src/lib is used only when building for POSIX'y platforms, but
the man pages have their use for all platforms
* rumpuser.3 is a function of the rump kernel, not one of the of
the POSIX'y implementation hosted in src/lib/librumpuser
no functional change
To generate a diff of this commit:
cvs rdiff -u -r1.4 -r1.5 src/lib/librump/Makefile
cvs rdiff -u -r1.15 -r0 src/lib/librump/rump.3
cvs rdiff -u -r1.7 -r0 src/lib/librump/rump_lwproc.3 \
src/lib/librump/rump_sp.7
cvs rdiff -u -r1.22 -r1.23 src/lib/librumpuser/Makefile
cvs rdiff -u -r1.19 -r0 src/lib/librumpuser/rumpuser.3
cvs rdiff -u -r1.4 -r1.5 src/lib/librumpvfs/Makefile
cvs rdiff -u -r1.8 -r0 src/lib/librumpvfs/rump_etfs.3
cvs rdiff -u -r1.2 -r0 src/lib/librumpvfs/rumpfs.4
cvs rdiff -u -r1.32 -r1.33 src/share/man/Makefile
cvs rdiff -u -r1.6 -r1.7 src/sys/rump/Makefile
cvs rdiff -u -r1.149 -r1.150 src/sys/rump/librump/rumpkern/Makefile.rumpkern
cvs rdiff -u -r0 -r1.11 src/sys/rump/librump/rumpkern/rump.3
cvs rdiff -u -r0 -r1.1 src/sys/rump/librump/rumpkern/rump_lwproc.3
cvs rdiff -u -r1.41 -r1.42 src/sys/rump/librump/rumpvfs/Makefile.rumpvfs
cvs rdiff -u -r0 -r1.1 src/sys/rump/librump/rumpvfs/rump_etfs.3 \
src/sys/rump/librump/rumpvfs/rumpfs.4
cvs rdiff -u -r0 -r1.1 src/sys/rump/share/Makefile
cvs rdiff -u -r0 -r1.1 src/sys/rump/share/man/Makefile
cvs rdiff -u -r0 -r1.1 src/sys/rump/share/man/man3/Makefile \
src/sys/rump/share/man/man3/rumpuser.3
cvs rdiff -u -r0 -r1.1 src/sys/rump/share/man/man7/Makefile \
src/sys/rump/share/man/man7/rump_sp.7
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/librump/Makefile
diff -u src/lib/librump/Makefile:1.4 src/lib/librump/Makefile:1.5
--- src/lib/librump/Makefile:1.4 Thu Dec 16 15:29:28 2010
+++ src/lib/librump/Makefile Sun Nov 9 17:39:37 2014
@@ -1,10 +1,9 @@
-# $NetBSD: Makefile,v 1.4 2010/12/16 15:29:28 pooka Exp $
+# $NetBSD: Makefile,v 1.5 2014/11/09 17:39:37 pooka Exp $
#
RUMPTOP= ${.CURDIR}/../../sys/rump
LIBDPLIBS+= rumpuser ${.CURDIR}/../librumpuser
-MAN= rump.3 rump_lwproc.3 rump_sp.7
WARNS= 3 # XXX: kernel isn't ready for -Wsign-compare
Index: src/lib/librumpuser/Makefile
diff -u src/lib/librumpuser/Makefile:1.22 src/lib/librumpuser/Makefile:1.23
--- src/lib/librumpuser/Makefile:1.22 Tue Oct 28 23:48:03 2014
+++ src/lib/librumpuser/Makefile Sun Nov 9 17:39:37 2014
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.22 2014/10/28 23:48:03 pooka Exp $
+# $NetBSD: Makefile,v 1.23 2014/11/09 17:39:37 pooka Exp $
#
.include <bsd.own.mk>
@@ -52,8 +52,6 @@ SRCS+= rumpuser_dl.c rumpuser_daemonize
INCSDIR= /usr/include/rump
INCS= rumpuser_component.h rumpuser_port.h
-MAN= rumpuser.3
-
CPPFLAGS+= -D_REENTRANT
.include <bsd.lib.mk>
Index: src/lib/librumpvfs/Makefile
diff -u src/lib/librumpvfs/Makefile:1.4 src/lib/librumpvfs/Makefile:1.5
--- src/lib/librumpvfs/Makefile:1.4 Mon Mar 3 18:27:20 2014
+++ src/lib/librumpvfs/Makefile Sun Nov 9 17:39:37 2014
@@ -1,10 +1,9 @@
-# $NetBSD: Makefile,v 1.4 2014/03/03 18:27:20 pooka Exp $
+# $NetBSD: Makefile,v 1.5 2014/11/09 17:39:37 pooka Exp $
#
RUMPTOP= ${.CURDIR}/../../sys/rump
LIBDPLIBS+= rump ${.CURDIR}/../librump
-MAN= rump_etfs.3 rumpfs.4
WARNS= 3 # XXX: kernel isn't ready for -Wsign-compare
Index: src/share/man/Makefile
diff -u src/share/man/Makefile:1.32 src/share/man/Makefile:1.33
--- src/share/man/Makefile:1.32 Thu Jan 16 01:15:33 2014
+++ src/share/man/Makefile Sun Nov 9 17:39:37 2014
@@ -1,10 +1,11 @@
-# $NetBSD: Makefile,v 1.32 2014/01/16 01:15:33 christos Exp $
+# $NetBSD: Makefile,v 1.33 2014/11/09 17:39:37 pooka Exp $
# from: @(#)Makefile 8.2 (Berkeley) 4/16/94
.include <bsd.own.mk>
.if ${MKSHARE} != "no"
SUBDIR= man0 man1 man2 man3 man3lua man4 man5 man6 man7 man8 man9 man9lua
+SUBDIR+=${.CURDIR}/../../sys/rump/share/man
WHATISDBDIR?= /usr/share/man
Index: src/sys/rump/Makefile
diff -u src/sys/rump/Makefile:1.6 src/sys/rump/Makefile:1.7
--- src/sys/rump/Makefile:1.6 Thu Jun 10 21:56:42 2010
+++ src/sys/rump/Makefile Sun Nov 9 17:39:37 2014
@@ -1,6 +1,9 @@
-# $NetBSD: Makefile,v 1.6 2010/06/10 21:56:42 pooka Exp $
+# $NetBSD: Makefile,v 1.7 2014/11/09 17:39:37 pooka Exp $
#
-SUBDIR= include librump dev fs kern net
+SUBDIR= include
+SUBDIR+= librump
+SUBDIR+= dev fs kern net
+SUBDIR+= share
.include <bsd.subdir.mk>
Index: src/sys/rump/librump/rumpkern/Makefile.rumpkern
diff -u src/sys/rump/librump/rumpkern/Makefile.rumpkern:1.149 src/sys/rump/librump/rumpkern/Makefile.rumpkern:1.150
--- src/sys/rump/librump/rumpkern/Makefile.rumpkern:1.149 Mon Aug 11 22:03:25 2014
+++ src/sys/rump/librump/rumpkern/Makefile.rumpkern Sun Nov 9 17:39:38 2014
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile.rumpkern,v 1.149 2014/08/11 22:03:25 matt Exp $
+# $NetBSD: Makefile.rumpkern,v 1.150 2014/11/09 17:39:38 pooka Exp $
#
.include "${RUMPTOP}/Makefile.rump"
@@ -7,6 +7,8 @@
LIB= rump
+MAN= rump.3 rump_lwproc.3
+
.PATH: ${RUMPTOP}/librump/rumpkern \
${RUMPTOP}/librump/rumpkern/arch/generic \
${RUMPTOP}/../kern \
Index: src/sys/rump/librump/rumpvfs/Makefile.rumpvfs
diff -u src/sys/rump/librump/rumpvfs/Makefile.rumpvfs:1.41 src/sys/rump/librump/rumpvfs/Makefile.rumpvfs:1.42
--- src/sys/rump/librump/rumpvfs/Makefile.rumpvfs:1.41 Sun Apr 27 15:15:13 2014
+++ src/sys/rump/librump/rumpvfs/Makefile.rumpvfs Sun Nov 9 17:39:38 2014
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile.rumpvfs,v 1.41 2014/04/27 15:15:13 pooka Exp $
+# $NetBSD: Makefile.rumpvfs,v 1.42 2014/11/09 17:39:38 pooka Exp $
#
.include "${RUMPTOP}/Makefile.rump"
@@ -7,6 +7,8 @@
LIB= rumpvfs
+MAN= rump_etfs.3 rumpfs.4
+
.PATH: ${RUMPTOP}/librump/rumpvfs ${RUMPTOP}/librump \
${RUMPTOP}/../kern \
${RUMPTOP}/../miscfs/genfs ${RUMPTOP}/../miscfs/syncfs \
Added files:
Index: src/sys/rump/librump/rumpkern/rump.3
diff -u /dev/null src/sys/rump/librump/rumpkern/rump.3:1.11
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/librump/rumpkern/rump.3 Sun Nov 9 17:39:38 2014
@@ -0,0 +1,190 @@
+.\" $NetBSD: rump.3,v 1.11 2014/11/09 17:39:38 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 po...@iki.fi
Index: src/sys/rump/librump/rumpkern/rump_lwproc.3
diff -u /dev/null src/sys/rump/librump/rumpkern/rump_lwproc.3:1.1
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/librump/rumpkern/rump_lwproc.3 Sun Nov 9 17:39:38 2014
@@ -0,0 +1,145 @@
+.\" $NetBSD: rump_lwproc.3,v 1.1 2014/11/09 17:39:38 pooka Exp $
+.\"
+.\" Copyright (c) 2010 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 October 27, 2014
+.Dt RUMP_LWPROC 3
+.Os
+.Sh NAME
+.Nm rump_lwproc
+.Nd rump kernel process/lwp management
+.Sh LIBRARY
+rump kernel (librump, \-lrump)
+.Sh SYNOPSIS
+.In rump/rump.h
+.Ft int
+.Fn rump_pub_lwproc_rfork "int flags"
+.Ft int
+.Fn rump_pub_lwproc_newlwp "pid_t pid"
+.Ft void
+.Fn rump_pub_lwproc_switch "struct lwp *l"
+.Ft void
+.Fn rump_pub_lwproc_releaselwp
+.Ft struct lwp *
+.Fn rump_pub_lwproc_curlwp
+.Sh DESCRIPTION
+In a normal operating system model a process is a resource
+container and a thread (lwp) is the execution context.
+Every lwp is associated with exactly one process, and a process is
+associated with one or more lwps.
+The current lwp (curlwp) indicates the current process and determines
+which resources, such as UID/GID, current working directory, and
+file descriptor table, are currently used.
+These basic principles apply to rump kernels as well, but since
+a rump kernel uses the host's thread and process context directly, the rules
+for how thread context is determined are different.
+.Pp
+In the rump kernel model, each host thread (implemented for example
+with pthreads or green threads) is either bound to
+a rump kernel lwp or accesses the rump kernel with an implicit thread
+context associated with pid 1.
+An implicit thread context is created every time the rump kernel
+is entered and disbanded upon exit.
+While convenient for occasional calls, creating an implicit thread
+uses a shared resource which can become highly contended in a
+multithreaded situation.
+It is therefore recommended that dedicated threads are created.
+.Pp
+The association between host threads and the rump kernel curlwp is
+left to the caller.
+It is possible to create a dedicated host thread for every
+rump kernel lwp or multiplex them on top of a single host thread.
+After rump kernel lwps have been created, switching curlwp is very cheap.
+In case multiple lwps/processes are created, it is the caller's
+responsibility to keep track of them and release them when they
+are no longer necessary.
+A rump kernel lwp will persist until it is explicitly released.
+A rump kernel process will persist until all of its lwps have been
+released, at which point the process is automatically released.
+.Bl -tag -width xxxx
+.It Fn rump_pub_lwproc_rfork
+Create a process, one lwp inside it and set curlwp to the new lwp.
+The
+.Ar flags
+parameter controls how file descriptors are inherited from the
+parent.
+By default (flags=0) file descriptors are shared.
+Other options are:
+.Bl -tag -width RUMP_RFCFDGXX
+.It Dv RUMP_RFFDG
+Copy file descriptors from parent.
+This is what
+.Xr fork 2
+does.
+.It Dv RUMP_RFCFDG
+File descriptors neither copied nor shared, i.e. new process does not
+have access to the parent's file descriptors.
+.El
+.Pp
+This routine returns 0 for success or an errno indicating the reason
+for failure.
+The new process id can be retrieved in the normal fashion by calling
+.Fn rump_sys_getpid .
+.It Fn rump_pub_lwproc_newlwp "pid"
+Create a new lwp attached to the process specified by
+.Fa pid .
+Sets curlwp to the new lwp.
+This routine returns 0 for success or an errno indicating the reason
+for failure.
+.It Fn rump_pub_lwproc_switch "l"
+Sets curlwp to
+.Fa l .
+In case the new thread is associated with a different process than the
+current one, the process context is also switched.
+The special value
+.Dv NULL
+sets curlwp to implicit context.
+Switching to an already running lwp, i.e. attempting to use the
+same curlwp in two host threads simultaneously causes a fatal error.
+.It Fn rump_pub_lwproc_releaselwp
+Release curlwp and set curlwp to context.
+In case curlwp was the last thread inside the current process, the
+process container is also released.
+Calling this routine without a dedicated curlwp is a fatal error.
+.It Fn rump_pub_lwproc_curlwp
+Returns curlwp or
+.Dv NULL
+if the current context is an implicit context.
+.El
+.Sh RETURN VALUES
+.Fn rump_pub_lwproc_rfork
+and
+.Fn rump_pub_lwproc_newlwp
+return 0 on success or an errno indicating the reason for failure.
+.Fn rump_pub_lwproc_curlwp
+returns curlwp or
+.Dv NULL
+if the current context is an implicit context.
+.Sh SEE ALSO
+.Xr getpid 2 ,
+.Xr rump 3
+.Sh HISTORY
+.Nm
+first appeared in
+.Nx 6.0 .
Index: src/sys/rump/librump/rumpvfs/rump_etfs.3
diff -u /dev/null src/sys/rump/librump/rumpvfs/rump_etfs.3:1.1
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/librump/rumpvfs/rump_etfs.3 Sun Nov 9 17:39:38 2014
@@ -0,0 +1,213 @@
+.\" $NetBSD: rump_etfs.3,v 1.1 2014/11/09 17:39:38 pooka Exp $
+.\"
+.\" Copyright (c) 2010 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 October 27, 2014
+.Dt RUMP_ETFS 3
+.Os
+.Sh NAME
+.Nm rump_etfs
+.Nd rump host file system interface
+.Sh LIBRARY
+rump kernel (librump, \-lrump)
+.Sh SYNOPSIS
+.In rump/rump.h
+.Ft int
+.Fo rump_pub_etfs_register
+.Fa "const char *key" "const char *hostpath" "enum rump_etfs_type ftype"
+.Fc
+.Ft int
+.Fo rump_pub_etfs_register_withsize
+.Fa "const char *key" "const char *hostpath" "enum rump_etfs_type ftype"
+.Fa "uint64_t begin" "uint64_t size"
+.Fc
+.Ft void
+.Fn rump_boot_etfs_register "struct rump_boot_etfs *eb"
+.Ft int
+.Fn rump_pub_etfs_remove "const char *key"
+.Sh DESCRIPTION
+The rump ExtraTerrestrial File System
+.Nm ( )
+is used to provide access to the host file system namespace
+within a rump kernel.
+.Pp
+The operation is based on registered
+.Fa key
+values which each map to a
+.Fa hostpath .
+A key must be an absolute path (i.e. begin with
+.Dq / ) .
+Multiple leading slashes are collapsed to one (i.e.
+.Dq /key
+is the same as
+.Dq //key ) .
+The rest of the path, including slashes, is compared verbatim (i.e.
+.Dq /key/path
+does not match
+.Dq /key//path ) .
+.Pp
+The
+.Fa hostpath
+is interpreted in host system context for the current working directory
+and can be either absolute or relative.
+.Pp
+The
+.Fa key
+is accessible from all rump kernel clients, both local and remote.
+Note, the keys are not be visible via readdir, so you will not see
+them in directory listings.
+.Pp
+The
+.Fa ftype
+parameter specifies how etfs file will be presented and does not
+have to match the host type, although some limitations apply.
+Possible values are:
+.Bl -tag -width RUMP_ETFS_DIR_SUBDIRSXXX
+.It Dv RUMP_ETFS_REG
+regular file.
+.It Dv RUMP_ETFS_BLK
+block device.
+This is often used when mapping file system images.
+.It Dv RUMP_ETFS_CHR
+character device.
+.It Dv RUMP_ETFS_DIR
+directory.
+This option is valid only when
+.Fa hostpath
+is a directory.
+The immediate children of the host directory will be accessible
+inside a rump kernel.
+.It Dv RUMP_ETFS_DIR_SUBDIRS
+directory.
+This option is valid only when
+.Fa hostpath
+is a directory.
+This option recursively applies to all subdirectories, and allows
+a rump kernel to access an entire directory tree.
+.El
+.Pp
+The interfaces are:
+.Bl -tag -width xxxx
+.It Fn rump_pub_etfs_register "key" "hostpath" "ftype"
+Map
+.Fa key
+to a file of type
+.Fa ftype
+with the contents of
+.Fa hostpath .
+.It Fn rump_pub_etfs_register_withsize "key" "hostpath" "ftype" "begin" "size"
+Like the above, but map only
+.Fa [ begin , begin+size ]
+from
+.Fa hostpath .
+This is useful when mapping disk images where only one partition is
+relevant to the application.
+If
+.Ar size
+is given the special value
+.Dv RUMP_ETFS_SIZE_ENDOFF ,
+the underlying file is mapped from
+.Ar begin
+to the end of the file.
+.It Fn rump_boot_etfs_register "eb"
+Unlike the above interfaces,
+.Fn rump_boot_etfs_register
+can and must be called before
+.Fn rump_init .
+It causes an etfs key to be available immediately when the root file
+system is mounted as part of
+.Fn rump_init .
+The intended use is for example for firmware images to be available
+immediately when device driver autoconfiguration is run as part of
+.Fn rump_init .
+.Pp
+To use
+.Fn rump_boot_etfs_register ,
+the client fills out
+.Fa eb .
+The layout of
+.Fa eb
+is as follows:
+.Bd -literal
+struct rump_boot_etfs {
+ /* client initializes */
+ const char *eb_key;
+ const char *eb_hostpath;
+ enum rump_etfs_type eb_type;
+ uint64_t eb_begin;
+ uint64_t eb_size;
+
+ /* rump kernel initializes */
+ struct rump_boot_etfs *_eb_next;
+ int eb_status;
+};
+.Ed
+.Pp
+All of the client fields must be initialized before the call.
+See
+.Fn rump_pub_etfs_register_withsize
+for descriptions of the fields.
+After the function has been called, the client may not touch the
+structure memory or the pathname pointers.
+After
+.Fn rump_init
+returns, the client may check the status of the registration from
+.Fa eb_status
+and free the structure.
+A value of \-1 designates that the etfs registration was not
+performed, 0 designates success and a value larger than 0 designates
+an errno.
+The client must serialize calls to
+.Fn rump_boot_etfs_register .
+.It Fn rump_pub_etfs_remove "key"
+Remove etfs mapping for
+.Fa key .
+This routine may be called only if the file related to the mapping
+is not in use.
+.El
+.Sh RETURN VALUES
+.Nm
+routines return 0 on success or an errno indicating the reason for failure.
+.Sh EXAMPLES
+Map a host image file to a mountable
+.Pa /dev/harddisk
+path using window offsets from the disklabel.
+.Bd -literal -offset indent
+rump_pub_etfs_register_withsize("/dev/harddisk", "disk.img",
+ RUMP_ETFS_BLK,
+ pp->p_offset << DEV_BSHIFT, pp->p_size << DEV_BSHIFT);
+.Ed
+.Pp
+Make the host kernel module directory hierarchy available within the
+rump kernel.
+.Bd -literal -offset indent
+rump_pub_etfs_register("/stand/i386/5.99.41",
+ "/stand/i386/5.99.41", RUMP_ETFS_DIR_SUBDIRS);
+.Ed
+.Sh SEE ALSO
+.Xr rump 3
+.Sh HISTORY
+.Nm
+first appeared in
+.Nx 6.0 .
Index: src/sys/rump/librump/rumpvfs/rumpfs.4
diff -u /dev/null src/sys/rump/librump/rumpvfs/rumpfs.4:1.1
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/librump/rumpvfs/rumpfs.4 Sun Nov 9 17:39:38 2014
@@ -0,0 +1,67 @@
+.\" $NetBSD: rumpfs.4,v 1.1 2014/11/09 17:39:38 pooka Exp $
+.\"
+.\" Copyright (c) 2014 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 3, 2014
+.Dt RUMPFS 4
+.Os
+.Sh NAME
+.Nm rumpfs
+.Nd rump kernel root file system
+.Sh LIBRARY
+rump kernel (librumpvfs, \-lrumpvfs)
+.Sh DESCRIPTION
+.Nm
+is a simple in-memory file system for rump kernels.
+It is automatically mounted as the root file system of a rump kernel
+at boot time, provided that the VFS faction is configured into the rump
+kernel instance.
+.Pp
+The three main features of
+.Nm
+are:
+.Bl -enum -offset indent
+.It
+providing a hook for accessing host files via the
+.Xr rump_etfs 3
+interfaces.
+.It
+supporting enough of file and directory interfaces to facilitate simple
+operations such as hosting config files or creating mount points.
+.It
+being small and lightweight so as to keep a barebones rump kernel
+lightweight.
+.El
+.Pp
+.Nm
+is not intended for hosting large files or big directory
+hierarchies.
+If faced with such a use case, mounting a tmpfs file system
+inside the rump kernel is recommended.
+.Sh SEE ALSO
+.Xr rump 3
+.Sh HISTORY
+.Nm
+first appeared in
+.Nx 6.0 .
Index: src/sys/rump/share/Makefile
diff -u /dev/null src/sys/rump/share/Makefile:1.1
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/share/Makefile Sun Nov 9 17:39:38 2014
@@ -0,0 +1,3 @@
+SUBDIR= man
+
+.include <bsd.subdir.mk>
Index: src/sys/rump/share/man/Makefile
diff -u /dev/null src/sys/rump/share/man/Makefile:1.1
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/share/man/Makefile Sun Nov 9 17:39:38 2014
@@ -0,0 +1,3 @@
+SUBDIR= man3 man7
+
+.include <bsd.subdir.mk>
Index: src/sys/rump/share/man/man3/Makefile
diff -u /dev/null src/sys/rump/share/man/man3/Makefile:1.1
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/share/man/man3/Makefile Sun Nov 9 17:39:38 2014
@@ -0,0 +1,5 @@
+# $NetBSD: Makefile,v 1.1 2014/11/09 17:39:38 pooka Exp $
+
+MAN= rumpuser.3
+
+.include <bsd.man.mk>
Index: src/sys/rump/share/man/man3/rumpuser.3
diff -u /dev/null src/sys/rump/share/man/man3/rumpuser.3:1.1
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/share/man/man3/rumpuser.3 Sun Nov 9 17:39:38 2014
@@ -0,0 +1,782 @@
+.\" $NetBSD: rumpuser.3,v 1.1 2014/11/09 17:39:38 pooka Exp $
+.\"
+.\" Copyright (c) 2013 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 August 24, 2014
+.Dt RUMPUSER 3
+.Os
+.Sh NAME
+.Nm rumpuser
+.Nd rump kernel hypercall interface
+.Sh LIBRARY
+rump User Library (librumpuser, \-lrumpuser)
+.Sh SYNOPSIS
+.In rump/rumpuser.h
+.Sh DESCRIPTION
+The
+.Nm
+hypercall interfaces allow a rump kernel to access host resources.
+A hypervisor implementation must implement the routines described in
+this document to allow a rump kernel to run on the host.
+The implementation included in
+.Nx
+is for POSIX-like hosts (*BSD, Linux, etc.).
+This document is divided into sections based on the functionality
+group of each hypercall.
+.Pp
+Since the hypercall interface is a C function interface, both the
+rump kernel and the hypervisor must conform to the same ABI.
+The interface itself attempts to assume as little as possible from
+the type systems, and for example
+.Vt off_t
+is passed as
+.Vt int64_t
+and enums are passed as ints.
+It is recommended that the hypervisor converts these to the native
+types before starting to process the hypercall, for example by
+assigning the ints back to enums.
+.Sh UPCALLS AND RUMP KERNEL CONTEXT
+A hypercall is always entered with the calling thread scheduled in
+the rump kernel.
+In case the hypercall intends to block while waiting for an event,
+the hypervisor must first release the rump kernel scheduling context.
+In other words, the rump kernel context is a resource and holding
+on to it while waiting for a rump kernel event/resource may lead
+to a deadlock.
+Even when there is no possibility of deadlock in the strict sense
+of the term, holding on to the rump kernel context while performing
+a slow hypercall such as reading a device will prevent other threads
+(including the clock interrupt) from using that rump kernel context.
+.Pp
+Releasing the context is done by calling the
+.Fn hyp_backend_unschedule
+upcall which the hypervisor received from rump kernel as a parameter
+for
+.Fn rumpuser_init .
+Before a hypercall returns back to the rump kernel, the returning thread
+must carry a rump kernel context.
+In case the hypercall unscheduled itself, it must reschedule itself
+by calling
+.Fn hyp_backend_schedule .
+.Sh HYPERCALL INTERFACES
+.Ss Initialization
+.Ft int
+.Fn rumpuser_init "int version" "struct rump_hyperup *hyp"
+.Pp
+Initialize the hypervisor.
+.Bl -tag -width "xenum_rumpclock"
+.It Fa version
+hypercall interface version number that the kernel expects to be used.
+In case the hypervisor cannot provide an exact match, this routine must
+return a non-zero value.
+.It Fa hyp
+pointer to a set of upcalls the hypervisor can make into the rump kernel
+.El
+.Ss Memory allocation
+.Ft int
+.Fn rumpuser_malloc "size_t len" "int alignment" "void **memp"
+.Bl -tag -width "xenum_rumpclock"
+.It Fa len
+amount of memory to allocate
+.It Fa alignment
+size the returned memory must be aligned to.
+For example, if the value passed is 4096, the returned memory
+must be aligned to a 4k boundary.
+.It Fa memp
+return pointer for allocated memory
+.El
+.Pp
+.Ft void
+.Fn rumpuser_free "void *mem" "size_t len"
+.Bl -tag -width "xenum_rumpclock"
+.It Fa mem
+memory to free
+.It Fa len
+length of allocation.
+This is always equal to the amount the caller requested from the
+.Fn rumpuser_malloc
+which returned
+.Fa mem .
+.El
+.Ss Files and I/O
+.Ft int
+.Fn rumpuser_open "const char *name" "int mode" "int *fdp"
+.Pp
+Open
+.Fa name
+for I/O and associate a file descriptor with it.
+Notably, there needs to be no mapping between
+.Fa name
+and the host's file system namespace.
+For example, it is possible to associate the file descriptor with
+device I/O registers for special values of
+.Fa name .
+.Bl -tag -width "xenum_rumpclock"
+.It Fa name
+the identifier of the file to open for I/O
+.It Fa mode
+combination of the following:
+.Bl -tag -width "XRUMPUSER_OPEN_CREATE"
+.It Dv RUMPUSER_OPEN_RDONLY
+open only for reading
+.It Dv RUMPUSER_OPEN_WRONLY
+open only for writing
+.It Dv RUMPUSER_OPEN_RDWR
+open for reading and writing
+.It Dv RUMPUSER_OPEN_CREATE
+do not treat missing
+.Fa name
+as an error
+.It Dv RUMPUSER_OPEN_EXCL
+combined with
+.Dv RUMPUSER_OPEN_CREATE ,
+flag an error if
+.Fa name
+already exists
+.It Dv RUMPUSER_OPEN_BIO
+the caller will use this file for block I/O, usually used in
+conjunction with accessing file system media.
+The hypervisor should treat this flag as advisory and possibly
+enable some optimizations for
+.Fa *fdp
+based on it.
+.El
+Notably, the permissions of the created file are left up to the
+hypervisor implementation.
+.It Fa fdp
+An integer value denoting the open file is returned here.
+.El
+.Pp
+.Ft int
+.Fn rumpuser_close "int fd"
+.Pp
+Close a previously opened file descriptor.
+.Pp
+.Ft int
+.Fn rumpuser_getfileinfo "const char *name" "uint64_t *size" "int *type"
+.Bl -tag -width "xenum_rumpclock"
+.It Fa name
+file for which information is returned.
+The namespace is equal to that of
+.Fn rumpuser_open .
+.It Fa size
+If
+.Pf non- Dv NULL ,
+size of the file is returned here.
+.It Fa type
+If
+.Pf non- Dv NULL ,
+type of the file is returned here.
+The options are
+.Dv RUMPUSER_FT_DIR ,
+.Dv RUMPUSER_FT_REG ,
+.Dv RUMPUSER_FT_BLK ,
+.Dv RUMPUSER_FT_CHR ,
+or
+.Dv RUMPUSER_FT_OTHER
+for directory, regular file, block device, character device or unknown,
+respectively.
+.El
+.Pp
+.Ft void
+.Fo rumpuser_bio
+.Fa "int fd" "int op" "void *data" "size_t dlen" "int64_t off"
+.Fa "rump_biodone_fn biodone" "void *donearg"
+.Fc
+.Pp
+Initiate block I/O and return immediately.
+.Bl -tag -width "xenum_rumpclock"
+.It Fa fd
+perform I/O on this file descriptor.
+The file descriptor must have been opened with
+.Dv RUMPUSER_OPEN_BIO .
+.It Fa op
+Transfer data from the file descriptor with
+.Dv RUMPUSER_BIO_READ
+and transfer data to the file descriptor with
+.Dv RUMPUSER_BIO_WRITE .
+Unless
+.Dv RUMPUSER_BIO_SYNC
+is specified, the hypervisor may cache a write instead of
+committing it to permanent storage.
+.It Fa data
+memory address to transfer data to/from
+.It Fa dlen
+length of I/O.
+The length is guaranteed to be a multiple of 512.
+.It Fa off
+offset into
+.Fa fd
+where I/O is performed
+.It Fa biodone
+To be called when the I/O is complete.
+Accessing
+.Fa data
+is not legal after the call is made.
+.It Fa donearg
+opaque arg that must be passed to
+.Fa biodone .
+.El
+.Pp
+.Ft int
+.Fo rumpuser_iovread
+.Fa "int fd" "struct rumpuser_iovec *ruiov" "size_t iovlen"
+.Fa "int64_t off" "size_t *retv"
+.Fc
+.Pp
+.Ft int
+.Fo rumpuser_iovwrite
+.Fa "int fd" "struct rumpuser_iovec *ruiov" "size_t iovlen"
+.Fa "int64_t off" "size_t *retv"
+.Fc
+.Pp
+These routines perform scatter-gather I/O which is not
+block I/O by nature and therefore cannot be handled by
+.Fn rumpuser_bio .
+.Pp
+.Bl -tag -width "xenum_rumpclock"
+.It Fa fd
+file descriptor to perform I/O on
+.It Fa ruiov
+an array of I/O descriptors.
+It is defined as follows:
+.Bd -literal -offset indent -compact
+struct rumpuser_iovec {
+ void *iov_base;
+ size_t iov_len;
+};
+.Ed
+.It Fa iovlen
+number of elements in
+.Fa ruiov
+.It Fa off
+offset of
+.Fa fd
+to perform I/O on.
+This can either be a non-negative value or
+.Dv RUMPUSER_IOV_NOSEEK .
+The latter denotes that no attempt to change the underlying objects
+offset should be made.
+Using both types of offsets on a single instance of
+.Fa fd
+results in undefined behavior.
+.It Fa retv
+number of bytes successfully transferred is returned here
+.El
+.Pp
+.Ft int
+.Fo rumpuser_syncfd
+.Fa "int fd" "int flags" "uint64_t start" "uint64_t len"
+.Fc
+.Pp
+Synchronizes
+.Fa fd
+with respect to backing storage.
+The other arguments are:
+.Pp
+.Bl -tag -width "xenum_rumpclock"
+.It Fa flags
+controls how synchronization happens.
+It must contain one of the following:
+.Bl -tag -width "XRUMPUSER_SYNCFD_BARRIER"
+.It Dv RUMPUSER_SYNCFD_READ
+Make sure that the next read sees writes from all other parties.
+This is useful for example in the case that
+.Fa fd
+represents memory to write a DMA read is being performed.
+.It Dv RUMPUSER_SYNCFD_WRITE
+Flush cached writes.
+.El
+.Pp
+The following additional parameters may be passed in
+.Fa flags :
+.Pp
+.Bl -tag -width "XRUMPUSER_SYNCFD_BARRIER"
+.It Dv RUMPUSER_SYNCFD_BARRIER
+Issue a barrier.
+Outstanding I/O operations which were started before the barrier
+complete before any operations after the barrier are performed.
+.It Dv RUMPUSER_SYNCFD_SYNC
+Wait for the synchronization operation to fully complete before
+returning.
+For example, this could mean that the data to be written to a disk
+has hit either the disk or non-volatile memory.
+.El
+.It Fa start
+offset into the object.
+.It Fa len
+the number of bytes to synchronize.
+The value 0 denotes until the end of the object.
+.El
+.Ss Clocks
+The hypervisor should support two clocks, one for wall time and one
+for monotonically increasing time, the latter of which may be based
+on some arbitrary time (e.g. system boot time).
+If this is not possible, the hypervisor must make a reasonable effort to
+retain semantics.
+.Pp
+.Ft int
+.Fn rumpuser_clock_gettime "int enum_rumpclock" "int64_t *sec" "long *nsec"
+.Pp
+.Bl -tag -width "xenum_rumpclock"
+.It Fa enum_rumpclock
+specifies the clock type.
+In case of
+.Dv RUMPUSER_CLOCK_RELWALL
+the wall time should be returned.
+In case of
+.Dv RUMPUSER_CLOCK_ABSMONO
+the time of a monotonic clock should be returned.
+.It Fa sec
+return value for seconds
+.It Fa nsec
+return value for nanoseconds
+.El
+.Pp
+.Ft int
+.Fn rumpuser_clock_sleep "int enum_rumpclock" "int64_t sec" "long nsec"
+.Bl -tag -width "xenum_rumpclock"
+.It Fa enum_rumpclock
+In case of
+.Dv RUMPUSER_CLOCK_RELWALL ,
+the sleep should last at least as long as specified.
+In case of
+.Dv RUMPUSER_CLOCK_ABSMONO ,
+the sleep should last until the hypervisor monotonic clock hits
+the specified absolute time.
+.It Fa sec
+sleep duration, seconds.
+exact semantics depend on
+.Fa clk .
+.It Fa nsec
+sleep duration, nanoseconds.
+exact semantics depend on
+.Fa clk .
+.El
+.Ss Parameter retrieval
+.Ft int
+.Fn rumpuser_getparam "const char *name" "void *buf" "size_t buflen"
+.Pp
+Retrieve a configuration parameter from the hypervisor.
+It is up to the hypervisor to decide how the parameters can be set.
+.Bl -tag -width "xenum_rumpclock"
+.It Fa name
+name of the parameter.
+If the name starts with an underscore, it means a mandatory parameter.
+The mandatory parameters are
+.Dv RUMPUSER_PARAM_NCPU
+which specifies the amount of virtual CPUs bootstrapped by the
+rump kernel and
+.Dv RUMPUSER_PARAM_HOSTNAME
+which returns a preferably unique instance name for the rump kernel.
+.It Fa buf
+buffer to return the data in as a string
+.It Fa buflen
+length of buffer
+.El
+.Ss Termination
+.Ft void
+.Fn rumpuser_exit "int value"
+.Pp
+Terminate the rump kernel with exit value
+.Fa value .
+If
+.Fa value
+is
+.Dv RUMPUSER_PANIC
+the hypervisor should attempt to provide something akin to a core dump.
+.Ss Console output
+Console output is divided into two routines: a per-character
+one and printf-like one.
+The former is used e.g. by the rump kernel's internal printf
+routine.
+The latter can be used for direct debug prints e.g. very early
+on in the rump kernel's bootstrap or when using the in-kernel
+routine causes too much skew in the debug print results
+(the hypercall runs outside of the rump kernel and therefore does not
+cause any locking or scheduling events inside the rump kernel).
+.Pp
+.Ft void
+.Fn rumpuser_putchar "int ch"
+.Pp
+Output
+.Fa ch
+on the console.
+.Pp
+.Ft void
+.Fn rumpuser_dprintf "const char *fmt" "..."
+.Pp
+Do output based on printf-like parameters.
+.Ss Signals
+.Pp
+A rump kernel should be able to send signals to client programs
+due to some standard interfaces including signal delivery in their
+specifications.
+Examples of these interfaces include
+.Xr setitimer 2
+and
+.Xr write 2 .
+The
+.Fn rumpuser_kill
+function advises the hypercall implementation to raise a signal for the
+process containing the rump kernel.
+.Pp
+.Ft int
+.Fn rumpuser_kill "int64_t pid" "int sig"
+.Pp
+.Bl -tag -width "xenum_rumpclock"
+.It Fa pid
+The pid of the rump kernel process that the signal is directed to.
+This value may be used as the hypervisor as a hint on how to deliver
+the signal.
+The value
+.Dv RUMPUSER_PID_SELF
+may also be specified to indicate no hint.
+This value will be removed in a future version of the hypercall interface.
+.It Fa sig
+Number of signal to raise.
+The value is in NetBSD signal number namespace.
+In case the host has a native representation for signals, the
+value should be translated before the signal is raised.
+In case there is no mapping between
+.Fa sig
+and native signals (if any), the behavior is implementation-defined.
+.El
+.Pp
+A rump kernel will ignore the return value of this hypercall.
+The only implication of not implementing
+.Fn rumpuser_kill
+is that some application programs may not experience expected behavior
+for standard interfaces.
+.Pp
+As an aside,the
+.Xr rump_sp 7
+protocol provides equivalent functionality for remote clients.
+.Ss Random pool
+.Ft int
+.Fn rumpuser_getrandom "void *buf" "size_t buflen" "int flags" "size_t *retp"
+.Pp
+.Bl -tag -width "xenum_rumpclock"
+.It Fa buf
+buffer that the randomness is written to
+.It Fa buflen
+number of bytes of randomness requested
+.It Fa flags
+The value 0 or a combination of
+.Dv RUMPUSER_RANDOM_HARD
+(return true randomness instead of something from a PRNG)
+and
+.Dv RUMPUSER_RANDOM_NOWAIT
+(do not block in case the requested amount of bytes is not available).
+.It Fa retp
+The number of random bytes written into
+.Fa buf .
+.El
+.Ss Threads
+.Ft int
+.Fo rumpuser_thread_create
+.Fa "void *(*fun)(void *)" "void *arg" "const char *thrname" "int mustjoin"
+.Fa "int priority" "int cpuidx" "void **cookie"
+.Fc
+.Pp
+Create a schedulable host thread context.
+The rump kernel will call this interface when it creates a kernel thread.
+The scheduling policy for the new thread is defined by the hypervisor.
+In case the hypervisor wants to optimize the scheduling of the
+threads, it can perform heuristics on the
+.Fa thrname ,
+.Fa priority
+and
+.Fa cpuidx
+parameters.
+.Bl -tag -width "xenum_rumpclock"
+.It Fa fun
+function that the new thread must call.
+This call will never return.
+.It Fa arg
+argument to be passed to
+.Fa fun
+.It Fa thrname
+Name of the new thread.
+.It Fa mustjoin
+If 1, the thread will be waited for by
+.Fn rumpuser_thread_join
+when the thread exits.
+.It Fa priority
+The priority that the kernel requested the thread to be created at.
+Higher values mean higher priority.
+The exact kernel semantics for each value are not available through
+this interface.
+.It Fa cpuidx
+The index of the virtual CPU that the thread is bound to, or \-1
+if the thread is not bound.
+The mapping between the virtual CPUs and physical CPUs, if any,
+is hypervisor implementation specific.
+.It Fa cookie
+In case
+.Fa mustjoin
+is set, the value returned in
+.Fa cookie
+will be passed to
+.Fn rumpuser_thread_join .
+.El
+.Pp
+.Ft void
+.Fn rumpuser_thread_exit "void"
+.Pp
+Called when a thread created with
+.Fn rumpuser_thread_create
+exits.
+.Pp
+.Ft int
+.Fn rumpuser_thread_join "void *cookie"
+.Pp
+Wait for a joinable thread to exit.
+The cookie matches the value from
+.Fn rumpuser_thread_create .
+.Pp
+.Ft void
+.Fn rumpuser_curlwpop "int enum_rumplwpop" "struct lwp *l"
+.Pp
+Manipulate the hypervisor's thread context database.
+The possible operations are create, destroy, and set as specified by
+.Fa enum_rumplwpop :
+.Bl -tag -width "XRUMPUSER_LWP_DESTROY"
+.It Dv RUMPUSER_LWP_CREATE
+Inform the hypervisor that
+.Fa l
+is now a valid thread context which may be set.
+A currently valid value of
+.Fa l
+may not be specified.
+This operation is informational and does not mandate any action
+from the hypervisor.
+.It Dv RUMPUSER_LWP_DESTROY
+Inform the hypervisor that
+.Fa l
+is no longer a valid thread context.
+This means that it may no longer be set as the current context.
+A currently set context or an invalid one may not be destroyed.
+This operation is informational and does not mandate any action
+from the hypervisor.
+.It Dv RUMPUSER_LWP_SET
+Set
+.Fa l
+as the current host thread's rump kernel context.
+A previous context must not exist.
+.It Dv RUMPUSER_LWP_CLEAR
+Clear the context previous set by
+.Dv RUMPUSER_LWP_SET .
+The value passed in
+.Fa l
+is the current thread and is never
+.Dv NULL .
+.El
+.Pp
+.Ft struct lwp *
+.Fn rumpuser_curlwp "void"
+.Pp
+Retrieve the rump kernel thread context associated with the current host
+thread, as set by
+.Fn rumpuser_curlwpop .
+This routine may be called when a context is not set and
+the routine must return
+.Dv NULL
+in that case.
+This interface is expected to be called very often.
+Any optimizations pertaining to the execution speed of this routine
+should be done in
+.Fn rumpuser_curlwpop .
+.Pp
+.Ft void
+.Fn rumpuser_seterrno "int errno"
+.Pp
+Set an errno value in the calling thread's TLS.
+Note: this is used only if rump kernel clients make rump system calls.
+.Ss Mutexes, rwlocks and condition variables
+The locking interfaces have standard semantics, so we will not
+discuss each one in detail.
+The data types
+.Vt struct rumpuser_mtx ,
+.Vt struct rumpuser_rw
+and
+.Vt struct rumpuser_cv
+used by these interfaces are opaque to the rump kernel, i.e. the
+hypervisor has complete freedom over them.
+.Pp
+Most of these interfaces will (and must) relinquish the rump kernel
+CPU context in case they block (or intend to block).
+The exceptions are the "nowrap" variants of the interfaces which
+may not relinquish rump kernel context.
+.Pp
+.Ft void
+.Fn rumpuser_mutex_init "struct rumpuser_mtx **mtxp" "int flags"
+.Pp
+.Ft void
+.Fn rumpuser_mutex_enter "struct rumpuser_mtx *mtx"
+.Pp
+.Ft void
+.Fn rumpuser_mutex_enter_nowrap "struct rumpuser_mtx *mtx"
+.Pp
+.Ft int
+.Fn rumpuser_mutex_tryenter "struct rumpuser_mtx *mtx"
+.Pp
+.Ft void
+.Fn rumpuser_mutex_exit "struct rumpuser_mtx *mtx"
+.Pp
+.Ft void
+.Fn rumpuser_mutex_destroy "struct rumpuser_mtx *mtx"
+.Pp
+.Ft void
+.Fn rumpuser_mutex_owner "struct rumpuser_mtx *mtx" "struct lwp **lp"
+.Pp
+Mutexes provide mutually exclusive locking.
+The flags, of which at least one must be given, are as follows:
+.Bl -tag -width "XRUMPUSER_MTX_KMUTEX"
+.It Dv RUMPUSER_MTX_SPIN
+Create a spin mutex.
+Locking this type of mutex must not relinquish rump kernel context
+even when
+.Fn rumpuser_mutex_enter
+is used.
+.It Dv RUMPUSER_MTX_KMUTEX
+The mutex must track and be able to return the rump kernel thread
+that owns the mutex (if any).
+If this flag is not specified,
+.Fn rumpuser_mutex_owner
+will never be called for that particular mutex.
+.El
+.Pp
+.Ft void
+.Fn rumpuser_rw_init "struct rumpuser_rw **rwp"
+.Pp
+.Ft void
+.Fn rumpuser_rw_enter "int enum_rumprwlock" "struct rumpuser_rw *rw"
+.Pp
+.Ft int
+.Fn rumpuser_rw_tryenter "int enum_rumprwlock" "struct rumpuser_rw *rw"
+.Pp
+.Ft int
+.Fn rumpuser_rw_tryupgrade "struct rumpuser_rw *rw"
+.Pp
+.Ft void
+.Fn rumpuser_rw_downgrade "struct rumpuser_rw *rw"
+.Pp
+.Ft void
+.Fn rumpuser_rw_exit "struct rumpuser_rw *rw"
+.Pp
+.Ft void
+.Fn rumpuser_rw_destroy "struct rumpuser_rw *rw"
+.Pp
+.Ft void
+.Fo rumpuser_rw_held
+.Fa "int enum_rumprwlock" "struct rumpuser_rw *rw" "int *heldp"
+.Fc
+.Pp
+Read/write locks provide either shared or exclusive locking.
+The possible values for
+.Fa lk
+are
+.Dv RUMPUSER_RW_READER
+and
+.Dv RUMPUSER_RW_WRITER .
+Upgrading means trying to migrate from an already owned shared
+lock to an exclusive lock and downgrading means migrating from
+an already owned exclusive lock to a shared lock.
+.Pp
+.Ft void
+.Fn rumpuser_cv_init "struct rumpuser_cv **cvp"
+.Pp
+.Ft void
+.Fn rumpuser_cv_destroy "struct rumpuser_cv *cv"
+.Pp
+.Ft void
+.Fn rumpuser_cv_wait "struct rumpuser_cv *cv" "struct rumpuser_mtx *mtx"
+.Pp
+.Ft void
+.Fn rumpuser_cv_wait_nowrap "struct rumpuser_cv *cv" "struct rumpuser_mtx *mtx"
+.Pp
+.Ft int
+.Fo rumpuser_cv_timedwait
+.Fa "struct rumpuser_cv *cv" "struct rumpuser_mtx *mtx"
+.Fa "int64_t sec" "int64_t nsec"
+.Fc
+.Pp
+.Ft void
+.Fn rumpuser_cv_signal "struct rumpuser_cv *cv"
+.Pp
+.Ft void
+.Fn rumpuser_cv_broadcast "struct rumpuser_cv *cv"
+.Pp
+.Ft void
+.Fn rumpuser_cv_has_waiters "struct rumpuser_cv *cv" "int *waitersp"
+.Pp
+Condition variables wait for an event.
+The
+.Fa mtx
+interlock eliminates a race between checking the predicate and
+sleeping on the condition variable; the mutex should be released
+for the duration of the sleep in the normal atomic manner.
+The timedwait variant takes a specifier indicating a relative
+sleep duration after which the routine will return with
+.Er ETIMEDOUT .
+If a timedwait is signaled before the timeout expires, the
+routine will return 0.
+.Pp
+The order in which the hypervisor
+reacquires the rump kernel context and interlock mutex before
+returning into the rump kernel is as follows.
+In case the interlock mutex was initialized with both
+.Dv RUMPUSER_MTX_SPIN
+and
+.Dv RUMPUSER_MTX_KMUTEX ,
+the rump kernel context is scheduled before the mutex is reacquired.
+In case of a purely
+.Dv RUMPUSER_MTX_SPIN
+mutex, the mutex is acquired first.
+In the final case the order is implementation-defined.
+.Sh RETURN VALUES
+All routines which return an integer return an errno value.
+The hypervisor must translate the value to the the native errno
+namespace used by the rump kernel.
+Routines which do not return an integer may never fail.
+.Sh SEE ALSO
+.Xr rump 3
+.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 Kernels
+.%O Section 2.3.2: The Hypercall Interface
+.Re
+.Pp
+For a list of all known implementations of the
+.Nm
+interface, see
+.Lk http://wiki.rumpkernel.org/Platforms .
+.Sh HISTORY
+The rump kernel hypercall API was first introduced in
+.Nx 5.0 .
+The API described above first appeared in
+.Nx 7.0 .
Index: src/sys/rump/share/man/man7/Makefile
diff -u /dev/null src/sys/rump/share/man/man7/Makefile:1.1
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/share/man/man7/Makefile Sun Nov 9 17:39:38 2014
@@ -0,0 +1,5 @@
+# $NetBSD: Makefile,v 1.1 2014/11/09 17:39:38 pooka Exp $
+
+MAN= rump_sp.7
+
+.include <bsd.man.mk>
Index: src/sys/rump/share/man/man7/rump_sp.7
diff -u /dev/null src/sys/rump/share/man/man7/rump_sp.7:1.1
--- /dev/null Sun Nov 9 17:39:38 2014
+++ src/sys/rump/share/man/man7/rump_sp.7 Sun Nov 9 17:39:38 2014
@@ -0,0 +1,117 @@
+.\" $NetBSD: rump_sp.7,v 1.1 2014/11/09 17:39:38 pooka Exp $
+.\"
+.\" Copyright (c) 2010 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 February 7, 2011
+.Dt RUMP_SP 7
+.Os
+.Sh NAME
+.Nm rump_sp
+.Nd rump remote system call support
+.Sh DESCRIPTION
+The
+.Nm
+facility allows clients to attach to a rump kernel server over a
+socket and perform system calls.
+While making a local rump system call is faster than calling the
+host kernel, a remote system call over a socket is slower.
+This facility is therefore meant mostly for operations which are
+not performance critical, such as configuration of a rump kernel
+server.
+.Ss Clients
+The
+.Nx
+base system comes with multiple preinstalled clients which can be
+used to configure a rump kernel and request diagnostic information.
+These clients run as hybrids partially in the host system and
+partially against the rump kernel.
+For example, network-related clients will typically avoid making
+any file system related system calls against the rump kernel, since
+it is not guaranteed that a rump network server has file system
+support.
+Another example is DNS: since a rump server very rarely has a DNS
+service configured, host networking is used to do DNS lookups.
+.Pp
+Some examples of clients include
+.Nm rump.ifconfig
+which configures interfaces,
+.Nm rump.sysctl
+which is used to access the
+.Xr sysctl 7
+namespace
+and
+.Nm rump.traceroute
+which is used to display a network trace starting from the rump kernel.
+.Pp
+Also, almost any unmodified dynamically linked application
+(for example
+.Xr telnet 1
+or
+.Xr ls 1 )
+can be used as a rump kernel client with the help of system call hijacking.
+See
+.Xr rumphijack 3
+for more information.
+.Ss Connecting to the server
+A remote rump server is specified using an URL.
+Currently two types of URLs are supported: TCP and local domain sockets.
+The TCP URL is of the format tcp://ip.address:port/ and the local
+domain URL is unix://path.
+The latter can accept relative or absolute paths.
+Note that absolute paths require three leading slashes.
+.Pp
+To preserve the standard usage of the rump clients' counterparts
+the environment variable
+.Ev RUMP_SERVER
+is used to specify the server URL.
+To keep track of which rump kernel the current shell is using,
+modifying the shell prompt is recommended -- this is analoguous
+to the visual clue you have when you login from one machine to
+another.
+.Ss Client credentials and access control
+The current scheme gives all connecting clients root credentials.
+It is recommended to take precautions which prevent unauthorized
+access.
+For a unix domain socket it is enough to prevent access to the
+socket using file system permissions.
+For TCP/IP sockets the only available means is to prevent network
+access to the socket with the use of firewalls.
+More fine-grained access control based on cryptographic credentials
+may be implemented at a future date.
+.Sh EXAMPLES
+Get a list of file systems supported by a rump kernel server
+(in case that particular server does not support file systems,
+an error will be returned):
+.Bd -literal -offset indent
+$ env RUMP_SERVER=unix://sock rump.sysctl vfs.generic.fstypes
+.Ed
+.Sh SEE ALSO
+.Xr rump_server 1 ,
+.Xr rump 3 ,
+.Xr rumpclient 3 ,
+.Xr rumphijack 3
+.Sh HISTORY
+.Nm
+first appeared in
+.Nx 6.0 .
