path: root/static/freebsd/man4/vtnet.4

.\" Copyright (c) 2011 Bryan Venteicher
.\" 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.
.\"
.Dd December 19, 2025
.Dt VTNET 4
.Os
.Sh NAME
.Nm vtnet
.Nd VirtIO Ethernet driver
.Sh SYNOPSIS
To compile this driver into the kernel,
place the following lines in your
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device vtnet"
.Ed
.Pp
Alternatively, to load the driver as a
module at boot time, place the following line in
.Xr loader.conf 5 :
.Bd -literal -offset indent
if_vtnet_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
device driver provides support for VirtIO Ethernet devices.
.Pp
If the hypervisor advertises the appropriate features, the
.Nm
driver supports TCP/UDP checksum offload for both transmit and receive,
TCP segmentation offload (TSO), TCP large receive offload (LRO),
hardware VLAN tag stripping/insertion features, a multicast hash filter,
as well as Jumbo Frames (up to 9216 bytes), which can be
configured via the interface MTU setting.
.Pp
Two flavors of TCP LRO are supported:
Hardware TCP LRO, which is performed by the host providing TCP segments larger
than the MTU to the guest, and Software TCP LRO, which is performed by the
network stack of the guest processing TCP segments in an optimized way.
Only one flavour of TCP LRO should be used.
Since hardware TCP LRO can have bad interactions with IP forwarding and
software TCP LRO mitigates several drawbacks of hardware TCP LRO, the default
setting is to disable hardware TCP LRO.
See the loader tunable
.Va hw.vtnet. Ns Ar X Ns Va .lro_disable .
.Pp
TCP/UDP receive checksum offload cannot be configured independently for IPv4
and IPv6.
Selecting an MTU larger than 1500 bytes with the
.Xr ifconfig 8
utility configures the adapter to receive and transmit Jumbo Frames.
.Pp
For more information on configuring this device, see
.Xr ifconfig 8 .
.Sh LOADER 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 hw.vtnet.csum_disable
.It Va hw.vtnet. Ns Ar X Ns Va .csum_disable
This tunable disables receive and transmit checksum offloading for TCP and
UDP.
This also implies that TCP segmentation offloading and large receive offload
are disabled.
The default value is 0.
.It Va hw.vtnet.fixup_needs_csum
.It Va hw.vtnet. Ns Ar X Ns Va .fixup_needs_csum
This tunable enforces the calculation of a valid TCP or UDP checksum for
packets received with 
.Dv VIRTIO_NET_HDR_F_NEEDS_CSUM
being set in the
.Va flags
field of the structure
.Vt struct virtio_net_hdr .
It also marks the checksum as being correct in the mbuf packet header.
The default value is 0.
This tunable is deprecated and will be removed in
.Fx 16 .
.It Va hw.vtnet.tso_disable
.It Va hw.vtnet. Ns Ar X Ns Va .tso_disable
This tunable disables TCP segmentation offloading.
The default value is 0.
.It Va hw.vtnet.lro_disable
.It Va hw.vtnet. Ns Ar X Ns Va .lro_disable
This tunable disables hardware TCP LRO.
The default value is 1.
.It Va hw.vtnet.mq_disable
.It Va hw.vtnet. Ns Ar X Ns Va .mq_disable
This tunable disables multiqueue.
The default value is 0.
.It Va hw.vtnet.mq_max_pairs
.It Va hw.vtnet. Ns Ar X Ns Va .mq_max_pairs
This tunable sets the maximum number of transmit and receive queue pairs.
Multiple queues are only supported when the Multiqueue feature is negotiated.
This driver supports a maximum of 8 queue pairs.
The number of queue pairs used is the lesser of the maximum supported by the
driver and the hypervisor, the number of CPUs present in the guest, and this
tunable if not zero.
The default value is 0.
.It Va hw.vtnet.tso_maxlen
.It Va hw.vtnet. Ns Ar X Ns Va .tso_maxlen
This tunable sets the TSO burst limit.
The default value is 65535.
.It Va hw.vtnet.rx_process_limit
.It Va hw.vtnet. Ns Ar X Ns Va .rx_process_limit
This tunable sets the number of RX segments processed in one pass.
The default value is 1024.
.It Va hw.vtnet.lro_entry_count
.It Va hw.vtnet. Ns Ar X Ns Va .lro_entry_count
This tunable sets the software TCP LRO entry count.
The default value is 128, the minimum value is 8.
.It Va hw.vtnet.lro_mbufq_depth
.It Va hw.vtnet. Ns Ar X Ns Va .lro_mbufq_depth
This tunable sets the depth of the software TCP LRO mbuf queue.
The default value is 0.
.It Va hw.vtnet.altq_disable
This tunable disables ALTQ support, allowing the use of multiqueue instead.
This option applies to all interfaces.
The default value is 0.
.El
.Sh TRANSMIT QUEUE STATISTICS
For each transmit queue of each interface the following read-only statistics
are provided:
.Bl -tag -width "xxxxxx"
.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .rescheduled
The number of times the transmit interrupt handler was rescheduled.
.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .tso
The number of times TCP segment offloading was performed.
.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .csum
The number of times transmit checksum offloading for UDP or TCP was
performed.
.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .omcasts
The number of multicast packets that were transmitted.
.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .obytes
The number of bytes that were transmitted (based on Ethernet frames).
.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .opackets
The number of packets that were transmitted (Ethernet frames).
.El
.Sh RECEIVE QUEUE STATISTICS
For each receive queue of each interface the following read-only statistics
are provided:
.Bl -tag -width "xxxxxx"
.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .rescheduled
The number of times the receive interrupt handler was rescheduled.
.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .host_lro
The number of times TCP large receive offload was performed.
.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed
The number of times a packet with a request for receive or transmit checksum
offloading was received and this request failed.
The different reasons for the failure are counted by
.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_inaccessible_ipproto ,
.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto ,
.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype ,
and
.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_offset .
.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum
The number of times receive checksum offloading for UDP or TCP was performed.
.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ierrors
The number of times an error occurred during input processing.
.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .iqdrops
The number of times a packet was dropped during input processing.
.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ibytes
The number of bytes that were received (based on Ethernet frames).
.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ipackets
The number of packets that were received (Ethernet frames).
.El
.Sh INTERFACE TRANSMIT STATISTICS
For each interface the following read-only transmit statistics are provided:
.Bl -tag -width "xxxxxx"
.It Va dev.vtnet. Ns Ar X Ns Va .tx_task_rescheduled
The sum of
.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .rescheduled
over all transmit queues of the interface.
.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_offloaded
The sum of
.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .tso
over all transmit queues of the interface.
.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_offloaded
The sum of
.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .csum
over all transmit queues of the interface.
.It Va dev.vtnet. Ns Ar X Ns Va .tx_defrag_failed
The number of times an attempt to defragment an mbuf chain failed during a
transmit operation.
.It Va dev.vtnet. Ns Ar X Ns Va .tx_defragged
The number of times an mbuf chain was defragmented during a transmit operation.
.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_without_csum
The number of times TCP segment offloading was attempted without transmit
checksum offloading.
.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_not_tcp
The number of times TCP segment offloading was attempted for a non-TCP packet.
.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_proto_mismatch
The number of times the IP protocol version of the transmit checksum
offloading request did not match the IP protocol version of the packet.
.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_unknown_ethtype
The number of times a transmit offload operation was requested for an
ethernet frame for which the EtherType was neither IPv4 nor IPv6
(considering simple VLAN tagging).
.El
.Sh INTERFACE RECEIVE STATISTICS
For each interface the following read-only receive statistics are provided:
.Bl -tag -width "xxxxxx"
.It Va dev.vtnet. Ns Ar X Ns Va .rx_task_rescheduled
The sum of
.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .rescheduled
over all receive queues of the interface.
.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_offloaded
The sum of
.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum
over all receive queues of the interface.
.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_failed
The sum of
.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed
over all receive queues of the interface.
.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_inaccessible_ipproto
The number of times a packet with a request for receive or transmit checksum
offloading was received where the IP protocol was not accessible.
.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_offset
The number of times fixing the checksum required by
.Va hw.vtnet.fixup_needs_csum
or
.Va hw.vtnet. Ns Ar X Ns Va .fixup_needs_csum
was attempted for a packet where the csum is not located in the first mbuf.
.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto
The number of times a packet with a request for receive or transmit checksum
offloading was received where the IP protocol was neither TCP nor UDP.
.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype
The number of times a packet with a request for receive or transmit checksum
offloading was received where the EtherType was neither IPv4 nor IPv6.
.It Va dev.vtnet. Ns Ar X Ns Va .rx_mergeable_failed
The number of times receiving a mergable buffer failed.
.It Va dev.vtnet. Ns Ar X Ns Va .rx_enq_replacement_failed
The number of times the enqueuing the replacement receive mbuf chain failed.
.It Va dev.vtnet. Ns Ar X Ns Va .rx_frame_too_large
The number of times the frame was loger than the mbuf chain during large
receive offload without mergeable buffers.
.It Va dev.vtnet. Ns Ar X Ns Va .mbuf_alloc_failed
The number of times an mbuf cluster allocation for the receive buffer failed.
.El
.Sh INTERFACE CONFIGURATION PARAMETER
For each interface the following read-only configuration parameters are
provided:
.Bl -tag -width "xxxxxx"
.It Va dev.vtnet. Ns Ar X Ns Va .act_vq_pairs
The number of active virtqueue pairs.
.It Va dev.vtnet. Ns Ar X Ns Va .req_vq_pairs
The number of requested virtqueue pairs.
.It Va dev.vtnet. Ns Ar X Ns Va .max_vq_pairs
The maximum number of supported virtqueue pairs.
.It Va dev.vtnet. Ns Ar X Ns Va .flags
The flags of the interface.
Mostly for debugging purposes.
.It Va dev.vtnet. Ns Ar X Ns Va .features
The features of the interface as defined by the virtio specification.
.El
.Sh SEE ALSO
.Xr arp 4 ,
.Xr netintro 4 ,
.Xr ng_ether 4 ,
.Xr virtio 4 ,
.Xr vlan 4 ,
.Xr ifconfig 8
.Sh HISTORY
The
.Nm
driver was written by
.An Bryan Venteicher Aq Mt bryanv@FreeBSD.org .
It first appeared in
.Fx 9.0 .
.Sh CAVEATS
The
.Nm
driver only supports LRO when the hypervisor advertises the
mergeable buffer feature.