From owner-svn-src-stable-12@freebsd.org Sat Dec 15 18:11:42 2018 Return-Path: Delivered-To: svn-src-stable-12@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 415ED1328E81; Sat, 15 Dec 2018 18:11:42 +0000 (UTC) (envelope-from vmaffione@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id D8CBF8320E; Sat, 15 Dec 2018 18:11:41 +0000 (UTC) (envelope-from vmaffione@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id CA74E1B357; Sat, 15 Dec 2018 18:11:41 +0000 (UTC) (envelope-from vmaffione@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id wBFIBfp3067671; Sat, 15 Dec 2018 18:11:41 GMT (envelope-from vmaffione@FreeBSD.org) Received: (from vmaffione@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id wBFIBfps067670; Sat, 15 Dec 2018 18:11:41 GMT (envelope-from vmaffione@FreeBSD.org) Message-Id: <201812151811.wBFIBfps067670@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: vmaffione set sender to vmaffione@FreeBSD.org using -f From: Vincenzo Maffione Date: Sat, 15 Dec 2018 18:11:41 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-12@freebsd.org Subject: svn commit: r342132 - stable/12/share/man/man4 X-SVN-Group: stable-12 X-SVN-Commit-Author: vmaffione X-SVN-Commit-Paths: stable/12/share/man/man4 X-SVN-Commit-Revision: 342132 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: D8CBF8320E X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-2.79 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-0.99)[-0.988,0]; NEURAL_HAM_SHORT(-0.92)[-0.919,0]; ASN(0.00)[asn:11403, ipnet:2610:1c1:1::/48, country:US]; NEURAL_HAM_LONG(-0.89)[-0.888,0] X-BeenThere: svn-src-stable-12@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: SVN commit messages for only the 12-stable src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 15 Dec 2018 18:11:42 -0000 Author: vmaffione Date: Sat Dec 15 18:11:41 2018 New Revision: 342132 URL: https://svnweb.freebsd.org/changeset/base/342132 Log: MFC r341993 netmap: add man page for ptnet Add a man page for ptnet(4), describing the guest driver for netmap passthrough. Reviewed by: bcr Differential Revision: https://reviews.freebsd.org/D18518 Added: stable/12/share/man/man4/ptnet.4 - copied unchanged from r341993, head/share/man/man4/ptnet.4 Modified: Directory Properties: stable/12/ (props changed) Copied: stable/12/share/man/man4/ptnet.4 (from r341993, head/share/man/man4/ptnet.4) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/12/share/man/man4/ptnet.4 Sat Dec 15 18:11:41 2018 (r342132, copy of r341993, head/share/man/man4/ptnet.4) @@ -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 .