Date: Thu, 2 Aug 2012 08:46:08 +0000 (UTC) From: Luigi Rizzo <luigi@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r238983 - head/share/man/man4 Message-ID: <201208020846.q728k8AL057056@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: luigi Date: Thu Aug 2 08:46:08 2012 New Revision: 238983 URL: http://svn.freebsd.org/changeset/base/238983 Log: Update netmap page, fixing the API documentation and usage example. Add a new manpage for the vale switch Added: head/share/man/man4/vale.4 (contents, props changed) Modified: head/share/man/man4/Makefile head/share/man/man4/netmap.4 Modified: head/share/man/man4/Makefile ============================================================================== --- head/share/man/man4/Makefile Thu Aug 2 07:35:40 2012 (r238982) +++ head/share/man/man4/Makefile Thu Aug 2 08:46:08 2012 (r238983) @@ -509,6 +509,7 @@ MAN= aac.4 \ utopia.4 \ uvisor.4 \ uvscom.4 \ + vale.4 \ vga.4 \ vge.4 \ viapm.4 \ Modified: head/share/man/man4/netmap.4 ============================================================================== --- head/share/man/man4/netmap.4 Thu Aug 2 07:35:40 2012 (r238982) +++ head/share/man/man4/netmap.4 Thu Aug 2 08:46:08 2012 (r238983) @@ -21,12 +21,12 @@ .\" 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. -.\" +.\" .\" This document is derived in part from the enet man page (enet.4) .\" distributed with 4.3BSD Unix. .\" .\" $FreeBSD$ -.\" $Id: netmap.4 9662 2011-11-16 13:18:06Z luigi $: stable/8/share/man/man4/bpf.4 181694 2008-08-13 17:45:06Z ed $ +.\" $Id: netmap.4 11563 2012-08-02 08:59:12Z luigi $: stable/8/share/man/man4/bpf.4 181694 2008-08-13 17:45:06Z ed $ .\" .Dd February 27, 2012 .Dt NETMAP 4 @@ -43,14 +43,15 @@ is a framework for fast and safe access .Nm uses memory mapped buffers and metadata (buffer indexes and lengths) to communicate with the kernel, -which is in charge of validating information through +which is in charge of validating information through .Pa ioctl() and -.Pa select()/poll() . +.Pa select()/poll(). .Nm can exploit the parallelism in multiqueue devices and multicore systems. .Pp +.Pp .Nm requires explicit support in device drivers. For a list of supported devices, see the end of this manual page. @@ -65,7 +66,7 @@ to bind the file descriptor to a network When a device is put in .Nm mode, its data path is disconnected from the host stack. -The processes owning the file descriptor +The processes owning the file descriptor can exchange packets with the device, or with the host stack, through an mmapped memory region that contains pre-allocated buffers and metadata. @@ -88,6 +89,7 @@ are relative (offsets or indexes). Some them into actual pointers. .Pp The data structures in shared memory are the following: +.Pp .Bl -tag -width XXX .It Dv struct netmap_if (one per interface) indicates the number of rings supported by an interface, their @@ -159,7 +161,8 @@ struct netmap_ring *rxring = NETMAP_RXRI int i = txring->slot[txring->cur].buf_idx; char *buf = NETMAP_BUF(txring, i); .Ed -.Ss IOCTLS +.Sh IOCTLS +.Pp .Nm supports some ioctl() to synchronize the state of the rings between the kernel and the user processes, plus some @@ -172,7 +175,7 @@ defined as follows: struct nmreq { char nr_name[IFNAMSIZ]; uint32_t nr_version; /* API version */ -#define NETMAP_API 2 /* current version */ +#define NETMAP_API 3 /* current version */ uint32_t nr_offset; /* nifp offset in the shared region */ uint32_t nr_memsize; /* size of the shared region */ uint32_t nr_tx_slots; /* slots in tx rings */ @@ -184,6 +187,8 @@ struct nmreq { #define NETMAP_SW_RING 0x2000 /* we process the sw ring */ #define NETMAP_NO_TX_POLL 0x1000 /* no gratuitous txsync on poll */ #define NETMAP_RING_MASK 0xfff /* the actual ring number */ + uint16_t spare1; + uint32_t spare2[4]; }; .Ed @@ -250,7 +255,7 @@ number of slots available for transmissi tells the hardware of consumed packets, and asks for newly available packets. .El -.Ss SYSTEM CALLS +.Sh SYSTEM CALLS .Nm uses .Nm select @@ -279,7 +284,7 @@ fds.fd = fd; fds.events = POLLOUT; for (;;) { poll(list, 1, -1); - while (ring->avail-- > 0) { + for ( ; ring->avail > 0 ; ring->avail--) { i = ring->cur; buf = NETMAP_BUF(ring, ring->slot[i].buf_index); ... prepare packet in buf ... @@ -292,13 +297,31 @@ for (;;) { .Nm supports the following interfaces: .Xr em 4 , +.Xr igb 4 , .Xr ixgbe 4 , -.Xr re 4 , +.Xr lem 4 , +.Xr re 4 +.Sh SEE ALSO +.Xr vale 4 +.Pp +http://info.iet.unipi.it/~luigi/netmap/ +.Pp +Luigi Rizzo, Revisiting network I/O APIs: the netmap framework, +Communications of the ACM, 55 (3), pp.45-51, March 2012 +.Pp +Luigi Rizzo, netmap: a novel framework for fast packet I/O, +Usenix ATC'12, June 2012, Boston .Sh AUTHORS +.An -nosplit The .Nm -framework has been designed and implemented by -.An Luigi Rizzo -and -.An Matteo Landi -in 2011 at the Universita` di Pisa. +framework has been designed and implemented at the +Universita` di Pisa in 2011 by +.An Luigi Rizzo , +with help from +.An Matteo Landi , +.An Gaetano Catalli , +.An Giuseppe Lettieri . +.Pp +.Nm +has been funded by the European Commission within FP7 Project CHANGE (257422). Added: head/share/man/man4/vale.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/vale.4 Thu Aug 2 08:46:08 2012 (r238983) @@ -0,0 +1,134 @@ +.\" Copyright (c) 2012 Luigi Rizzo, Universita` di Pisa +.\" 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. +.\" +.\" This document is derived in part from the enet man page (enet.4) +.\" distributed with 4.3BSD Unix. +.\" +.\" $FreeBSD$ +.\" $Id: $ +.\" +.Dd July 27, 2012 +.Dt VALE 4 +.Os +.Sh NAME +.Nm vale +.Nd a very fast Virtual Local Ethernet using the netmap API +.Sh SYNOPSIS +.Cd device netmap +.Sh DESCRIPTION +.Nm +is a feature of the +.Nm netmap +module that implements multiple Virtual switches that can +be used to interconnect netmap clients, including traffic +sources and sinks, packet forwarders, userspace firewalls, +and so on. +.Pp +.Nm +is implemented completely in software, and is extremely fast. +On a modern machine it can move almost 20 Million packets per +second (Mpps) per core with small frames, and about 70 Gbit/s +with 1500 byte frames. +.Pp +.Sh OPERATION +.Nm +dynamically creates switches and ports as client connect +to it using the +.Xr netmap 4 +API. +.Pp +.Nm +ports are named +.Pa vale[bdg:][port] +where +.Pa vale +is the prefix indicating a VALE switch rather than a standard interface, +.Pa bdg +indicates a specific switch (the colon is a separator), +and +.Pa port +indicates a port within the switch. +Bridge and ports names are arbitrary strings, the only +constraint being that the full name must fit within 16 +characters. +.Pp +See +.Xr netmap 4 +for details on the API. +.Ss LIMITS +.Nm +currently supports up to 4 switches, 16 ports per switch, +1024 buffers per port. These hard limits will be +changed to sysctl variables in future releases. +.Pp +.Sh SYSCTL VARIABLES +.Nm +uses the following sysctl variables to control operation: +.Bl -tag -width 12 +.It dev.netmap.bridge +The maximum number of packets processed internally +in each iteration. +Defaults to 1024, use lower values to trade latency +with throughput. +.Pp +.It dev.netmap.verbose +Set to non-zero values to enable in-kernel diagnostics. +.El +.Pp +.Sh EXAMPLES +Create one switch, with a traffic generator connected to one +port, and a netmap-enabled tcpdump instance on another port: +.Bd -literal -offset indent +tcpdump -ni vale-a:1 & +pkt-gen -i vale-a:0 -f tx & +.Ed +.Pp +Create two switches, +each connected to two qemu machines on different ports. +.Bd -literal -offset indent +qemu -net nic -net netmap,ifname=vale-1:a ... & +qemu -net nic -net netmap,ifname=vale-1:b ... & +qemu -net nic -net netmap,ifname=vale-2:c ... & +qemu -net nic -net netmap,ifname=vale-2:d ... & +.Ed +.Sh SEE ALSO +.Xr netmap 4 +.Pp +.Xr http://info.iet.unipi.it/~luigi/vale/ +.Pp +Luigi Rizzo, Giuseppe Lettieri: VALE, a switched ethernet for virtual machines, +June 2012, http://info.iet.unipi.it/~luigi/vale/ +.Sh AUTHORS +.An -nosplit +The +.Nm +switch has been designed and implemented in 2012 by +.An Luigi Rizzo +and +.An Giuseppe Lettieri +at the Universita` di Pisa. +.Pp +.Nm +has been funded by the European Commission within FP7 Projects +CHANGE (257422) and OPENLAB (287581).
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201208020846.q728k8AL057056>