1 .\" Copyright (c) 2018 Vincenzo Maffione
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd Ethernet driver for passed-through netmap ports
34 This network driver is included in
36 and it can be compiled into the kernel by adding the following
37 line in your kernel configuration file:
38 .Bd -ragged -offset indent
44 device driver provides direct access to host netmap ports,
45 from within a Virtual Machine (VM).
46 Applications running inside
47 the VM can access the TX/RX rings and buffers of a netmap port
48 that the hypervisor has passed-through to the VM.
49 Hypervisor support for
51 is currently available for QEMU/KVM.
54 port can be passed-through, including physical NICs,
56 ports, netmap pipes, etc.
58 The main use-case for netmap passthrough is Network Function
59 Virtualization (NFV), where middlebox applications running within
60 VMs may want to process very high packet rates (e.g., 1-10 millions
61 packets per second or more).
62 Note, however, that those applications
63 must use the device in netmap mode in order to achieve such rates.
64 In addition to the general advantages of netmap, the improved
67 when compared to hypervisor device emulation or paravirtualization (e.g.,
70 comes from the hypervisor being completely bypassed in the data-path.
71 For example, when using
73 the VM has to convert each
75 to a VirtIO-specific packet representation
76 and publish that to a VirtIO queue; on the hypervisor side, the
77 packet is extracted from the VirtIO queue and converted to a
78 hypervisor-specific packet representation.
79 The overhead of format conversions (and packet copies, in same cases) is not
82 in netmap mode, because mbufs are not used at all, and the packet format
83 is the one defined by netmap (e.g.,
84 .Ar struct netmap_slot )
85 along the whole data-path.
86 No format conversions or copies happen.
88 It is also possible to use a
90 device like a regular network interface, which interacts with the
92 network stack (i.e., not in netmap mode).
93 However, in that case it is necessary to pay the cost of data copies
94 between mbufs and netmap buffers, which generally results in lower
95 TCP/UDP performance than
97 or other paravirtualized network devices.
98 If the passed-through netmap port supports the VirtIO network header,
100 is able to use it, and support TCP/UDP checksum offload (for both transmit
101 and receive), TCP segmentation offload (TSO) and TCP large receive offload
105 ports support the header.
106 Note that the VirtIO network header is generally not used in NFV
107 use-cases, because middleboxes are not endpoints of TCP/UDP connections.
109 Tunables can be set at the
111 prompt before booting the kernel or stored in
113 .Bl -tag -width "xxxxxx"
114 .It Va dev.netmap.ptnet_vnet_hdr
115 This tunable enables (1) or disables (0) the VirtIO network header.
118 uses the same header used by
120 to exchange offload metadata with the hypervisor.
121 If disabled, no header is prepended to transmitted and received
123 The metadata is necessary to support TCP/UDP checksum offloads,
125 The default value is 1.
137 driver was written by
138 .An Vincenzo Maffione Aq Mt vmaffione@FreeBSD.org .