1.\" $NetBSD: shmif.4,v 1.5 2018/12/12 02:26:40 rin Exp $ 2.\" 3.\" Copyright (c) 2010 Antti Kantee 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd December 12, 2018 27.Dt SHMIF 4 28.Os 29.Sh NAME 30.Nm shmif 31.Nd rump kernel shared memory network interface 32.Sh SYNOPSIS 33.In rump/rump.h 34.Ft int 35.Fo rump_pub_shmif_create 36.Fa "const char *path" "int *ifnum" 37.Fc 38.Sh DESCRIPTION 39The 40.Nm 41interface uses a memory mapped regular file as a virtual Ethernet bus. 42All interfaces connected to the same bus see each others' traffic. 43.Pp 44Using a memory mapped regular file as a bus has two implications: 45.Bl -enum 46.It 47The bus identifier is not in flat global namespace. 48.It 49Configuring and using the interface is possible without superuser 50privileges on the host (normal host file access permissions for 51the bus hold). 52.El 53.Pp 54It is not possible to directly access the host networking 55facilities from a rump kernel using purely 56.Nm . 57However, traffic can be routed to another rump kernel instance which 58provides both 59.Nm 60and 61.Xr virt 4 62networking. 63.Pp 64An 65.Nm 66interface can be created in two ways: 67.Bl -bullet 68.It 69Programmatically by calling 70.Fn rump_pub_shmif_create . 71The bus pathname is passed in 72.Fa path . 73The number of the newly created interface is available after a successful 74call by dereferencing 75.Fa ifnum . 76.It 77Dynamically at runtime with 78.Xr ifconfig 8 79or equivalent using the 80.Em create 81command. 82In this case the bus path must be configured with 83.Xr ifconfig 8 84.Em linkstr 85before the interface address can be configured. 86.El 87.Pp 88Destroying an 89.Nm 90interface is possible only via 91.Xr ifconfig 8 92.Em destroy . 93.Pp 94An 95.Nm 96interface emulates TX/RX offload options in software. 97They are specified by 98.Xr ifconfig 8 . 99Alternatively, its 100.Em if_capenable 101flag is directly specified by 102environment variable 103.Ev RUMP_SHMIF_CAPENABLE , 104for example: 105.Bl -tag -width 0xfffff 106.It Ar 0x7ff80 107for all TX/RX offload 108.It Ar 0x6aa80 109for all TX offload 110.It Ar 0x15500 111for all RX offload 112.El 113.Pp 114See 115.Pa /usr/include/net/if.h 116for more details. 117.Sh SEE ALSO 118.Xr rump 3 , 119.Xr virt 4 , 120.Xr ifconfig 8 121