share/man/man4/ptnet.4

   1 .\" Copyright (c) 2018 Vincenzo Maffione
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  12 .\"
  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
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd December 11, 2018
  28 .Dt PTNET 4
  29 .Os
  30 .Sh NAME
  31 .Nm ptnet
  32 .Nd Ethernet driver for passed-through netmap ports
  33 .Sh SYNOPSIS
  34 This network driver is included in
  35 .Xr netmap 4 ,
  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
  39 .Cd "device netmap"
  40 .Ed
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  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
  50 .Nm
  51 is currently available for QEMU/KVM.
  52 Any
  53 .Xr netmap 4
  54 port can be passed-through, including physical NICs,
  55 .Xr vale 4
  56 ports, netmap pipes, etc.
  57 .Pp
  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
  65 performance of
  66 .Nm
  67 when compared to hypervisor device emulation or paravirtualization (e.g.,
  68 .Xr vtnet 4 ,
  69 .Xr vmx 4 )
  70 comes from the hypervisor being completely bypassed in the data-path.
  71 For example, when using
  72 .Xr vtnet 4
  73 the VM has to convert each
  74 .Xr mbuf 9
  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
  80 incured by
  81 .Nm
  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.
  87 .Pp
  88 It is also possible to use a
  89 .Nm
  90 device like a regular network interface, which interacts with the
  91 .Fx
  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
  96 .Xr vtnet 4
  97 or other paravirtualized network devices.
  98 If the passed-through netmap port supports the VirtIO network header,
  99 .Nm
 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
 102 (LRO).
 103 Currently,
 104 .Xr vale 4
 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.
 108 .Sh TUNABLES
 109 Tunables can be set at the
 110 .Xr loader 8
 111 prompt before booting the kernel or stored in
 112 .Xr loader.conf 5 .
 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.
 116 If enabled,
 117 .Nm
 118 uses the same header used by
 119 .Xr vtnet 4
 120 to exchange offload metadata with the hypervisor.
 121 If disabled, no header is prepended to transmitted and received
 122 packets.
 123 The metadata is necessary to support TCP/UDP checksum offloads,
 124 TSO, and LRO.
 125 The default value is 1.
 126 .El
 127 .Sh SEE ALSO
 128 .Xr netintro 4 ,
 129 .Xr netmap 4 ,
 130 .Xr vale 4 ,
 131 .Xr virtio 4 ,
 132 .Xr vmx 4 ,
 133 .Xr ifconfig 8
 134 .Sh HISTORY
 135 The
 136 .Nm
 137 driver was written by
 138 .An Vincenzo Maffione Aq Mt vmaffione@FreeBSD.org .
 139 It first appeared in
 140 .Fx 12.0 .