Update netmap page, fixing the API documentation and usage example.
Add a new manpage for the vale switch
This commit is contained in:
parent
42a3a5bd91
commit
13a5d88f1a
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=238983
@ -509,6 +509,7 @@ MAN= aac.4 \
|
||||
utopia.4 \
|
||||
uvisor.4 \
|
||||
uvscom.4 \
|
||||
vale.4 \
|
||||
vga.4 \
|
||||
vge.4 \
|
||||
viapm.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).
|
||||
|
134
share/man/man4/vale.4
Normal file
134
share/man/man4/vale.4
Normal 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).
|
Loading…
Reference in New Issue
Block a user