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 August 21, 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. 57Selecting an MTU larger than 1500 bytes with the 58.Xr ifconfig 8 59utility configures the adapter to receive and transmit Jumbo Frames. 60.Pp 61For more information on configuring this device, see 62.Xr ifconfig 8 . 63.Sh LOADER TUNABLES 64Tunables can be set at the 65.Xr loader 8 66prompt before booting the kernel or stored in 67.Xr loader.conf 5 . 68.Bl -tag -width "xxxxxx" 69.It Va hw.vtnet.csum_disable 70.It Va hw.vtnet. Ns Ar X Ns Va .csum_disable 71This tunable disables receive and transmit checksum offloading for TCP and 72UDP. 73This also implies that TCP segmentation offloading and large receive offload 74are disabled. 75The default value is 0. 76.It Va hw.vtnet.fixup_needs_csum 77.It Va hw.vtnet. Ns Ar X Ns Va .fixup_needs_csum 78This tunable enforces the calculation of a valid TCP or UDP checksum for 79packets received with 80.Dv VIRTIO_NET_HDR_F_NEEDS_CSUM 81being set in the 82.Va flags 83field of the structure 84.Vt struct virtio_net_hdr . 85It also marks the checksum as being correct in the mbuf packet header. 86The default value is 0. 87.It Va hw.vtnet.tso_disable 88.It Va hw.vtnet. Ns Ar X Ns Va .tso_disable 89This tunable disables TCP segmentation offloading. 90The default value is 0. 91.It Va hw.vtnet.lro_disable 92.It Va hw.vtnet. Ns Ar X Ns Va .lro_disable 93This tunable disables large receive offload. 94The default value is 0. 95.It Va hw.vtnet.mq_disable 96.It Va hw.vtnet. Ns Ar X Ns Va .mq_disable 97This tunable disables multiqueue. 98The default value is 0. 99.It Va hw.vtnet.mq_max_pairs 100.It Va hw.vtnet. Ns Ar X Ns Va .mq_max_pairs 101This tunable sets the maximum number of transmit and receive queue pairs. 102Multiple queues are only supported when the Multiqueue feature is negotiated. 103This driver supports a maximum of 8 queue pairs. 104The number of queue pairs used is the lesser of the maximum supported by the 105driver and the hypervisor, the number of CPUs present in the guest, and this 106tunable if not zero. 107The default value is 0. 108.It Va hw.vtnet.tso_maxlen 109.It Va hw.vtnet. Ns Ar X Ns Va .tso_maxlen 110This tunable sets the TSO burst limit. 111The default value is 65535. 112.It Va hw.vtnet.rx_process_limit 113.It Va hw.vtnet. Ns Ar X Ns Va .rx_process_limit 114This tunable sets the number of RX segments processed in one pass. 115The default value is 1024. 116.It Va hw.vtnet.lro_entry_count 117.It Va hw.vtnet. Ns Ar X Ns Va .lro_entry_count 118This tunable sets the software LRO entry count. 119The default value is 128, the minimum value is 8. 120.It Va hw.vtnet.lro_mbufq_depth 121.It Va hw.vtnet. Ns Ar X Ns Va .lro_mbufq_depth 122This tunable sets the depth of the software LRO mbuf queue. 123The default value is 0. 124.It Va hw.vtnet.altq_disable 125This tunable disables ALTQ support, allowing the use of multiqueue instead. 126This option applies to all interfaces. 127The default value is 0. 128.El 129.Sh TRANSMIT QUEUE STATISTICS 130.Bl -tag -width "xxxxxx" 131For each transmit queue of each interface the following read-only statistics 132are provided: 133.Bl -tag -width "xxxxxx" 134.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .rescheduled 135The number of times the transmit interrupt handler was rescheduled. 136.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .tso 137The number of times TCP segment offloading was performed. 138.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .csum 139The number of times transmit checksum offloading for UDP or TCP was 140performed. 141.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .omcasts 142The number of multicast packets that were transmitted. 143.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .obytes 144The number of bytes that were transmitted (based on Ethernet frames). 145.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .opackets 146The number of packets that were transmitted (Ethernet frames). 147.El 148.Sh RECEIVE QUEUE STATISTICS 149For each receive queue of each interface the following read-only statistics 150are provided: 151.Bl -tag -width "xxxxxx" 152.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .rescheduled 153The number of times the receive interrupt handler was rescheduled. 154.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .host_lro 155The number of times TCP large receive offload was performed. 156.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed 157Currently not used. 158.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum 159The number of times receive checksum offloading for UDP or TCP was performed. 160.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ierrors 161The number of times an error occurred during input processing. 162.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .iqdrops 163The number of times a packet was dropped during input processing. 164.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ibytes 165The number of bytes that were received (based on Ethernet frames). 166.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ipackets 167The number of packets that were received (Ethernet frames). 168.El 169.Sh INTERFACE TRANSMIT STATISTICS 170For each interface the following read-only transmit statistics are provided: 171.Bl -tag -width "xxxxxx" 172.It Va dev.vtnet. Ns Ar X Ns Va .tx_task_rescheduled 173The sum of 174.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .rescheduled 175over all transmit queues of the interface. 176.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_offloaded 177The sum of 178.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .tso 179over all transmit queues of the interface. 180.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_offloaded 181The sum of 182.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .csum 183over all transmit queues of the interface. 184.It Va dev.vtnet. Ns Ar X Ns Va .tx_defrag_failed 185The number of times an attempt to defragment an mbuf chain failed during a 186transmit operation. 187.It Va dev.vtnet. Ns Ar X Ns Va .tx_defragged 188The number of times an mbuf chain was defragmented during a transmit operation. 189.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_without_csum 190The number of times TCP segment offloading was attempted without transmit 191checksum offloading. 192.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_not_tcp 193The number of times TCP segment offloading was attempted for a non-TCP packet. 194.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_proto_mismatch 195The number of times the IP protocol version of the transmit checksum 196offloading request did not match the IP protocol version of the packet. 197.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_unknown_ethtype 198The number of times a transmit offload operation was requested for an 199ethernet frame for which the EtherType was neither IPv4 nor IPv6 200(considering simple VLAN tagging). 201.El 202.Sh INTERFACE RECEIVE STATISTICS 203For each interface the following read-only receive statistics are provided: 204.Bl -tag -width "xxxxxx" 205.It Va dev.vtnet. Ns Ar X Ns Va .rx_task_rescheduled 206The sum of 207.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .rescheduled 208over all receive queues of the interface. 209.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_offloaded 210The sum of 211.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum 212over all receive queues of the interface. 213.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_failed 214The sum of 215.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed 216over all receive queues of the interface. 217.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_proto 218Currently unused. 219.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_offset 220Currently unused. 221.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto 222Currently unused. 223.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype 224The number of times fixing the checksum required by 225.Va hw.vtnet.fixup_needs_csum 226or 227.Va hw.vtnet. Ns Ar X Ns Va .fixup_needs_csum 228was attempted for a packet with an EtherType other than IPv4 or IPv6. 229.It Va dev.vtnet. Ns Ar X Ns Va .rx_mergeable_failed 230The number of times receiving a mergable buffer failed. 231.It Va dev.vtnet. Ns Ar X Ns Va .rx_enq_replacement_failed 232The number of times the enqueuing the replacement receive mbuf chain failed. 233.It Va dev.vtnet. Ns Ar X Ns Va .rx_frame_too_large 234The number of times the frame was loger than the mbuf chain during large 235receive offload without mergeable buffers. 236.It Va dev.vtnet. Ns Ar X Ns Va .mbuf_alloc_failed 237The number of times an mbuf cluster allocation for the receive buffer failed. 238.El 239.Sh INTERFACE CONFIGURATION PARAMETER 240For each interface the following read-only configuration parameters are 241provided: 242.Bl -tag -width "xxxxxx" 243.It Va dev.vtnet. Ns Ar X Ns Va .act_vq_pairs 244The number of active virtqueue pairs. 245.It Va dev.vtnet. Ns Ar X Ns Va .req_vq_pairs 246The number of requested virtqueue pairs. 247.It Va dev.vtnet. Ns Ar X Ns Va .max_vq_pairs 248The maximum number of supported virtqueue pairs. 249.El 250.Sh SEE ALSO 251.Xr arp 4 , 252.Xr netintro 4 , 253.Xr ng_ether 4 , 254.Xr virtio 4 , 255.Xr vlan 4 , 256.Xr ifconfig 8 257.Sh HISTORY 258The 259.Nm 260driver was written by 261.An Bryan Venteicher Aq Mt bryanv@FreeBSD.org . 262It first appeared in 263.Fx 9.0 . 264.Sh CAVEATS 265The 266.Nm 267driver only supports LRO when the hypervisor advertises the 268mergeable buffer feature. 269