Update netmap page, fixing the API documentation and usage example.

Add a new manpage for the vale switch

3 files changed, 173 insertions, 15 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 972200d..04d22d6 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -509,6 +509,7 @@ MAN=	aac.4 \
 	utopia.4 \
 	uvisor.4 \
 	uvscom.4 \
+	vale.4 \
 	vga.4 \
 	vge.4 \
 	viapm.4 \
diff --git a/share/man/man4/netmap.4 b/share/man/man4/netmap.4
index 9ac9fd0..d2dd591 100644
--- a/share/man/man4/netmap.4
+++ b/share/man/man4/netmap.4
@@ -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 to network devices
 .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 device.
 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 macros help converting
 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_RXRING(nifp, i);
 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 transmission.
 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).
diff --git a/share/man/man4/vale.4 b/share/man/man4/vale.4
new file mode 100644
index 0000000..12e3247
--- /dev/null
+++ b/share/man/man4/vale.4
@@ -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).