d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
Add a new manpage for the vale switch
This commit is contained in:
Luigi Rizzo 2012-08-02 08:46:08 +00:00
parent 42a3a5bd91
commit 13a5d88f1a
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=238983
3 changed files with 173 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
share/man/man4/Makefile
View File

@ -509,6 +509,7 @@ MAN= aac.4 \
utopia.4 \
uvisor.4 \
uvscom.4 \
vale.4 \
vga.4 \
vge.4 \
viapm.4 \

53
share/man/man4/netmap.4
View File

@ -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).

134
share/man/man4/vale.4 Normal file
View File

@ -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).