[src/trunk]: src document shmif, or at least what's implemented so far

[pooka <pooka%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a5b542481875
branches:  trunk
changeset: 758805:a5b542481875
user:      pooka <pooka%NetBSD.org@localhost>
date:      Mon Nov 15 23:10:51 2010 +0000

description:
document shmif, or at least what's implemented so far

diffstat:

 distrib/sets/lists/man/mi |   5 ++-
 share/man/man4/Makefile   |   4 +-
 share/man/man4/shmif.4    |  85 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 91 insertions(+), 3 deletions(-)

diffs (140 lines):

diff -r c812f3ecc948 -r a5b542481875 distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Mon Nov 15 23:07:37 2010 +0000
+++ b/distrib/sets/lists/man/mi Mon Nov 15 23:10:51 2010 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1251 2010/11/15 23:07:37 skrll Exp $
+# $NetBSD: mi,v 1.1252 2010/11/15 23:10:52 pooka Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -1446,6 +1446,7 @@
 ./usr/share/man/cat4/sgimips/wdsc.0            man-sys-catman          .cat
 ./usr/share/man/cat4/sgsmix.0                  man-sys-catman          .cat
 ./usr/share/man/cat4/shb.0                     man-sys-catman          .cat
+./usr/share/man/cat4/shmif.0                   man-sys-catman          .cat
 ./usr/share/man/cat4/shpcic.0                  man-sys-catman          .cat
 ./usr/share/man/cat4/si.0                      man-sys-catman          .cat
 ./usr/share/man/cat4/siisata.0                 man-sys-catman          .cat
@@ -4079,6 +4080,7 @@
 ./usr/share/man/html4/sgimips/wdsc.html                man-sys-htmlman         html
 ./usr/share/man/html4/sgsmix.html              man-sys-htmlman         html
 ./usr/share/man/html4/shb.html                 man-sys-htmlman         html
+./usr/share/man/html4/shmif.html               man-sys-htmlman         html
 ./usr/share/man/html4/shpcic.html              man-sys-htmlman         html
 ./usr/share/man/html4/si.html                  man-sys-htmlman         html
 ./usr/share/man/html4/siisata.html             man-sys-htmlman         html
@@ -6624,6 +6626,7 @@
 ./usr/share/man/man4/sgimips/wdsc.4            man-sys-man             .man
 ./usr/share/man/man4/sgsmix.4                  man-sys-man             .man
 ./usr/share/man/man4/shb.4                     man-sys-man             .man
+./usr/share/man/man4/shmif.4                   man-sys-man             .man
 ./usr/share/man/man4/shpcic.4                  man-sys-man             .man
 ./usr/share/man/man4/si.4                      man-sys-man             .man
 ./usr/share/man/man4/siisata.4                 man-sys-man             .man
diff -r c812f3ecc948 -r a5b542481875 share/man/man4/Makefile
--- a/share/man/man4/Makefile   Mon Nov 15 23:07:37 2010 +0000
+++ b/share/man/man4/Makefile   Mon Nov 15 23:10:51 2010 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.535 2010/11/15 23:07:38 skrll Exp $
+#      $NetBSD: Makefile,v 1.536 2010/11/15 23:10:51 pooka Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/18/93
 
 MAN=   aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
@@ -50,7 +50,7 @@
        raid.4 ral.4 ray.4 rcons.4 re.4 rgephy.4 rlphy.4 rnd.4 route.4 \
        rs5c372rtc.4 rtk.4 rtw.4 rum.4 \
        satalink.4 sbus.4 scc.4 schide.4 scsi.4 sd.4 se.4 seeprom.4 sem.4 \
-       ses.4 sf.4 sfb.4 sgsmix.4 shb.4 \
+       ses.4 sf.4 sfb.4 sgsmix.4 shb.4 shmif.4 \
        shpcic.4 siisata.4 siop.4 sip.4 siside.4 sk.4 sl.4 slide.4 \
        sm.4 smsh.4 sn.4 sony.4 spc.4 speaker.4 spif.4 sqphy.4 ss.4 \
        st.4 ste.4 stge.4 sti.4 stpcide.4 sv.4 strip.4 \
diff -r c812f3ecc948 -r a5b542481875 share/man/man4/shmif.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/shmif.4    Mon Nov 15 23:10:51 2010 +0000
@@ -0,0 +1,85 @@
+.\"    $NetBSD: shmif.4,v 1.1 2010/11/15 23:10:51 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 ``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 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 November 15, 2010
+.Dt SHMIF 4
+.Os
+.Sh NAME
+.Nm shmif
+.Nd rump shared memory network interface
+.Sh SYNOPSIS
+.In rump/rump.h
+.Ft int
+.Fo rump_pub_shmif_create
+.Fa "const char *path" "int *ifnum"
+.Fc
+.Sh DESCRIPTION
+The
+.Nm
+interface uses a memory mapped regular file as a virtual Ethernet bus.
+All interfaces connected to the same bus see each others' traffic.
+.Pp
+Using a memory mapped regular file as a bus has two implications:
+1) the bus identifier is not in flat global namespace 2) configuring
+and using the interface is possible without superuser privileges
+on the host (normal host file access permissions for the bus hold).
+.Pp
+It is not possible to directly access the host networking
+facilities from a rump virtual kernel using purely
+.Nm .
+However, traffic can be routed to another rump kernel instance which
+provides both
+.Nm
+and
+.Xr virt 4
+networking.
+.Pp
+An
+.Nm
+interface can be created in two ways:
+.Bl -bullet
+.It
+Programmatically by calling
+.Fn rump_pub_shmif_create .
+The bus pathname is passed in
+.Fa path .
+The number of the newly created interface is available after a succesful
+call by dereferencing
+.Fa ifnum .
+.It
+Dynamically at runtime with
+.Xr ifconfig 8
+or equivalent using the
+.Em create
+command.
+In this case the bus path must be configured with
+.Xr ifconfig 8
+.Em linkstr
+before the interface address can be configured.
+.El
+.Sh SEE ALSO
+.Xr rump 3 ,
+.Xr virt 4 ,
+.Xr ifconfig 8 .