1.\" Copyright (c) 2011 Bryan Venteicher 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.Dd September 30, 2025 26.Dt VTNET 4 27.Os 28.Sh NAME 29.Nm vtnet 30.Nd VirtIO Ethernet driver 31.Sh SYNOPSIS 32To compile this driver into the kernel, 33place the following lines in your 34kernel configuration file: 35.Bd -ragged -offset indent 36.Cd "device vtnet" 37.Ed 38.Pp 39Alternatively, to load the driver as a 40module at boot time, place the following line in 41.Xr loader.conf 5 : 42.Bd -literal -offset indent 43if_vtnet_load="YES" 44.Ed 45.Sh DESCRIPTION 46The 47.Nm 48device driver provides support for VirtIO Ethernet devices. 49.Pp 50If the hypervisor advertises the appropriate features, the 51.Nm 52driver supports TCP/UDP checksum offload for both transmit and receive, 53TCP segmentation offload (TSO), TCP large receive offload (LRO), 54hardware VLAN tag stripping/insertion features, a multicast hash filter, 55as well as Jumbo Frames (up to 9216 bytes), which can be 56configured via the interface MTU setting. 57.Pp 58Two flavors of TCP LRO are supported: 59Hardware TCP LRO, which is performed by the host providing TCP segments larger 60than the MTU to the guest, and Software TCP LRO, which is performed by the 61network stack of the guest processing TCP segments in an optimized way. 62Only one flavour of TCP LRO should be used. 63Since hardware TCP LRO can have bad interactions with IP forwarding and 64software TCP LRO mitigates several drawbacks of hardware TCP LRO, the default 65setting is to disable hardware TCP LRO. 66See the loader tunable 67.Va hw.vtnet. Ns Ar X Ns Va .lro_disable . 68.Pp 69TCP/UDP receive checksum offload cannot be configured independently for IPv4 70and IPv6. 71Selecting an MTU larger than 1500 bytes with the 72.Xr ifconfig 8 73utility configures the adapter to receive and transmit Jumbo Frames. 74.Pp 75For more information on configuring this device, see 76.Xr ifconfig 8 . 77.Sh LOADER TUNABLES 78Tunables can be set at the 79.Xr loader 8 80prompt before booting the kernel or stored in 81.Xr loader.conf 5 . 82.Bl -tag -width "xxxxxx" 83.It Va hw.vtnet.csum_disable 84.It Va hw.vtnet. Ns Ar X Ns Va .csum_disable 85This tunable disables receive and transmit checksum offloading for TCP and 86UDP. 87This also implies that TCP segmentation offloading and large receive offload 88are disabled. 89The default value is 0. 90.It Va hw.vtnet.fixup_needs_csum 91.It Va hw.vtnet. Ns Ar X Ns Va .fixup_needs_csum 92This tunable enforces the calculation of a valid TCP or UDP checksum for 93packets received with 94.Dv VIRTIO_NET_HDR_F_NEEDS_CSUM 95being set in the 96.Va flags 97field of the structure 98.Vt struct virtio_net_hdr . 99It also marks the checksum as being correct in the mbuf packet header. 100The default value is 0. 101This tunable is deprecated and will be removed in 102.Fx 16 . 103.It Va hw.vtnet.tso_disable 104.It Va hw.vtnet. Ns Ar X Ns Va .tso_disable 105This tunable disables TCP segmentation offloading. 106The default value is 0. 107.It Va hw.vtnet.lro_disable 108.It Va hw.vtnet. Ns Ar X Ns Va .lro_disable 109This tunable disables hardware TCP LRO. 110The default value is 1. 111.It Va hw.vtnet.mq_disable 112.It Va hw.vtnet. Ns Ar X Ns Va .mq_disable 113This tunable disables multiqueue. 114The default value is 0. 115.It Va hw.vtnet.mq_max_pairs 116.It Va hw.vtnet. Ns Ar X Ns Va .mq_max_pairs 117This tunable sets the maximum number of transmit and receive queue pairs. 118Multiple queues are only supported when the Multiqueue feature is negotiated. 119This driver supports a maximum of 8 queue pairs. 120The number of queue pairs used is the lesser of the maximum supported by the 121driver and the hypervisor, the number of CPUs present in the guest, and this 122tunable if not zero. 123The default value is 0. 124.It Va hw.vtnet.tso_maxlen 125.It Va hw.vtnet. Ns Ar X Ns Va .tso_maxlen 126This tunable sets the TSO burst limit. 127The default value is 65535. 128.It Va hw.vtnet.rx_process_limit 129.It Va hw.vtnet. Ns Ar X Ns Va .rx_process_limit 130This tunable sets the number of RX segments processed in one pass. 131The default value is 1024. 132.It Va hw.vtnet.lro_entry_count 133.It Va hw.vtnet. Ns Ar X Ns Va .lro_entry_count 134This tunable sets the software TCP LRO entry count. 135The default value is 128, the minimum value is 8. 136.It Va hw.vtnet.lro_mbufq_depth 137.It Va hw.vtnet. Ns Ar X Ns Va .lro_mbufq_depth 138This tunable sets the depth of the software TCP LRO mbuf queue. 139The default value is 0. 140.It Va hw.vtnet.altq_disable 141This tunable disables ALTQ support, allowing the use of multiqueue instead. 142This option applies to all interfaces. 143The default value is 0. 144.El 145.Sh TRANSMIT QUEUE STATISTICS 146For each transmit queue of each interface the following read-only statistics 147are provided: 148.Bl -tag -width "xxxxxx" 149.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .rescheduled 150The number of times the transmit interrupt handler was rescheduled. 151.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .tso 152The number of times TCP segment offloading was performed. 153.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .csum 154The number of times transmit checksum offloading for UDP or TCP was 155performed. 156.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .omcasts 157The number of multicast packets that were transmitted. 158.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .obytes 159The number of bytes that were transmitted (based on Ethernet frames). 160.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .opackets 161The number of packets that were transmitted (Ethernet frames). 162.El 163.Sh RECEIVE QUEUE STATISTICS 164For each receive queue of each interface the following read-only statistics 165are provided: 166.Bl -tag -width "xxxxxx" 167.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .rescheduled 168The number of times the receive interrupt handler was rescheduled. 169.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .host_lro 170The number of times TCP large receive offload was performed. 171.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed 172The number of times a packet with a request for receive or transmit checksum 173offloading was received and this request failed. 174The different reasons for the failure are counted by 175.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_inaccessible_ipproto , 176.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto , 177.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype , 178and 179.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_offset . 180.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum 181The number of times receive checksum offloading for UDP or TCP was performed. 182.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ierrors 183The number of times an error occurred during input processing. 184.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .iqdrops 185The number of times a packet was dropped during input processing. 186.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ibytes 187The number of bytes that were received (based on Ethernet frames). 188.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ipackets 189The number of packets that were received (Ethernet frames). 190.El 191.Sh INTERFACE TRANSMIT STATISTICS 192For each interface the following read-only transmit statistics are provided: 193.Bl -tag -width "xxxxxx" 194.It Va dev.vtnet. Ns Ar X Ns Va .tx_task_rescheduled 195The sum of 196.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .rescheduled 197over all transmit queues of the interface. 198.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_offloaded 199The sum of 200.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .tso 201over all transmit queues of the interface. 202.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_offloaded 203The sum of 204.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .csum 205over all transmit queues of the interface. 206.It Va dev.vtnet. Ns Ar X Ns Va .tx_defrag_failed 207The number of times an attempt to defragment an mbuf chain failed during a 208transmit operation. 209.It Va dev.vtnet. Ns Ar X Ns Va .tx_defragged 210The number of times an mbuf chain was defragmented during a transmit operation. 211.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_without_csum 212The number of times TCP segment offloading was attempted without transmit 213checksum offloading. 214.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_not_tcp 215The number of times TCP segment offloading was attempted for a non-TCP packet. 216.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_proto_mismatch 217The number of times the IP protocol version of the transmit checksum 218offloading request did not match the IP protocol version of the packet. 219.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_unknown_ethtype 220The number of times a transmit offload operation was requested for an 221ethernet frame for which the EtherType was neither IPv4 nor IPv6 222(considering simple VLAN tagging). 223.El 224.Sh INTERFACE RECEIVE STATISTICS 225For each interface the following read-only receive statistics are provided: 226.Bl -tag -width "xxxxxx" 227.It Va dev.vtnet. Ns Ar X Ns Va .rx_task_rescheduled 228The sum of 229.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .rescheduled 230over all receive queues of the interface. 231.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_offloaded 232The sum of 233.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum 234over all receive queues of the interface. 235.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_failed 236The sum of 237.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed 238over all receive queues of the interface. 239.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_inaccessible_ipproto 240The number of times a packet with a request for receive or transmit checksum 241offloading was received where the IP protocol was not accessible. 242.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_offset 243The number of times fixing the checksum required by 244.Va hw.vtnet.fixup_needs_csum 245or 246.Va hw.vtnet. Ns Ar X Ns Va .fixup_needs_csum 247was attempted for a packet where the csum is not located in the first mbuf. 248.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto 249The number of times a packet with a request for receive or transmit checksum 250offloading was received where the IP protocol was neither TCP nor UDP. 251.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype 252The number of times a packet with a request for receive or transmit checksum 253offloading was received where the EtherType was neither IPv4 nor IPv6. 254.It Va dev.vtnet. Ns Ar X Ns Va .rx_mergeable_failed 255The number of times receiving a mergable buffer failed. 256.It Va dev.vtnet. Ns Ar X Ns Va .rx_enq_replacement_failed 257The number of times the enqueuing the replacement receive mbuf chain failed. 258.It Va dev.vtnet. Ns Ar X Ns Va .rx_frame_too_large 259The number of times the frame was loger than the mbuf chain during large 260receive offload without mergeable buffers. 261.It Va dev.vtnet. Ns Ar X Ns Va .mbuf_alloc_failed 262The number of times an mbuf cluster allocation for the receive buffer failed. 263.El 264.Sh INTERFACE CONFIGURATION PARAMETER 265For each interface the following read-only configuration parameters are 266provided: 267.Bl -tag -width "xxxxxx" 268.It Va dev.vtnet. Ns Ar X Ns Va .act_vq_pairs 269The number of active virtqueue pairs. 270.It Va dev.vtnet. Ns Ar X Ns Va .req_vq_pairs 271The number of requested virtqueue pairs. 272.It Va dev.vtnet. Ns Ar X Ns Va .max_vq_pairs 273The maximum number of supported virtqueue pairs. 274.El 275.Sh SEE ALSO 276.Xr arp 4 , 277.Xr netintro 4 , 278.Xr ng_ether 4 , 279.Xr virtio 4 , 280.Xr vlan 4 , 281.Xr ifconfig 8 282.Sh HISTORY 283The 284.Nm 285driver was written by 286.An Bryan Venteicher Aq Mt bryanv@FreeBSD.org . 287It first appeared in 288.Fx 9.0 . 289.Sh CAVEATS 290The 291.Nm 292driver only supports LRO when the hypervisor advertises the 293mergeable buffer feature. 294