.\"	$NetBSD: shmif.4,v 1.5 2018/12/12 02:26:40 rin 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 December 12, 2018
.Dt SHMIF 4
.Os
.Sh NAME
.Nm shmif
.Nd rump kernel 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:
.Bl -enum
.It
The bus identifier is not in flat global namespace.
.It
Configuring and using the interface is possible without superuser
privileges on the host (normal host file access permissions for
the bus hold).
.El
.Pp
It is not possible to directly access the host networking
facilities from a rump 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 successful
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
.Pp
Destroying an
.Nm
interface is possible only via
.Xr ifconfig 8
.Em destroy .
.Pp
An
.Nm
interface emulates TX/RX offload options in software.
They are specified by
.Xr ifconfig 8 .
Alternatively, its
.Em if_capenable
flag is directly specified by
environment variable
.Ev RUMP_SHMIF_CAPENABLE ,
for example:
.Bl -tag -width 0xfffff
.It Ar 0x7ff80
for all TX/RX offload
.It Ar 0x6aa80
for all TX offload
.It Ar 0x15500
for all RX offload
.El
.Pp
See
.Pa /usr/include/net/if.h
for more details.
.Sh SEE ALSO
.Xr rump 3 ,
.Xr virt 4 ,
.Xr ifconfig 8