diff options
author | ken <ken@FreeBSD.org> | 2012-01-26 16:35:09 +0000 |
---|---|---|
committer | ken <ken@FreeBSD.org> | 2012-01-26 16:35:09 +0000 |
commit | 7f685c218aab7dcffad6119b6e3741a0b71a2e97 (patch) | |
tree | d7ac881e15cd62a22e0e8f7d9e34f5708762e482 /share/man/man4/xnb.4 | |
parent | 709d732d543664ea423f0de76539e97df592cf5c (diff) | |
download | FreeBSD-src-7f685c218aab7dcffad6119b6e3741a0b71a2e97.zip FreeBSD-src-7f685c218aab7dcffad6119b6e3741a0b71a2e97.tar.gz |
Xen netback driver rewrite.
share/man/man4/Makefile,
share/man/man4/xnb.4,
sys/dev/xen/netback/netback.c,
sys/dev/xen/netback/netback_unit_tests.c:
Rewrote the netback driver for xen to attach properly via newbus
and work properly in both HVM and PVM mode (only HVM is tested).
Works with the in-tree FreeBSD netfront driver or the Windows
netfront driver from SuSE. Has not been extensively tested with
a Linux netfront driver. Does not implement LRO, TSO, or
polling. Includes unit tests that may be run through sysctl
after compiling with XNB_DEBUG defined.
sys/dev/xen/blkback/blkback.c,
sys/xen/interface/io/netif.h:
Comment elaboration.
sys/kern/uipc_mbuf.c:
Fix page fault in kernel mode when calling m_print() on a
null mbuf. Since m_print() is only used for debugging, there
are no performance concerns for extra error checking code.
sys/kern/subr_scanf.c:
Add the "hh" and "ll" width specifiers from C99 to scanf().
A few callers were already using "ll" even though scanf()
was handling it as "l".
Submitted by: Alan Somers <alans@spectralogic.com>
Submitted by: John Suykerbuyk <johns@spectralogic.com>
Sponsored by: Spectra Logic
MFC after: 1 week
Reviewed by: ken
Diffstat (limited to 'share/man/man4/xnb.4')
-rw-r--r-- | share/man/man4/xnb.4 | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/share/man/man4/xnb.4 b/share/man/man4/xnb.4 new file mode 100644 index 0000000..f2d8f8a --- /dev/null +++ b/share/man/man4/xnb.4 @@ -0,0 +1,134 @@ +.\" Copyright (c) 2012 Spectra Logic Corporation +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.\" Authors: Alan Somers (Spectra Logic Corporation) +.\" +.\" $FreeBSD$ +.\" + +.Dd January 6, 2012 +.Dt XNB 4 +.Os +.Sh NAME +.Nm xnb +.Nd "Xen Paravirtualized Backend 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 "options XENHVM" +.Cd "device xenpci" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides the back half of a paravirtualized +.Xr xen 4 +network connection. The netback and netfront drivers appear to their +respective operating systems as Ethernet devices linked by a crossover cable. +Typically, +.Nm +will run on Domain 0 and the netfront driver will run on a guest domain. +However, it is also possible to run +.Nm +on a guest domain. It may be bridged or routed to provide the netfront's +domain access to other guest domains or to a physical network. +.Pp +In most respects, the +.Nm +device appears to the OS as an other Ethernet device. It can be configured at +runtime entirely with +.Xr ifconfig 8 +\&. In particular, it supports MAC changing, arbitrary MTU sizes, checksum +offload for IP, UDP, and TCP for both receive and transmit, and TSO. However, +see +.Sx CAVEATS +before enabling txcsum, rxcsum, or tso. +.Sh SYSCTL VARIABLES +The following read-only variables are available via +.Xr sysctl 8 : +.Bl -tag -width indent +.It Va dev.xnb.%d.dump_rings +Displays information about the ring buffers used to pass requests between the +netfront and netback. Mostly useful for debugging, but can also be used to +get traffic statistics. +.It Va dev.xnb.%d.unit_test_results +Runs a builtin suite of unit tests and displays the results. Does not affect +the operation of the driver in any way. Note that the test suite simulates +error conditions; this will result in error messages being printed to the +system system log. +.Sh CAVEATS +Packets sent through Xennet pass over shared memory, so the protocol includes +no form of link-layer checksum or CRC. Furthermore, Xennet drivers always +report to their hosts that they support receive and transmit checksum +offloading. They "offload" the checksum calculation by simply skipping it. +That works fine for packets that are exchanged between two domains on the same +machine. However, when a Xennet interface is bridged to a physical interface, +a correct checksum must be attached to any packets bound for that physical +interface. Currently, FreeBSD lacks any mechanism for an ethernet device to +inform the OS that newly received packets are valid even though their checksums +are not. So if the netfront driver is configured to offload checksum +calculations, it will pass non-checksumed packets to +.Nm +, which must then calculate the checksum in software before passing the packet +to the OS. +.Pp +For this reason, it is recommended that if +.Nm +is bridged to a physcal interface, then transmit checksum offloading should be +disabled on the netfront. The Xennet protocol does not have any mechanism for +the netback to request the netfront to do this; the operator must do it +manually. +.Sh SEE ALSO +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 , +.Xr xen 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 +. +.Sh AUTHORS +The +.Nm +driver was written by +.An Alan Somers +.Aq alans@spectralogic.com +and +.An John Suykerbuyk +.Aq johns@spectralogic.com +.Sh BUGS +The +.Nm +driver does not properly checksum UDP datagrams that span more than one +Ethernet frame. Nor does it correctly checksum IPv6 packets. To workaround +that bug, disable transmit checksum offloading on the netfront driver. |