netmap: add man page for ptnet
Add a man page for ptnet(4), describing the guest driver for netmap passthrough. Reviewed by: bcr MFC after: 3 days Differential Revision: https://reviews.freebsd.org/D18518
This commit is contained in:
Vincenzo Maffione
parent
dde885de95
commit
76ed4255b5
140
share/man/man4/ptnet.4
Normal file
140
share/man/man4/ptnet.4
Normal file
@ -0,0 +1,140 @@
|
||||
.\" Copyright (c) 2018 Vincenzo Maffione
|
||||
.\" 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.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd December 11, 2018
|
||||
.Dt PTNET 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm ptnet
|
||||
.Nd Ethernet driver for passed-through netmap ports
|
||||
.Sh SYNOPSIS
|
||||
This network driver is included in
|
||||
.Xr netmap 4 ,
|
||||
and it can be compiled into the kernel by adding the following
|
||||
line in your kernel configuration file:
|
||||
.Bd -ragged -offset indent
|
||||
.Cd "device netmap"
|
||||
.Ed
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
device driver provides direct access to host netmap ports,
|
||||
from within a Virtual Machine (VM).
|
||||
Applications running inside
|
||||
the VM can access the TX/RX rings and buffers of a netmap port
|
||||
that the hypervisor has passed-through to the VM.
|
||||
Hypervisor support for
|
||||
.Nm
|
||||
is currently available for QEMU/KVM.
|
||||
Any
|
||||
.Xr netmap 4
|
||||
port can be passed-through, including physical NICs,
|
||||
.Xr vale 4
|
||||
ports, netmap pipes, etc.
|
||||
.Pp
|
||||
The main use-case for netmap passthrough is Network Function
|
||||
Virtualization (NFV), where middlebox applications running within
|
||||
VMs may want to process very high packet rates (e.g., 1-10 millions
|
||||
packets per second or more).
|
||||
Note, however, that those applications
|
||||
must use the device in netmap mode in order to achieve such rates.
|
||||
In addition to the general advantages of netmap, the improved
|
||||
performance of
|
||||
.Nm
|
||||
when compared to hypervisor device emulation or paravirtualization (e.g.,
|
||||
.Xr vtnet 4 ,
|
||||
.Xr vmx 4 )
|
||||
comes from the hypervisor being completely bypassed in the data-path.
|
||||
For example, when using
|
||||
.Xr vtnet 4
|
||||
the VM has to convert each
|
||||
.Xr mbuf 9
|
||||
to a VirtIO-specific packet representation
|
||||
and publish that to a VirtIO queue; on the hypervisor side, the
|
||||
packet is extracted from the VirtIO queue and converted to a
|
||||
hypervisor-specific packet representation.
|
||||
The overhead of format conversions (and packet copies, in same cases) is not
|
||||
incured by
|
||||
.Nm
|
||||
in netmap mode, because mbufs are not used at all, and the packet format
|
||||
is the one defined by netmap (e.g.,
|
||||
.Ar struct netmap_slot )
|
||||
along the whole data-path.
|
||||
No format conversions or copies happen.
|
||||
.Pp
|
||||
It is also possible to use a
|
||||
.Nm
|
||||
device like a regular network interface, which interacts with the
|
||||
.Fx
|
||||
network stack (i.e., not in netmap mode).
|
||||
However, in that case it is necessary to pay the cost of data copies
|
||||
between mbufs and netmap buffers, which generally results in lower
|
||||
TCP/UDP performance than
|
||||
.Xr vtnet 4
|
||||
or other paravirtualized network devices.
|
||||
If the passed-through netmap port supports the VirtIO network header,
|
||||
.Nm
|
||||
is able to use it, and support TCP/UDP checksum offload (for both transmit
|
||||
and receive), TCP segmentation offload (TSO) and TCP large receive offload
|
||||
(LRO).
|
||||
Currently,
|
||||
.Xr vale 4
|
||||
ports support the header.
|
||||
Note that the VirtIO network header is generally not used in NFV
|
||||
use-cases, because middleboxes are not endpoints of TCP/UDP connections.
|
||||
.Sh TUNABLES
|
||||
Tunables can be set at the
|
||||
.Xr loader 8
|
||||
prompt before booting the kernel or stored in
|
||||
.Xr loader.conf 5 .
|
||||
.Bl -tag -width "xxxxxx"
|
||||
.It Va dev.netmap.ptnet_vnet_hdr
|
||||
This tunable enables (1) or disables (0) the VirtIO network header.
|
||||
If enabled,
|
||||
.Nm
|
||||
uses the same header used by
|
||||
.Xr vtnet 4
|
||||
to exchange offload metadata with the hypervisor.
|
||||
If disabled, no header is prepended to transmitted and received
|
||||
packets.
|
||||
The metadata is necessary to support TCP/UDP checksum offloads,
|
||||
TSO, and LRO.
|
||||
The default value is 1.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr netintro 4 ,
|
||||
.Xr netmap 4 ,
|
||||
.Xr vale 4 ,
|
||||
.Xr virtio 4 ,
|
||||
.Xr vmx 4 ,
|
||||
.Xr ifconfig 8
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Nm
|
||||
driver was written by
|
||||
.An Vincenzo Maffione Aq Mt vmaffione@FreeBSD.org .
|
||||
It first appeared in
|
||||
.Fx 12.0 .
|
||||
Loading…
Reference in New Issue
Block a user