PTNET(4)

💖 PTNET 💖

okay bestie, sit DOWN, because we're talking about ptnet — the Ethernet driver for passed-through netmap ports, straight out of the Kernel Interfaces Manual. this is genuinely one of the coolest things in the whole netmap(4) situation and i need you to be normal about it (i will not be normal about it).

---

✨ NAME ✨

ptnet — Ethernet driver for passed-through netmap ports 🦋

---

✨ SYNOPSIS ✨

okay so this network driver is literally included in netmap(4), and if you want it compiled into your kernel you just add this one iconic little line to your kernel configuration file:

device netmap

that's it. that's the whole thing. periodt. 💅

---

✨ DESCRIPTION ✨

so the ptnet device driver gives you direct access to host netmap ports, from inside a Virtual Machine (VM). like, applications running inside the VM can reach 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. and honestly? any netmap(4) port can be passed-through — physical NICs, vale(4) ports, netmap pipes, etc. all of them. no gatekeeping. 🌈

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 🔥). but lowkey important caveat: those applications must use the device in netmap mode in order to achieve such rates. no cap.

so on top of 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. let me paint you a picture, bestie:

• with vtnet(4), the VM has to convert each mbuf(9) to a VirtIO-specific packet representation and publish that to a VirtIO queue 😭
• then 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. none. zero. ate and left no crumbs. 👑

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. so like, know what you're signing up for. 🫶

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. and note that the VirtIO network header is generally not used in NFV use-cases, because middleboxes are not endpoints of TCP/UDP connections. iykyk. 🧚

---

✨ TUNABLES ✨

tunables can be set at the loader(8) prompt before booting the kernel or stored in loader.conf(5). so many options, so little time. 💜

• 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 ✨

the whole friend group, fr fr:

• 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. iconic behavior honestly 🌸

---

and that's the whole page bestie!! this one came from the Debian crew, dated December 11, 2018 💖✨ go forth and pass through some netmap ports, you've got this 🎀🦋💅