xref: /freebsd/share/man/man4/xnb.4 (revision 87c1627502a5dde91e5284118eec8682b60f27a2)
1.\" Copyright (c) 2012 Spectra Logic Corporation
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.\"    without modification.
10.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
11.\"    substantially similar to the "NO WARRANTY" disclaimer below
12.\"    ("Disclaimer") and any redistribution must be conditioned upon
13.\"    including a substantially similar Disclaimer requirement for further
14.\"    binary redistribution.
15.\"
16.\" NO WARRANTY
17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
20.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
25.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
26.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27.\" POSSIBILITY OF SUCH DAMAGES.
28.\"
29.\" Authors: Alan Somers         (Spectra Logic Corporation)
30.\"
31.\" $FreeBSD$
32.\"
33.Dd January 6, 2012
34.Dt XNB 4
35.Os
36.Sh NAME
37.Nm xnb
38.Nd "Xen Paravirtualized Backend Ethernet Driver"
39.Sh SYNOPSIS
40To compile this driver into the kernel, place the following lines in your
41kernel configuration file:
42.Bd -ragged -offset indent
43.Cd "options XENHVM"
44.Cd "device xenpci"
45.Ed
46.Sh DESCRIPTION
47The
48.Nm
49driver provides the back half of a paravirtualized
50.Xr xen 4
51network connection.
52The netback and netfront drivers appear to their respective operating
53systems as Ethernet devices linked by a crossover cable.
54Typically,
55.Nm
56will run on Domain 0 and the netfront driver will run on a guest domain.
57However, it is also possible to run
58.Nm
59on a guest domain.
60It may be bridged or routed to provide the netfront's
61domain access to other guest domains or to a physical network.
62.Pp
63In most respects, the
64.Nm
65device appears to the OS as an other Ethernet device.
66It can be configured at runtime entirely with
67.Xr ifconfig 8 .
68In particular, it supports MAC changing, arbitrary MTU sizes, checksum
69offload for IP, UDP, and TCP for both receive and transmit, and TSO.
70However, see
71.Sx CAVEATS
72before enabling txcsum, rxcsum, or tso.
73.Sh SYSCTL VARIABLES
74The following read-only variables are available via
75.Xr sysctl 8 :
76.Bl -tag -width indent
77.It Va dev.xnb.%d.dump_rings
78Displays information about the ring buffers used to pass requests between the
79netfront and netback.
80Mostly useful for debugging, but can also be used to
81get traffic statistics.
82.It Va dev.xnb.%d.unit_test_results
83Runs a builtin suite of unit tests and displays the results.
84Does not affect the operation of the driver in any way.
85Note that the test suite simulates error conditions; this will result in
86error messages being printed to the system log.
87.El
88.Sh SEE ALSO
89.Xr arp 4 ,
90.Xr netintro 4 ,
91.Xr ng_ether 4 ,
92.Xr xen 4 ,
93.Xr ifconfig 8
94.Sh HISTORY
95The
96.Nm
97device driver first appeared in
98.Fx 10.0 .
99.Sh AUTHORS
100The
101.Nm
102driver was written by
103.An Alan Somers
104.Aq alans@spectralogic.com
105and
106.An John Suykerbuyk
107.Aq johns@spectralogic.com .
108.Sh CAVEATS
109Packets sent through Xennet pass over shared memory, so the protocol includes
110no form of link-layer checksum or CRC.
111Furthermore, Xennet drivers always report to their hosts that they support
112receive and transmit checksum offloading.
113They "offload" the checksum calculation by simply skipping it.
114That works fine for packets that are exchanged between two domains on the same
115machine.
116However, when a Xennet interface is bridged to a physical interface,
117a correct checksum must be attached to any packets bound for that physical
118interface.
119Currently, FreeBSD lacks any mechanism for an ethernet device to
120inform the OS that newly received packets are valid even though their checksums
121are not.
122So if the netfront driver is configured to offload checksum calculations,
123it will pass non-checksumed packets to
124.Nm ,
125which must then calculate the checksum in software before passing the packet
126to the OS.
127.Pp
128For this reason, it is recommended that if
129.Nm
130is bridged to a physical interface, then transmit checksum offloading should be
131disabled on the netfront.
132The Xennet protocol does not have any mechanism for the netback to request
133the netfront to do this; the operator must do it manually.
134.Sh BUGS
135The
136.Nm
137driver does not properly checksum UDP datagrams that span more than one
138Ethernet frame.
139Nor does it correctly checksum IPv6 packets.
140To workaround that bug, disable transmit checksum offloading on the
141netfront driver.
142