NAME

       ptnet — Ethernet driver for passed-through netmap ports

SYNOPSIS

       This  network  driver  is  included  in  netmap(4),  and it can be compiled into the kernel by adding the
       following line in your kernel configuration file:

             device netmap

DESCRIPTION

       The ptnet 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  ptnet  is  currently  available  for
       QEMU/KVM.   Any  netmap(4)  port  can  be  passed-through, including physical NICs, vale(4) ports, netmap
       pipes, etc.

       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
       ptnet when compared to hypervisor device emulation or paravirtualization (e.g., vtnet(4),  vmx(4))  comes
       from  the hypervisor being completely bypassed in the data-path.  For example, when using vtnet(4) the VM
       has to convert each 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 ptnet in netmap mode, because mbufs are not used at all, and the packet
       format is the one defined by netmap (e.g., struct netmap_slot) along  the  whole  data-path.   No  format
       conversions or copies happen.

       It  is  also  possible  to  use a ptnet device like a regular network interface, which interacts with the
       FreeBSD 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 vtnet(4) or other paravirtualized network devices.  If the passed-through netmap port  supports  the
       VirtIO  network  header, ptnet 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,  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.

TUNABLES

       Tunables can be set at the loader(8) prompt before booting the kernel or stored in loader.conf(5).

       dev.netmap.ptnet_vnet_hdr
               This tunable enables (1) or disables (0) the VirtIO network header.  If enabled, ptnet  uses  the
               same  header  used by 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.

SEE ALSO

       netintro(4), netmap(4), vale(4), virtio(4), vmx(4), ifconfig(8)

HISTORY

       The  ptnet  driver  was  written  by  Vincenzo  Maffione  <vmaffione@FreeBSD.org>.   It first appeared in
       FreeBSD 12.0.

Debian                                          December 11, 2018                                       PTNET(4)