.\" -*- nroff -*- .\" -*- nroff -*- .\" ovs.tmac .\" .\" Open vSwitch troff macro library . . .\" Continuation line for .IP. .de IQ . br . ns . IP "\\$1" .. . .\" Introduces a sub-subsection .de ST . PP . RS -0.15in . I "\\$1" . RE .. . .\" The content between the lines below is from an-ext.tmac in groff .\" 1.21, with some modifications. .\" ---------------------------------------------------------------------- .\" an-ext.tmac .\" .\" Written by Eric S. Raymond .\" Werner Lemberg .\" .\" Version 2007-Feb-02 .\" .\" Copyright (C) 2007, 2009, 2011 Free Software Foundation, Inc. .\" You may freely use, modify and/or distribute this file. .\" .\" .\" The code below provides extension macros for the `man' macro package. .\" Care has been taken to make the code portable; groff extensions are .\" properly hidden so that all troff implementations can use it without .\" changes. .\" .\" With groff, this file is sourced by the `man' macro package itself. .\" Man page authors who are concerned about portability might add the .\" used macros directly to the prologue of the man page(s). . . .\" Convention: Auxiliary macros and registers start with `m' followed .\" by an uppercase letter or digit. . . .\" Declare start of command synopsis. Sets up hanging indentation. .de SY . ie !\\n(mS \{\ . nh . nr mS 1 . nr mA \\n(.j . ad l . nr mI \\n(.i . \} . el \{\ . br . ns . \} . . HP \w'\fB\\$1\fP\ 'u . B "\\$1" .. . . .\" End of command synopsis. Restores adjustment. .de YS . in \\n(mIu . ad \\n(mA . hy \\n(HY . nr mS 0 .. . . .\" Declare optional option. .de OP . ie \\n(.$-1 \ . RI "[\fB\\$1\fP" "\ \\$2" "]" . el \ . RB "[" "\\$1" "]" .. . . .\" Start URL. .de UR . ds m1 \\$1\" . nh . if \\n(mH \{\ . \" Start diversion in a new environment. . do ev URL-div . do di URL-div . \} .. . . .\" End URL. .de UE . ie \\n(mH \{\ . br . di . ev . . \" Has there been one or more input lines for the link text? . ie \\n(dn \{\ . do HTML-NS "" . \" Yes, strip off final newline of diversion and emit it. . do chop URL-div . do URL-div \c . do HTML-NS . \} . el \ . do HTML-NS "\\*(m1" \&\\$*\" . \} . el \ \\*(la\\*(m1\\*(ra\\$*\" . . hy \\n(HY .. . . .\" Start email address. .de MT . ds m1 \\$1\" . nh . if \\n(mH \{\ . \" Start diversion in a new environment. . do ev URL-div . do di URL-div . \} .. . . .\" End email address. .de ME . ie \\n(mH \{\ . br . di . ev . . \" Has there been one or more input lines for the link text? . ie \\n(dn \{\ . do HTML-NS "" . \" Yes, strip off final newline of diversion and emit it. . do chop URL-div . do URL-div \c . do HTML-NS . \} . el \ . do HTML-NS "\\*(m1" \&\\$*\" . \} . el \ \\*(la\\*(m1\\*(ra\\$*\" . . hy \\n(HY .. . . .\" Continuation line for .TP header. .de TQ . br . ns . TP \\$1\" no doublequotes around argument! .. . . .\" Start example. .de EX . nr mE \\n(.f . nf . nh . ft CW .. . . .\" End example. .de EE . ft \\n(mE . fi . hy \\n(HY .. . .\" EOF .\" ---------------------------------------------------------------------- .TH ovs\-vlan\-bug\-workaround 8 "2.11.2" "Open vSwitch" "Open vSwitch Manual" .ds PN ovs\-vlan\-bug\-workaround . .SH NAME ovs\-vlan\-bug\-workaround \- utility for configuring Linux VLAN driver bug workaround . .SH SYNOPSIS \fBovs\-vlan\-bug\-workaround \fInetdev\fR \fBon\fR .br \fBovs\-vlan\-bug\-workaround \fInetdev\fR \fBoff\fR .br \fBovs\-vlan\-bug\-workaround \-\-help .br \fBovs\-vlan\-bug\-workaround \-\-version .SH DESCRIPTION . .PP Some Linux network drivers support a feature called ``VLAN acceleration''. VLAN acceleration is associated with a data structure called a \fBvlan_group\fR that is, abstractly, a dictionary that maps from a VLAN ID (in the range 0 to 4095) to a VLAN device, that is, a Linux network device associated with a particular VLAN, e.g. \fBeth0.9\fR for VLAN 9 on \fBeth0\fR. .PP Some drivers that support VLAN acceleration have bugs that fall roughly into the categories listed below. \fBovs\-vlan\-test\fR(8) can test for these driver bugs. .IP \(bu When NICs use VLAN stripping on receive they must pass a pointer to a \fBvlan_group\fR when reporting the stripped tag to the networking core. If no \fBvlan_group\fR is in use then some drivers just drop the extracted tag. Drivers are supposed to only enable stripping if a \fBvlan_group\fR is registered but not all of them do that. . .IP \(bu On receive, some drivers handle priority tagged packets specially and don't pass the tag onto the network stack at all, so Open vSwitch never has a chance to see it. . .IP \(bu Some drivers size their receive buffers based on whether a \fBvlan_group\fR is enabled, meaning that a maximum size packet with a VLAN tag will not fit if no \fBvlan_group\fR is configured. . .IP \(bu On transmit, some drivers expect that VLAN acceleration will be used if it is available, which can only be done if a \fBvlan_group\fR is configured. In these cases, the driver may fail to parse the packet and correctly setup checksum offloading or TSO. .PP .PP The correct long term solution is to fix these driver bugs. .PP For now, \fBovs\-vlan\-bug\-workaround\fR can enable a special-purpose workaround for devices with buggy VLAN acceleration. A kernel patch must be applied for this workaround to work. .PP Use the command \fBovs\-vlan\-bug\-workaround \fInetdev\fR \fBon\fR to enable the VLAN driver bug workaround for network device \fInetdev\fR. Use the command \fBovs\-vlan\-bug\-workaround \fInetdev\fR \fBoff\fR to disable the VLAN driver bug workaround for network device \fInetdev\fR. .SH "DRIVER DETAILS" .PP The following drivers in Linux version 2.6.32.12-0.7.1.xs1.0.0.311.170586 implement VLAN acceleration and are relevant to Open vSwitch on XenServer. We have not tested any version of most of these drivers, so we do not know whether they have a VLAN problem that needs to be fixed. The drivers are listed by the name that they report in, e.g., \fBethtool \-i\fR output; in a few cases this differs slightly from the name of the module's \fB.ko\fR file: . .nf .ta T 1i \fB8139cp acenic amd8111e atl1c ATL1E atl1 atl2 be2net bna bnx2 bnx2x cnic cxgb cxgb3 e1000 e1000e enic forcedeth igb igbvf ixgb ixgbe jme ml4x_core ns83820 qlge r8169 S2IO sky2 starfire tehuti tg3 typhoon via-velocity vxge .fi .PP The following drivers use \fBvlan_group\fR but are irrelevant to Open vSwitch on XenServer: .IP "\fBbonding\fR" Not used with Open vSwitch on XenServer. .IP "\fBgianfar\fR" Not shipped with XenServer. A FreeScale CPU-integrated device. .IP "\fBehea\fR" Cannot be built on x86. IBM Power architecture only. .IP "\fBstmmac\fR" Cannot be built on x86. SH4 architecture only. .IP "\fBvmxnet3\fR" Not shipped with XenServer. For use inside VMware VMs only. . .SH OPTIONS . .IP "\fB\-h\fR" .IQ "\fB\-\-help\fR" Prints a brief help message to the console. . .IP "\fB\-V\fR" .IQ "\fB\-\-version\fR" Prints version information to the console. . .SH BUGS . Obviously. . .SH "SEE ALSO" . .BR ovs\-vlan\-test (8).