sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget(/translations/zh_CN/networking/switchdevmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_TW/networking/switchdevmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/it_IT/networking/switchdevmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ja_JP/networking/switchdevmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ko_KR/networking/switchdevmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/sp_SP/networking/switchdevmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhB/var/lib/git/docbuild/linux/Documentation/networking/switchdev.rsthKubh)}(h4This data file has been placed in the public domain.h]h4This data file has been placed in the public domain.}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhho/srv/docbuild/lib/venvs/build-kernel-docs/lib64/python3.9/site-packages/docutils/parsers/rst/include/isonum.txthKubh)}(hDerived from the Unicode character mappings available from . Processed by unicode2rstsubs.py, part of Docutils: .h]hDerived from the Unicode character mappings available from . Processed by unicode2rstsubs.py, part of Docutils: .}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhKubhsubstitution_definition)}(h*.. |amp| unicode:: U+00026 .. AMPERSANDh]h&}hhsbah}(h]h ]h"]ampah$]h&]uh1hhhhKhhhhubh)}(h+.. |apos| unicode:: U+00027 .. APOSTROPHEh]h'}hhsbah}(h]h ]h"]aposah$]h&]uh1hhhhKhhhhubh)}(h).. |ast| unicode:: U+0002A .. ASTERISKh]h*}hhsbah}(h]h ]h"]astah$]h&]uh1hhhhK hhhhubh)}(h+.. |brvbar| unicode:: U+000A6 .. BROKEN BARh]h¦}hjsbah}(h]h ]h"]brvbarah$]h&]uh1hhhhK hhhhubh)}(h0.. |bsol| unicode:: U+0005C .. REVERSE SOLIDUSh]h\}hjsbah}(h]h ]h"]bsolah$]h&]uh1hhhhK hhhhubh)}(h*.. |cent| unicode:: U+000A2 .. CENT SIGNh]h¢}hjsbah}(h]h ]h"]centah$]h&]uh1hhhhK hhhhubh)}(h&.. |colon| unicode:: U+0003A .. COLONh]h:}hj-sbah}(h]h ]h"]colonah$]h&]uh1hhhhK hhhhubh)}(h&.. |comma| unicode:: U+0002C .. COMMAh]h,}hj<sbah}(h]h ]h"]commaah$]h&]uh1hhhhKhhhhubh)}(h... |commat| unicode:: U+00040 .. COMMERCIAL ATh]h@}hjKsbah}(h]h ]h"]commatah$]h&]uh1hhhhKhhhhubh)}(h/.. |copy| unicode:: U+000A9 .. COPYRIGHT SIGNh]h©}hjZsbah}(h]h ]h"]copyah$]h&]uh1hhhhKhhhhubh)}(h... |curren| unicode:: U+000A4 .. CURRENCY SIGNh]h¤}hjisbah}(h]h ]h"]currenah$]h&]uh1hhhhKhhhhubh)}(h0.. |darr| unicode:: U+02193 .. DOWNWARDS ARROWh]h↓}hjxsbah}(h]h ]h"]darrah$]h&]uh1hhhhKhhhhubh)}(h,.. |deg| unicode:: U+000B0 .. DEGREE SIGNh]h°}hjsbah}(h]h ]h"]degah$]h&]uh1hhhhKhhhhubh)}(h... |divide| unicode:: U+000F7 .. DIVISION SIGNh]h÷}hjsbah}(h]h ]h"]divideah$]h&]uh1hhhhKhhhhubh)}(h,.. |dollar| unicode:: U+00024 .. DOLLAR SIGNh]h$}hjsbah}(h]h ]h"]dollarah$]h&]uh1hhhhKhhhhubh)}(h,.. |equals| unicode:: U+0003D .. EQUALS SIGNh]h=}hjsbah}(h]h ]h"]equalsah$]h&]uh1hhhhKhhhhubh)}(h1.. |excl| unicode:: U+00021 .. EXCLAMATION MARKh]h!}hjsbah}(h]h ]h"]exclah$]h&]uh1hhhhKhhhhubh)}(h9.. |frac12| unicode:: U+000BD .. VULGAR FRACTION ONE HALFh]h½}hjsbah}(h]h ]h"]frac12ah$]h&]uh1hhhhKhhhhubh)}(h<.. |frac14| unicode:: U+000BC .. VULGAR FRACTION ONE QUARTERh]h¼}hjsbah}(h]h ]h"]frac14ah$]h&]uh1hhhhKhhhhubh)}(h;.. |frac18| unicode:: U+0215B .. VULGAR FRACTION ONE EIGHTHh]h⅛}hjsbah}(h]h ]h"]frac18ah$]h&]uh1hhhhKhhhhubh)}(h?.. |frac34| unicode:: U+000BE .. VULGAR FRACTION THREE QUARTERSh]h¾}hjsbah}(h]h ]h"]frac34ah$]h&]uh1hhhhKhhhhubh)}(h>.. |frac38| unicode:: U+0215C .. VULGAR FRACTION THREE EIGHTHSh]h⅜}hjsbah}(h]h ]h"]frac38ah$]h&]uh1hhhhKhhhhubh)}(h=.. |frac58| unicode:: U+0215D .. VULGAR FRACTION FIVE EIGHTHSh]h⅝}hjsbah}(h]h ]h"]frac58ah$]h&]uh1hhhhKhhhhubh)}(h>.. |frac78| unicode:: U+0215E .. VULGAR FRACTION SEVEN EIGHTHSh]h⅞}hj,sbah}(h]h ]h"]frac78ah$]h&]uh1hhhhKhhhhubh)}(h2.. |gt| unicode:: U+0003E .. GREATER-THAN SIGNh]h>}hj;sbah}(h]h ]h"]gtah$]h&]uh1hhhhKhhhhubh)}(h9.. |half| unicode:: U+000BD .. VULGAR FRACTION ONE HALFh]h½}hjJsbah}(h]h ]h"]halfah$]h&]uh1hhhhK hhhhubh)}(h/.. |horbar| unicode:: U+02015 .. HORIZONTAL BARh]h―}hjYsbah}(h]h ]h"]horbarah$]h&]uh1hhhhK!hhhhubh)}(h'.. |hyphen| unicode:: U+02010 .. HYPHENh]h‐}hjhsbah}(h]h ]h"]hyphenah$]h&]uh1hhhhK"hhhhubh)}(h:.. |iexcl| unicode:: U+000A1 .. INVERTED EXCLAMATION MARKh]h¡}hjwsbah}(h]h ]h"]iexclah$]h&]uh1hhhhK#hhhhubh)}(h7.. |iquest| unicode:: U+000BF .. INVERTED QUESTION MARKh]h¿}hjsbah}(h]h ]h"]iquestah$]h&]uh1hhhhK$hhhhubh)}(hJ.. |laquo| unicode:: U+000AB .. LEFT-POINTING DOUBLE ANGLE QUOTATION MARKh]h«}hjsbah}(h]h ]h"]laquoah$]h&]uh1hhhhK%hhhhubh)}(h0.. |larr| unicode:: U+02190 .. LEFTWARDS ARROWh]h←}hjsbah}(h]h ]h"]larrah$]h&]uh1hhhhK&hhhhubh)}(h3.. |lcub| unicode:: U+0007B .. LEFT CURLY BRACKETh]h{}hjsbah}(h]h ]h"]lcubah$]h&]uh1hhhhK'hhhhubh)}(h;.. |ldquo| unicode:: U+0201C .. LEFT DOUBLE QUOTATION MARKh]h“}hjsbah}(h]h ]h"]ldquoah$]h&]uh1hhhhK(hhhhubh)}(h).. |lowbar| unicode:: U+0005F .. LOW LINEh]h_}hjsbah}(h]h ]h"]lowbarah$]h&]uh1hhhhK)hhhhubh)}(h1.. |lpar| unicode:: U+00028 .. LEFT PARENTHESISh]h(}hjsbah}(h]h ]h"]lparah$]h&]uh1hhhhK*hhhhubh)}(h4.. |lsqb| unicode:: U+0005B .. LEFT SQUARE BRACKETh]h[}hjsbah}(h]h ]h"]lsqbah$]h&]uh1hhhhK+hhhhubh)}(h;.. |lsquo| unicode:: U+02018 .. LEFT SINGLE QUOTATION MARKh]h‘}hjsbah}(h]h ]h"]lsquoah$]h&]uh1hhhhK,hhhhubh)}(h/.. |lt| unicode:: U+0003C .. LESS-THAN SIGNh]h<}hj sbah}(h]h ]h"]ltah$]h&]uh1hhhhK-hhhhubh)}(h+.. |micro| unicode:: U+000B5 .. MICRO SIGNh]hµ}hjsbah}(h]h ]h"]microah$]h&]uh1hhhhK.hhhhubh)}(h+.. |middot| unicode:: U+000B7 .. MIDDLE DOTh]h·}hj+sbah}(h]h ]h"]middotah$]h&]uh1hhhhK/hhhhubh)}(h/.. |nbsp| unicode:: U+000A0 .. NO-BREAK SPACEh]h }hj:sbah}(h]h ]h"]nbspah$]h&]uh1hhhhK0hhhhubh)}(h).. |not| unicode:: U+000AC .. NOT SIGNh]h¬}hjIsbah}(h]h ]h"]notah$]h&]uh1hhhhK1hhhhubh)}(h,.. |num| unicode:: U+00023 .. NUMBER SIGNh]h#}hjXsbah}(h]h ]h"]numah$]h&]uh1hhhhK2hhhhubh)}(h).. |ohm| unicode:: U+02126 .. OHM SIGNh]hΩ}hjgsbah}(h]h ]h"]ohmah$]h&]uh1hhhhK3hhhhubh)}(h;.. |ordf| unicode:: U+000AA .. FEMININE ORDINAL INDICATORh]hª}hjvsbah}(h]h ]h"]ordfah$]h&]uh1hhhhK4hhhhubh)}(h<.. |ordm| unicode:: U+000BA .. MASCULINE ORDINAL INDICATORh]hº}hjsbah}(h]h ]h"]ordmah$]h&]uh1hhhhK5hhhhubh)}(h-.. |para| unicode:: U+000B6 .. PILCROW SIGNh]h¶}hjsbah}(h]h ]h"]paraah$]h&]uh1hhhhK6hhhhubh)}(h-.. |percnt| unicode:: U+00025 .. PERCENT SIGNh]h%}hjsbah}(h]h ]h"]percntah$]h&]uh1hhhhK7hhhhubh)}(h*.. |period| unicode:: U+0002E .. FULL STOPh]h.}hjsbah}(h]h ]h"]periodah$]h&]uh1hhhhK8hhhhubh)}(h*.. |plus| unicode:: U+0002B .. PLUS SIGNh]h+}hjsbah}(h]h ]h"]plusah$]h&]uh1hhhhK9hhhhubh)}(h0.. |plusmn| unicode:: U+000B1 .. PLUS-MINUS SIGNh]h±}hjsbah}(h]h ]h"]plusmnah$]h&]uh1hhhhK:hhhhubh)}(h+.. |pound| unicode:: U+000A3 .. POUND SIGNh]h£}hjsbah}(h]h ]h"]poundah$]h&]uh1hhhhK;hhhhubh)}(h... |quest| unicode:: U+0003F .. QUESTION MARKh]h?}hjsbah}(h]h ]h"]questah$]h&]uh1hhhhKhhhhubh)}(h1.. |rarr| unicode:: U+02192 .. RIGHTWARDS ARROWh]h→}hjsbah}(h]h ]h"]rarrah$]h&]uh1hhhhK?hhhhubh)}(h4.. |rcub| unicode:: U+0007D .. RIGHT CURLY BRACKETh]h}}hj*sbah}(h]h ]h"]rcubah$]h&]uh1hhhhK@hhhhubh)}(h<.. |rdquo| unicode:: U+0201D .. RIGHT DOUBLE QUOTATION MARKh]h”}hj9sbah}(h]h ]h"]rdquoah$]h&]uh1hhhhKAhhhhubh)}(h0.. |reg| unicode:: U+000AE .. REGISTERED SIGNh]h®}hjHsbah}(h]h ]h"]regah$]h&]uh1hhhhKBhhhhubh)}(h2.. |rpar| unicode:: U+00029 .. RIGHT PARENTHESISh]h)}hjWsbah}(h]h ]h"]rparah$]h&]uh1hhhhKChhhhubh)}(h5.. |rsqb| unicode:: U+0005D .. RIGHT SQUARE BRACKETh]h]}hjfsbah}(h]h ]h"]rsqbah$]h&]uh1hhhhKDhhhhubh)}(h<.. |rsquo| unicode:: U+02019 .. RIGHT SINGLE QUOTATION MARKh]h’}hjusbah}(h]h ]h"]rsquoah$]h&]uh1hhhhKEhhhhubh)}(h-.. |sect| unicode:: U+000A7 .. SECTION SIGNh]h§}hjsbah}(h]h ]h"]sectah$]h&]uh1hhhhKFhhhhubh)}(h*.. |semi| unicode:: U+0003B .. SEMICOLONh]h;}hjsbah}(h]h ]h"]semiah$]h&]uh1hhhhKGhhhhubh)}(h,.. |shy| unicode:: U+000AD .. SOFT HYPHENh]h­}hjsbah}(h]h ]h"]shyah$]h&]uh1hhhhKHhhhhubh)}(h(.. |sol| unicode:: U+0002F .. SOLIDUSh]h/}hjsbah}(h]h ]h"]solah$]h&]uh1hhhhKIhhhhubh)}(h,.. |sung| unicode:: U+0266A .. EIGHTH NOTEh]h♪}hjsbah}(h]h ]h"]sungah$]h&]uh1hhhhKJhhhhubh)}(h0.. |sup1| unicode:: U+000B9 .. SUPERSCRIPT ONEh]h¹}hjsbah}(h]h ]h"]sup1ah$]h&]uh1hhhhKKhhhhubh)}(h0.. |sup2| unicode:: U+000B2 .. SUPERSCRIPT TWOh]h²}hjsbah}(h]h ]h"]sup2ah$]h&]uh1hhhhKLhhhhubh)}(h2.. |sup3| unicode:: U+000B3 .. SUPERSCRIPT THREEh]h³}hjsbah}(h]h ]h"]sup3ah$]h&]uh1hhhhKMhhhhubh)}(h4.. |times| unicode:: U+000D7 .. MULTIPLICATION SIGNh]h×}hjsbah}(h]h ]h"]timesah$]h&]uh1hhhhKNhhhhubh)}(h0.. |trade| unicode:: U+02122 .. TRADE MARK SIGNh]h™}hj sbah}(h]h ]h"]tradeah$]h&]uh1hhhhKOhhhhubh)}(h... |uarr| unicode:: U+02191 .. UPWARDS ARROWh]h↑}hjsbah}(h]h ]h"]uarrah$]h&]uh1hhhhKPhhhhubh)}(h... |verbar| unicode:: U+0007C .. VERTICAL LINEh]h|}hj)sbah}(h]h ]h"]verbarah$]h&]uh1hhhhKQhhhhubh)}(h*.. |yen| unicode:: U+000A5 .. YEN SIGN h]h¥}hj8sbah}(h]h ]h"]yenah$]h&]uh1hhhhKRhhhhubhtarget)}(h.. _switchdev:h]h}(h]h ]h"]h$]h&]refid switchdevuh1jGhKYhhhhhhubhsection)}(hhh](htitle)}(h/Ethernet switch device driver model (switchdev)h]h/Ethernet switch device driver model (switchdev)}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjWhhhhhKubh paragraph)}(h3Copyright |copy| 2014 Jiri Pirko h](h Copyright }(hjlhhhNhNubh©}(hjlhhhNhNubh 2014 Jiri Pirko <}(hjlhhhNhNubh reference)}(hjiri@resnulli.ush]hjiri@resnulli.us}(hj~hhhNhNubah}(h]h ]h"]h$]h&]refurimailto:jiri@resnulli.usuh1j|hjlubh>}(hjlhhhNhNubeh}(h]h ]h"]h$]h&]uh1jjhhhK hjWhhubjk)}(hh](h Copyright }(hjhhhNhNubh©}(hjhhhNhNubh 2014-2015 Scott Feldman <}(hjhhhNhNubj})}(hsfeldma@gmail.comh]hsfeldma@gmail.com}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurimailto:sfeldma@gmail.comuh1j|hjubh>}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jjhhhK hjWhhubjk)}(hThe Ethernet switch device driver model (switchdev) is an in-kernel driver model for switch devices which offload the forwarding (data) plane from the kernel.h]hThe Ethernet switch device driver model (switchdev) is an in-kernel driver model for switch devices which offload the forwarding (data) plane from the kernel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjWhhubjk)}(hFigure 1 is a block diagram showing the components of the switchdev model for an example setup using a data-center-class switch ASIC chip. Other setups with SR-IOV or soft switches, such as OVS, are possible.h]hFigure 1 is a block diagram showing the components of the switchdev model for an example setup using a data-center-class switch ASIC chip. Other setups with SR-IOV or soft switches, such as OVS, are possible.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjWhhubh literal_block)}(hX User-space tools user space | +-------------------------------------------------------------------+ kernel | Netlink | +--------------+-------------------------------+ | Network stack | | (Linux) | | | +----------------------------------------------+ sw1p2 sw1p4 sw1p6 sw1p1 + sw1p3 + sw1p5 + eth1 + | + | + | + | | | | | | | +--+----+----+----+----+----+---+ +-----+-----+ | Switch driver | | mgmt | | (this document) | | driver | | | | | +--------------+----------------+ +-----------+ | kernel | HW bus (eg PCI) +-------------------------------------------------------------------+ hardware | +--------------+----------------+ | Switch device (sw1) | | +----+ +--------+ | | v offloaded data path | mgmt port | | | | +--|----|----+----+----+----+---+ | | | | | | + + + + + + p1 p2 p3 p4 p5 p6 front-panel ports Fig 1.h]hX User-space tools user space | +-------------------------------------------------------------------+ kernel | Netlink | +--------------+-------------------------------+ | Network stack | | (Linux) | | | +----------------------------------------------+ sw1p2 sw1p4 sw1p6 sw1p1 + sw1p3 + sw1p5 + eth1 + | + | + | + | | | | | | | +--+----+----+----+----+----+---+ +-----+-----+ | Switch driver | | mgmt | | (this document) | | driver | | | | | +--------------+----------------+ +-----------+ | kernel | HW bus (eg PCI) +-------------------------------------------------------------------+ hardware | +--------------+----------------+ | Switch device (sw1) | | +----+ +--------+ | | v offloaded data path | mgmt port | | | | +--|----|----+----+----+----+---+ | | | | | | + + + + + + p1 p2 p3 p4 p5 p6 front-panel ports Fig 1.}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjWhhubjV)}(hhh](j[)}(h Include Filesh]h Include Files}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjhhhhhKCubj)}(h7#include #include h]h7#include #include }hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKGhjhhubeh}(h] include-filesah ]h"] include filesah$]h&]uh1jUhjWhhhhhKCubjV)}(hhh](j[)}(h Configurationh]h Configuration}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjhhhhhKLubjk)}(hfUse "depends NET_SWITCHDEV" in driver's Kconfig to ensure switchdev model support is built for driver.h]hlUse “depends NET_SWITCHDEV” in driver’s Kconfig to ensure switchdev model support is built for driver.}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKNhjhhubeh}(h] configurationah ]h"] configurationah$]h&]uh1jUhjWhhhhhKLubjV)}(hhh](j[)}(h Switch Portsh]h Switch Ports}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj<hhhhhKSubjk)}(hXOn switchdev driver initialization, the driver will allocate and register a struct net_device (using register_netdev()) for each enumerated physical switch port, called the port netdev. A port netdev is the software representation of the physical port and provides a conduit for control traffic to/from the controller (the kernel) and the network, as well as an anchor point for higher level constructs such as bridges, bonds, VLANs, tunnels, and L3 routers. Using standard netdev tools (iproute2, ethtool, etc), the port netdev can also provide to the user access to the physical properties of the switch port such as PHY link state and I/O statistics.h]hXOn switchdev driver initialization, the driver will allocate and register a struct net_device (using register_netdev()) for each enumerated physical switch port, called the port netdev. A port netdev is the software representation of the physical port and provides a conduit for control traffic to/from the controller (the kernel) and the network, as well as an anchor point for higher level constructs such as bridges, bonds, VLANs, tunnels, and L3 routers. Using standard netdev tools (iproute2, ethtool, etc), the port netdev can also provide to the user access to the physical properties of the switch port such as PHY link state and I/O statistics.}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKUhj<hhubjk)}(hThere is (currently) no higher-level kernel object for the switch beyond the port netdevs. All of the switchdev driver ops are netdev ops or switchdev ops.h]hThere is (currently) no higher-level kernel object for the switch beyond the port netdevs. All of the switchdev driver ops are netdev ops or switchdev ops.}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhK_hj<hhubjk)}(hA switch management port is outside the scope of the switchdev driver model. Typically, the management port is not participating in offloaded data plane and is loaded with a different driver, such as a NIC driver, on the management port device.h]hA switch management port is outside the scope of the switchdev driver model. Typically, the management port is not participating in offloaded data plane and is loaded with a different driver, such as a NIC driver, on the management port device.}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKbhj<hhubjV)}(hhh](j[)}(h Switch IDh]h Switch ID}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjwhhhhhKhubjk)}(hX'The switchdev driver must implement the net_device operation ndo_get_port_parent_id for each port netdev, returning the same physical ID for each port of a switch. The ID must be unique between switches on the same system. The ID does not need to be unique between switches on different systems.h]hX'The switchdev driver must implement the net_device operation ndo_get_port_parent_id for each port netdev, returning the same physical ID for each port of a switch. The ID must be unique between switches on the same system. The ID does not need to be unique between switches on different systems.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKjhjwhhubjk)}(hlThe switch ID is used to locate ports on a switch and to know if aggregated ports belong to the same switch.h]hlThe switch ID is used to locate ports on a switch and to know if aggregated ports belong to the same switch.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKphjwhhubeh}(h] switch-idah ]h"] switch idah$]h&]uh1jUhj<hhhhhKhubjV)}(hhh](j[)}(hPort Netdev Namingh]hPort Netdev Naming}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjhhhhhKtubjk)}(hXHUdev rules should be used for port netdev naming, using some unique attribute of the port as a key, for example the port MAC address or the port PHYS name. Hard-coding of kernel netdev names within the driver is discouraged; let the kernel pick the default netdev name, and let udev set the final name based on a port attribute.h]hXHUdev rules should be used for port netdev naming, using some unique attribute of the port as a key, for example the port MAC address or the port PHYS name. Hard-coding of kernel netdev names within the driver is discouraged; let the kernel pick the default netdev name, and let udev set the final name based on a port attribute.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKvhjhhubjk)}(hXuUsing port PHYS name (ndo_get_phys_port_name) for the key is particularly useful for dynamically-named ports where the device names its ports based on external configuration. For example, if a physical 40G port is split logically into 4 10G ports, resulting in 4 port netdevs, the device can give a unique name for each port using port PHYS name. The udev rule would be::h]hXtUsing port PHYS name (ndo_get_phys_port_name) for the key is particularly useful for dynamically-named ports where the device names its ports based on external configuration. For example, if a physical 40G port is split logically into 4 10G ports, resulting in 4 port netdevs, the device can give a unique name for each port using port PHYS name. The udev rule would be:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhK|hjhhubj)}(hSUBSYSTEM=="net", ACTION=="add", ATTR{phys_switch_id}=="", \ ATTR{phys_port_name}!="", NAME="swX$attr{phys_port_name}"h]hSUBSYSTEM=="net", ACTION=="add", ATTR{phys_switch_id}=="", \ ATTR{phys_port_name}!="", NAME="swX$attr{phys_port_name}"}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubjk)}(hSuggested naming convention is "swXpYsZ", where X is the switch name or ID, Y is the port name or ID, and Z is the sub-port name or ID. For example, sw1p1s0 would be sub-port 0 on port 1 on switch 1.h]hSuggested naming convention is “swXpYsZ”, where X is the switch name or ID, Y is the port name or ID, and Z is the sub-port name or ID. For example, sw1p1s0 would be sub-port 0 on port 1 on switch 1.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubeh}(h]port-netdev-namingah ]h"]port netdev namingah$]h&]uh1jUhj<hhhhhKtubjV)}(hhh](j[)}(h Port Featuresh]h Port Features}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjhhhhhKubjk)}(hdev->netns_immutableh]hdev->netns_immutable}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubjk)}(hXIf the switchdev driver (and device) only supports offloading of the default network namespace (netns), the driver should set this private flag to prevent the port netdev from being moved out of the default netns. A netns-aware driver/device would not set this flag and be responsible for partitioning hardware to preserve netns containment. This means hardware cannot forward traffic from a port in one namespace to another port in another namespace.h]hXIf the switchdev driver (and device) only supports offloading of the default network namespace (netns), the driver should set this private flag to prevent the port netdev from being moved out of the default netns. A netns-aware driver/device would not set this flag and be responsible for partitioning hardware to preserve netns containment. This means hardware cannot forward traffic from a port in one namespace to another port in another namespace.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubeh}(h] port-featuresah ]h"] port featuresah$]h&]uh1jUhj<hhhhhKubjV)}(hhh](j[)}(h Port Topologyh]h Port Topology}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj2hhhhhKubjk)}(hX1The port netdevs representing the physical switch ports can be organized into higher-level switching constructs. The default construct is a standalone router port, used to offload L3 forwarding. Two or more ports can be bonded together to form a LAG. Two or more ports (or LAGs) can be bridged to bridge L2 networks. VLANs can be applied to sub-divide L2 networks. L2-over-L3 tunnels can be built on ports. These constructs are built using standard Linux tools such as the bridge driver, the bonding/team drivers, and netlink-based tools such as iproute2.h]hX1The port netdevs representing the physical switch ports can be organized into higher-level switching constructs. The default construct is a standalone router port, used to offload L3 forwarding. Two or more ports can be bonded together to form a LAG. Two or more ports (or LAGs) can be bridged to bridge L2 networks. VLANs can be applied to sub-divide L2 networks. L2-over-L3 tunnels can be built on ports. These constructs are built using standard Linux tools such as the bridge driver, the bonding/team drivers, and netlink-based tools such as iproute2.}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhj2hhubjk)}(hXThe switchdev driver can know a particular port's position in the topology by monitoring NETDEV_CHANGEUPPER notifications. For example, a port moved into a bond will see its upper master change. If that bond is moved into a bridge, the bond's upper master will change. And so on. The driver will track such movements to know what position a port is in in the overall topology by registering for netdevice events and acting on NETDEV_CHANGEUPPER.h]hXThe switchdev driver can know a particular port’s position in the topology by monitoring NETDEV_CHANGEUPPER notifications. For example, a port moved into a bond will see its upper master change. If that bond is moved into a bridge, the bond’s upper master will change. And so on. The driver will track such movements to know what position a port is in in the overall topology by registering for netdevice events and acting on NETDEV_CHANGEUPPER.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhj2hhubeh}(h] port-topologyah ]h"] port topologyah$]h&]uh1jUhj<hhhhhKubeh}(h] switch-portsah ]h"] switch portsah$]h&]uh1jUhjWhhhhhKSubjV)}(hhh](j[)}(hL2 Forwarding Offloadh]hL2 Forwarding Offload}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjohhhhhKubjk)}(hThe idea is to offload the L2 data forwarding (switching) path from the kernel to the switchdev device by mirroring bridge FDB entries down to the device. An FDB entry is the {port, MAC, VLAN} tuple forwarding destination.h]hThe idea is to offload the L2 data forwarding (switching) path from the kernel to the switchdev device by mirroring bridge FDB entries down to the device. An FDB entry is the {port, MAC, VLAN} tuple forwarding destination.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjohhubjk)}(hFTo offloading L2 bridging, the switchdev driver/device should support:h]hFTo offloading L2 bridging, the switchdev driver/device should support:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjohhubh block_quote)}(h- Static FDB entries installed on a bridge port - Notification of learned/forgotten src mac/vlans from device - STP state changes on the port - VLAN flooding of multicast/broadcast and unknown unicast packets h]h bullet_list)}(hhh](h list_item)}(h-Static FDB entries installed on a bridge porth]jk)}(hjh]h-Static FDB entries installed on a bridge port}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h;Notification of learned/forgotten src mac/vlans from deviceh]jk)}(hjh]h;Notification of learned/forgotten src mac/vlans from device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hSTP state changes on the porth]jk)}(hjh]hSTP state changes on the port}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hAVLAN flooding of multicast/broadcast and unknown unicast packets h]jk)}(h@VLAN flooding of multicast/broadcast and unknown unicast packetsh]h@VLAN flooding of multicast/broadcast and unknown unicast packets}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjohhubjV)}(hhh](j[)}(hStatic FDB Entriesh]hStatic FDB Entries}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjhhhhhKubjk)}(hA driver which implements the ``ndo_fdb_add``, ``ndo_fdb_del`` and ``ndo_fdb_dump`` operations is able to support the command below, which adds a static bridge FDB entry::h](hA driver which implements the }(hj%hhhNhNubhliteral)}(h``ndo_fdb_add``h]h ndo_fdb_add}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj%ubh, }(hj%hhhNhNubj.)}(h``ndo_fdb_del``h]h ndo_fdb_del}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj%ubh and }(hj%hhhNhNubj.)}(h``ndo_fdb_dump``h]h ndo_fdb_dump}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj%ubhW operations is able to support the command below, which adds a static bridge FDB entry:}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubj)}(h7bridge fdb add dev DEV ADDRESS [vlan VID] [self] statich]h7bridge fdb add dev DEV ADDRESS [vlan VID] [self] static}hjksbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubjk)}(h(the "static" keyword is non-optional: if not specified, the entry defaults to being "local", which means that it should not be forwarded)h]h(the “static” keyword is non-optional: if not specified, the entry defaults to being “local”, which means that it should not be forwarded)}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubjk)}(hXCThe "self" keyword (optional because it is implicit) has the role of instructing the kernel to fulfill the operation through the ``ndo_fdb_add`` implementation of the ``DEV`` device itself. If ``DEV`` is a bridge port, this will bypass the bridge and therefore leave the software database out of sync with the hardware one.h](hThe “self” keyword (optional because it is implicit) has the role of instructing the kernel to fulfill the operation through the }(hjhhhNhNubj.)}(h``ndo_fdb_add``h]h ndo_fdb_add}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjubh implementation of the }(hjhhhNhNubj.)}(h``DEV``h]hDEV}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjubh device itself. If }(hjhhhNhNubj.)}(h``DEV``h]hDEV}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjubh{ is a bridge port, this will bypass the bridge and therefore leave the software database out of sync with the hardware one.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubjk)}(h1To avoid this, the "master" keyword can be used::h]h4To avoid this, the “master” keyword can be used:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubj)}(h7bridge fdb add dev DEV ADDRESS [vlan VID] master statich]h7bridge fdb add dev DEV ADDRESS [vlan VID] master static}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubjk)}(hXThe above command instructs the kernel to search for a master interface of ``DEV`` and fulfill the operation through the ``ndo_fdb_add`` method of that. This time, the bridge generates a ``SWITCHDEV_FDB_ADD_TO_DEVICE`` notification which the port driver can handle and use it to program its hardware table. This way, the software and the hardware database will both contain this static FDB entry.h](hKThe above command instructs the kernel to search for a master interface of }(hjhhhNhNubj.)}(h``DEV``h]hDEV}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjubh' and fulfill the operation through the }(hjhhhNhNubj.)}(h``ndo_fdb_add``h]h ndo_fdb_add}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjubh3 method of that. This time, the bridge generates a }(hjhhhNhNubj.)}(h``SWITCHDEV_FDB_ADD_TO_DEVICE``h]hSWITCHDEV_FDB_ADD_TO_DEVICE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjubh notification which the port driver can handle and use it to program its hardware table. This way, the software and the hardware database will both contain this static FDB entry.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubjk)}(hXiNote: for new switchdev drivers that offload the Linux bridge, implementing the ``ndo_fdb_add`` and ``ndo_fdb_del`` bridge bypass methods is strongly discouraged: all static FDB entries should be added on a bridge port using the "master" flag. The ``ndo_fdb_dump`` is an exception and can be implemented to visualize the hardware tables, if the device does not have an interrupt for notifying the operating system of newly learned/forgotten dynamic FDB addresses. In that case, the hardware FDB might end up having entries that the software FDB does not, and implementing ``ndo_fdb_dump`` is the only way to see them.h](hPNote: for new switchdev drivers that offload the Linux bridge, implementing the }(hj+ hhhNhNubj.)}(h``ndo_fdb_add``h]h ndo_fdb_add}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj+ ubh and }(hj+ hhhNhNubj.)}(h``ndo_fdb_del``h]h ndo_fdb_del}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj+ ubh bridge bypass methods is strongly discouraged: all static FDB entries should be added on a bridge port using the “master” flag. The }(hj+ hhhNhNubj.)}(h``ndo_fdb_dump``h]h ndo_fdb_dump}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj+ ubhX4 is an exception and can be implemented to visualize the hardware tables, if the device does not have an interrupt for notifying the operating system of newly learned/forgotten dynamic FDB addresses. In that case, the hardware FDB might end up having entries that the software FDB does not, and implementing }(hj+ hhhNhNubj.)}(h``ndo_fdb_dump``h]h ndo_fdb_dump}(hji hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj+ ubh is the only way to see them.}(hj+ hhhNhNubeh}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubjk)}(hNote: by default, the bridge does not filter on VLAN and only bridges untagged traffic. To enable VLAN support, turn on VLAN filtering::h]hNote: by default, the bridge does not filter on VLAN and only bridges untagged traffic. To enable VLAN support, turn on VLAN filtering:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhjhhubj)}(h5echo 1 >/sys/class/net//bridge/vlan_filteringh]h5echo 1 >/sys/class/net//bridge/vlan_filtering}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubeh}(h]static-fdb-entriesah ]h"]static fdb entriesah$]h&]uh1jUhjohhhhhKubjV)}(hhh](j[)}(h2Notification of Learned/Forgotten Source MAC/VLANsh]h2Notification of Learned/Forgotten Source MAC/VLANs}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj hhhhhKubjk)}(hThe switch device will learn/forget source MAC address/VLAN on ingress packets and notify the switch driver of the mac/vlan/port tuples. The switch driver, in turn, will notify the bridge driver using the switchdev notifier call::h]hThe switch device will learn/forget source MAC address/VLAN on ingress packets and notify the switch driver of the mac/vlan/port tuples. The switch driver, in turn, will notify the bridge driver using the switchdev notifier call:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhj hhubj)}(h7err = call_switchdev_notifiers(val, dev, info, extack);h]h7err = call_switchdev_notifiers(val, dev, info, extack);}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhj hhubjk)}(hXOWhere val is SWITCHDEV_FDB_ADD when learning and SWITCHDEV_FDB_DEL when forgetting, and info points to a struct switchdev_notifier_fdb_info. On SWITCHDEV_FDB_ADD, the bridge driver will install the FDB entry into the bridge's FDB and mark the entry as NTF_EXT_LEARNED. The iproute2 bridge command will label these entries "offload"::h]hXTWhere val is SWITCHDEV_FDB_ADD when learning and SWITCHDEV_FDB_DEL when forgetting, and info points to a struct switchdev_notifier_fdb_info. On SWITCHDEV_FDB_ADD, the bridge driver will install the FDB entry into the bridge’s FDB and mark the entry as NTF_EXT_LEARNED. The iproute2 bridge command will label these entries “offload”:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhKhj hhubj)}(hX1$ bridge fdb 52:54:00:12:35:01 dev sw1p1 master br0 permanent 00:02:00:00:02:00 dev sw1p1 master br0 offload 00:02:00:00:02:00 dev sw1p1 self 52:54:00:12:35:02 dev sw1p2 master br0 permanent 00:02:00:00:03:00 dev sw1p2 master br0 offload 00:02:00:00:03:00 dev sw1p2 self 33:33:00:00:00:01 dev eth0 self permanent 01:00:5e:00:00:01 dev eth0 self permanent 33:33:ff:00:00:00 dev eth0 self permanent 01:80:c2:00:00:0e dev eth0 self permanent 33:33:00:00:00:01 dev br0 self permanent 01:00:5e:00:00:01 dev br0 self permanent 33:33:ff:12:35:01 dev br0 self permanenth]hX1$ bridge fdb 52:54:00:12:35:01 dev sw1p1 master br0 permanent 00:02:00:00:02:00 dev sw1p1 master br0 offload 00:02:00:00:02:00 dev sw1p1 self 52:54:00:12:35:02 dev sw1p2 master br0 permanent 00:02:00:00:03:00 dev sw1p2 master br0 offload 00:02:00:00:03:00 dev sw1p2 self 33:33:00:00:00:01 dev eth0 self permanent 01:00:5e:00:00:01 dev eth0 self permanent 33:33:ff:00:00:00 dev eth0 self permanent 01:80:c2:00:00:0e dev eth0 self permanent 33:33:00:00:00:01 dev br0 self permanent 01:00:5e:00:00:01 dev br0 self permanent 33:33:ff:12:35:01 dev br0 self permanent}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhj hhubjk)}(hPLearning on the port should be disabled on the bridge using the bridge command::h]hOLearning on the port should be disabled on the bridge using the bridge command:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubj)}(h$bridge link set dev DEV learning offh]h$bridge link set dev DEV learning off}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubjk)}(hILearning on the device port should be enabled, as well as learning_sync::h]hHLearning on the device port should be enabled, as well as learning_sync:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubj)}(hVbridge link set dev DEV learning on self bridge link set dev DEV learning_sync on selfh]hVbridge link set dev DEV learning on self bridge link set dev DEV learning_sync on self}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubjk)}(hLearning_sync attribute enables syncing of the learned/forgotten FDB entry to the bridge's FDB. It's possible, but not optimal, to enable learning on the device port and on the bridge port, and disable learning_sync.h]hLearning_sync attribute enables syncing of the learned/forgotten FDB entry to the bridge’s FDB. It’s possible, but not optimal, to enable learning on the device port and on the bridge port, and disable learning_sync.}(hj& hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM hj hhubjk)}(h~To support learning, the driver implements switchdev op switchdev_port_attr_set for SWITCHDEV_ATTR_PORT_ID_{PRE}_BRIDGE_FLAGS.h]h~To support learning, the driver implements switchdev op switchdev_port_attr_set for SWITCHDEV_ATTR_PORT_ID_{PRE}_BRIDGE_FLAGS.}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM hj hhubeh}(h]2notification-of-learned-forgotten-source-mac-vlansah ]h"]2notification of learned/forgotten source mac/vlansah$]h&]uh1jUhjohhhhhKubjV)}(hhh](j[)}(h FDB Ageingh]h FDB Ageing}(hjM hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjJ hhhhhMubjk)}(hX4The bridge will skip ageing FDB entries marked with NTF_EXT_LEARNED and it is the responsibility of the port driver/device to age out these entries. If the port device supports ageing, when the FDB entry expires, it will notify the driver which in turn will notify the bridge with SWITCHDEV_FDB_DEL. If the device does not support ageing, the driver can simulate ageing using a garbage collection timer to monitor FDB entries. Expired entries will be notified to the bridge using SWITCHDEV_FDB_DEL. See rocker driver for example of driver running ageing timer.h]hX4The bridge will skip ageing FDB entries marked with NTF_EXT_LEARNED and it is the responsibility of the port driver/device to age out these entries. If the port device supports ageing, when the FDB entry expires, it will notify the driver which in turn will notify the bridge with SWITCHDEV_FDB_DEL. If the device does not support ageing, the driver can simulate ageing using a garbage collection timer to monitor FDB entries. Expired entries will be notified to the bridge using SWITCHDEV_FDB_DEL. See rocker driver for example of driver running ageing timer.}(hj[ hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhjJ hhubjk)}(hXqTo keep an NTF_EXT_LEARNED entry "alive", the driver should refresh the FDB entry by calling call_switchdev_notifiers(SWITCHDEV_FDB_ADD, ...). The notification will reset the FDB entry's last-used time to now. The driver should rate limit refresh notifications, for example, no more than once a second. (The last-used time is visible using the bridge -s fdb option).h]hXwTo keep an NTF_EXT_LEARNED entry “alive”, the driver should refresh the FDB entry by calling call_switchdev_notifiers(SWITCHDEV_FDB_ADD, ...). The notification will reset the FDB entry’s last-used time to now. The driver should rate limit refresh notifications, for example, no more than once a second. (The last-used time is visible using the bridge -s fdb option).}(hji hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhjJ hhubeh}(h] fdb-ageingah ]h"] fdb ageingah$]h&]uh1jUhjohhhhhMubjV)}(hhh](j[)}(hSTP State Change on Porth]hSTP State Change on Port}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj hhhhhM#ubjk)}(hXInternally or with a third-party STP protocol implementation (e.g. mstpd), the bridge driver maintains the STP state for ports, and will notify the switch driver of STP state change on a port using the switchdev op switchdev_attr_port_set for SWITCHDEV_ATTR_PORT_ID_STP_UPDATE.h]hXInternally or with a third-party STP protocol implementation (e.g. mstpd), the bridge driver maintains the STP state for ports, and will notify the switch driver of STP state change on a port using the switchdev op switchdev_attr_port_set for SWITCHDEV_ATTR_PORT_ID_STP_UPDATE.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM%hj hhubjk)}(hX+State is one of BR_STATE_*. The switch driver can use STP state updates to update ingress packet filter list for the port. For example, if port is DISABLED, no packets should pass, but if port moves to BLOCKED, then STP BPDUs and other IEEE 01:80:c2:xx:xx:xx link-local multicast packets can pass.h]hX+State is one of BR_STATE_*. The switch driver can use STP state updates to update ingress packet filter list for the port. For example, if port is DISABLED, no packets should pass, but if port moves to BLOCKED, then STP BPDUs and other IEEE 01:80:c2:xx:xx:xx link-local multicast packets can pass.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM*hj hhubjk)}(hNote that STP BDPUs are untagged and STP state applies to all VLANs on the port so packet filters should be applied consistently across untagged and tagged VLANs on the port.h]hNote that STP BDPUs are untagged and STP state applies to all VLANs on the port so packet filters should be applied consistently across untagged and tagged VLANs on the port.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM/hj hhubeh}(h]stp-state-change-on-portah ]h"]stp state change on portah$]h&]uh1jUhjohhhhhM#ubjV)}(hhh](j[)}(hFlooding L2 domainh]hFlooding L2 domain}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj hhhhhM4ubjk)}(hXFor a given L2 VLAN domain, the switch device should flood multicast/broadcast and unknown unicast packets to all ports in domain, if allowed by port's current STP state. The switch driver, knowing which ports are within which vlan L2 domain, can program the switch device for flooding. The packet may be sent to the port netdev for processing by the bridge driver. The bridge should not reflood the packet to the same ports the device flooded, otherwise there will be duplicate packets on the wire.h]hXFor a given L2 VLAN domain, the switch device should flood multicast/broadcast and unknown unicast packets to all ports in domain, if allowed by port’s current STP state. The switch driver, knowing which ports are within which vlan L2 domain, can program the switch device for flooding. The packet may be sent to the port netdev for processing by the bridge driver. The bridge should not reflood the packet to the same ports the device flooded, otherwise there will be duplicate packets on the wire.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM6hj hhubjk)}(hXTo avoid duplicate packets, the switch driver should mark a packet as already forwarded by setting the skb->offload_fwd_mark bit. The bridge driver will mark the skb using the ingress bridge port's mark and prevent it from being forwarded through any bridge port with the same mark.h]hXTo avoid duplicate packets, the switch driver should mark a packet as already forwarded by setting the skb->offload_fwd_mark bit. The bridge driver will mark the skb using the ingress bridge port’s mark and prevent it from being forwarded through any bridge port with the same mark.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM>hj hhubjk)}(hIt is possible for the switch device to not handle flooding and push the packets up to the bridge driver for flooding. This is not ideal as the number of ports scale in the L2 domain as the device is much more efficient at flooding packets that software.h]hIt is possible for the switch device to not handle flooding and push the packets up to the bridge driver for flooding. This is not ideal as the number of ports scale in the L2 domain as the device is much more efficient at flooding packets that software.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMChj hhubjk)}(hIf supported by the device, flood control can be offloaded to it, preventing certain netdevs from flooding unicast traffic for which there is no FDB entry.h]hIf supported by the device, flood control can be offloaded to it, preventing certain netdevs from flooding unicast traffic for which there is no FDB entry.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMHhj hhubeh}(h]flooding-l2-domainah ]h"]flooding l2 domainah$]h&]uh1jUhjohhhhhM4ubjV)}(hhh](j[)}(h IGMP Snoopingh]h IGMP Snooping}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj hhhhhMLubjk)}(hXIn order to support IGMP snooping, the port netdevs should trap to the bridge driver all IGMP join and leave messages. The bridge multicast module will notify port netdevs on every multicast group changed whether it is static configured or dynamically joined/leave. The hardware implementation should be forwarding all registered multicast traffic groups only to the configured ports.h]hXIn order to support IGMP snooping, the port netdevs should trap to the bridge driver all IGMP join and leave messages. The bridge multicast module will notify port netdevs on every multicast group changed whether it is static configured or dynamically joined/leave. The hardware implementation should be forwarding all registered multicast traffic groups only to the configured ports.}(hj$ hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMNhj hhubeh}(h] igmp-snoopingah ]h"] igmp snoopingah$]h&]uh1jUhjohhhhhMLubeh}(h]l2-forwarding-offloadah ]h"]l2 forwarding offloadah$]h&]uh1jUhjWhhhhhKubjV)}(hhh](j[)}(hL3 Routing Offloadh]hL3 Routing Offload}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjB hhhhhMVubjk)}(hX/Offloading L3 routing requires that device be programmed with FIB entries from the kernel, with the device doing the FIB lookup and forwarding. The device does a longest prefix match (LPM) on FIB entries matching route prefix and forwards the packet to the matching FIB entry's nexthop(s) egress ports.h]hX1Offloading L3 routing requires that device be programmed with FIB entries from the kernel, with the device doing the FIB lookup and forwarding. The device does a longest prefix match (LPM) on FIB entries matching route prefix and forwards the packet to the matching FIB entry’s nexthop(s) egress ports.}(hjS hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMXhjB hhubjk)}(hTo program the device, the driver has to register a FIB notifier handler using register_fib_notifier. The following events are available:h]hTo program the device, the driver has to register a FIB notifier handler using register_fib_notifier. The following events are available:}(hja hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM]hjB hhubhtable)}(hhh]htgroup)}(hhh](hcolspec)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jy hjv ubjz )}(hhh]h}(h]h ]h"]h$]h&]colwidthK3uh1jy hjv ubhtbody)}(hhh](hrow)}(hhh](hentry)}(hhh]jk)}(hFIB_EVENT_ENTRY_ADDh]hFIB_EVENT_ENTRY_ADD}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMahj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh]jk)}(haused for both adding a new FIB entry to the device, or modifying an existing entry on the device.h]haused for both adding a new FIB entry to the device, or modifying an existing entry on the device.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMahj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j )}(hhh]jk)}(hFIB_EVENT_ENTRY_DELh]hFIB_EVENT_ENTRY_DEL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMchj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh]jk)}(hused for removing a FIB entryh]hused for removing a FIB entry}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMchj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j )}(hhh]jk)}(hFIB_EVENT_RULE_ADD,h]hFIB_EVENT_RULE_ADD,}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMdhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh]h}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j )}(hhh]jk)}(hFIB_EVENT_RULE_DELh]hFIB_EVENT_RULE_DEL}(hj5 hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMehj2 ubah}(h]h ]h"]h$]h&]uh1j hj/ ubj )}(hhh]jk)}(h"used to propagate FIB rule changesh]h"used to propagate FIB rule changes}(hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMehjI ubah}(h]h ]h"]h$]h&]uh1j hj/ ubeh}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hjv ubeh}(h]h ]h"]h$]h&]colsKuh1jt hjq ubah}(h]h ]h"]h$]h&]uh1jo hjB hhhhhNubjk)}(h9FIB_EVENT_ENTRY_ADD and FIB_EVENT_ENTRY_DEL events pass::h]h8FIB_EVENT_ENTRY_ADD and FIB_EVENT_ENTRY_DEL events pass:}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhhjB hhubj)}(hstruct fib_entry_notifier_info { struct fib_notifier_info info; /* must be first */ u32 dst; int dst_len; struct fib_info *fi; u8 tos; u8 type; u32 tb_id; u32 nlflags; };h]hstruct fib_entry_notifier_info { struct fib_notifier_info info; /* must be first */ u32 dst; int dst_len; struct fib_info *fi; u8 tos; u8 type; u32 tb_id; u32 nlflags; };}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMjhjB hhubjk)}(hto add/modify/delete IPv4 dst/dest_len prefix on table tb_id. The ``*fi`` structure holds details on the route and route's nexthops. ``*dev`` is one of the port netdevs mentioned in the route's next hop list.h](hCto add/modify/delete IPv4 dst/dest_len prefix on table tb_id. The }(hj hhhNhNubj.)}(h``*fi``h]h*fi}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj ubh? structure holds details on the route and route’s nexthops. }(hj hhhNhNubj.)}(h``*dev``h]h*dev}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj ubhE is one of the port netdevs mentioned in the route’s next hop list.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jjhhhMuhjB hhubjk)}(hSRoutes offloaded to the device are labeled with "offload" in the ip route listing::h]hVRoutes offloaded to the device are labeled with “offload” in the ip route listing:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMyhjB hhubj)}(hX$ ip route show default via 192.168.0.2 dev eth0 11.0.0.0/30 dev sw1p1 proto kernel scope link src 11.0.0.2 offload 11.0.0.4/30 via 11.0.0.1 dev sw1p1 proto zebra metric 20 offload 11.0.0.8/30 dev sw1p2 proto kernel scope link src 11.0.0.10 offload 11.0.0.12/30 via 11.0.0.9 dev sw1p2 proto zebra metric 20 offload 12.0.0.2 proto zebra metric 30 offload nexthop via 11.0.0.1 dev sw1p1 weight 1 nexthop via 11.0.0.9 dev sw1p2 weight 1 12.0.0.3 via 11.0.0.1 dev sw1p1 proto zebra metric 20 offload 12.0.0.4 via 11.0.0.9 dev sw1p2 proto zebra metric 20 offload 192.168.0.0/24 dev eth0 proto kernel scope link src 192.168.0.15h]hX$ ip route show default via 192.168.0.2 dev eth0 11.0.0.0/30 dev sw1p1 proto kernel scope link src 11.0.0.2 offload 11.0.0.4/30 via 11.0.0.1 dev sw1p1 proto zebra metric 20 offload 11.0.0.8/30 dev sw1p2 proto kernel scope link src 11.0.0.10 offload 11.0.0.12/30 via 11.0.0.9 dev sw1p2 proto zebra metric 20 offload 12.0.0.2 proto zebra metric 30 offload nexthop via 11.0.0.1 dev sw1p1 weight 1 nexthop via 11.0.0.9 dev sw1p2 weight 1 12.0.0.3 via 11.0.0.1 dev sw1p1 proto zebra metric 20 offload 12.0.0.4 via 11.0.0.9 dev sw1p2 proto zebra metric 20 offload 192.168.0.0/24 dev eth0 proto kernel scope link src 192.168.0.15}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhM|hjB hhubjk)}(hMThe "offload" flag is set in case at least one device offloads the FIB entry.h]hQThe “offload” flag is set in case at least one device offloads the FIB entry.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhjB hhubjk)}(hXXX: add/mod/del IPv6 FIB APIh]hXXX: add/mod/del IPv6 FIB API}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhjB hhubjV)}(hhh](j[)}(hNexthop Resolutionh]hNexthop Resolution}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj hhhhhMubjk)}(hXThe FIB entry's nexthop list contains the nexthop tuple (gateway, dev), but for the switch device to forward the packet with the correct dst mac address, the nexthop gateways must be resolved to the neighbor's mac address. Neighbor mac address discovery comes via the ARP (or ND) process and is available via the arp_tbl neighbor table. To resolve the routes nexthop gateways, the driver should trigger the kernel's neighbor resolution process. See the rocker driver's rocker_port_ipv4_resolve() for an example.h]hX The FIB entry’s nexthop list contains the nexthop tuple (gateway, dev), but for the switch device to forward the packet with the correct dst mac address, the nexthop gateways must be resolved to the neighbor’s mac address. Neighbor mac address discovery comes via the ARP (or ND) process and is available via the arp_tbl neighbor table. To resolve the routes nexthop gateways, the driver should trigger the kernel’s neighbor resolution process. See the rocker driver’s rocker_port_ipv4_resolve() for an example.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubjk)}(hX!The driver can monitor for updates to arp_tbl using the netevent notifier NETEVENT_NEIGH_UPDATE. The device can be programmed with resolved nexthops for the routes as arp_tbl updates. The driver implements ndo_neigh_destroy to know when arp_tbl neighbor entries are purged from the port.h]hX!The driver can monitor for updates to arp_tbl using the netevent notifier NETEVENT_NEIGH_UPDATE. The device can be programmed with resolved nexthops for the routes as arp_tbl updates. The driver implements ndo_neigh_destroy to know when arp_tbl neighbor entries are purged from the port.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubeh}(h]nexthop-resolutionah ]h"]nexthop resolutionah$]h&]uh1jUhjB hhhhhMubeh}(h]l3-routing-offloadah ]h"]l3 routing offloadah$]h&]uh1jUhjWhhhhhMVubjV)}(hhh](j[)}(hDevice driver expected behaviorh]hDevice driver expected behavior}(hj? hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj< hhhhhMubjk)}(hYBelow is a set of defined behavior that switchdev enabled network devices must adhere to.h]hYBelow is a set of defined behavior that switchdev enabled network devices must adhere to.}(hjM hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj< hhubjV)}(hhh](j[)}(hConfiguration-less stateh]hConfiguration-less state}(hj^ hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj[ hhhhhMubjk)}(hXUpon driver bring up, the network devices must be fully operational, and the backing driver must configure the network device such that it is possible to send and receive traffic to this network device and it is properly separated from other network devices/ports (e.g.: as is frequent with a switch ASIC). How this is achieved is heavily hardware dependent, but a simple solution can be to use per-port VLAN identifiers unless a better mechanism is available (proprietary metadata for each network port for instance).h]hXUpon driver bring up, the network devices must be fully operational, and the backing driver must configure the network device such that it is possible to send and receive traffic to this network device and it is properly separated from other network devices/ports (e.g.: as is frequent with a switch ASIC). How this is achieved is heavily hardware dependent, but a simple solution can be to use per-port VLAN identifiers unless a better mechanism is available (proprietary metadata for each network port for instance).*l}(hjl hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj[ hhubjk)}(hXThe network device must be capable of running a full IP protocol stack including multicast, DHCP, IPv4/6, etc. If necessary, it should program the appropriate filters for VLAN, multicast, unicast etc. The underlying device driver must effectively be configured in a similar fashion to what it would do when IGMP snooping is enabled for IP multicast over these switchdev network devices and unsolicited multicast must be filtered as early as possible in the hardware.h]hXThe network device must be capable of running a full IP protocol stack including multicast, DHCP, IPv4/6, etc. If necessary, it should program the appropriate filters for VLAN, multicast, unicast etc. The underlying device driver must effectively be configured in a similar fashion to what it would do when IGMP snooping is enabled for IP multicast over these switchdev network devices and unsolicited multicast must be filtered as early as possible in the hardware.}(hjz hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj[ hhubjk)}(hWhen configuring VLANs on top of the network device, all VLANs must be working, irrespective of the state of other network devices (e.g.: other ports being part of a VLAN-aware bridge doing ingress VID checking). See below for details.h]hWhen configuring VLANs on top of the network device, all VLANs must be working, irrespective of the state of other network devices (e.g.: other ports being part of a VLAN-aware bridge doing ingress VID checking). See below for details.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj[ hhubjk)}(hIf the device implements e.g.: VLAN filtering, putting the interface in promiscuous mode should allow the reception of all VLAN tags (including those not present in the filter(s)).h]hIf the device implements e.g.: VLAN filtering, putting the interface in promiscuous mode should allow the reception of all VLAN tags (including those not present in the filter(s)).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj[ hhubeh}(h]configuration-less-stateah ]h"]configuration-less stateah$]h&]uh1jUhj< hhhhhMubjV)}(hhh](j[)}(hBridged switch portsh]hBridged switch ports}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj hhhhhMubjk)}(hX!When a switchdev enabled network device is added as a bridge member, it should not disrupt any functionality of non-bridged network devices and they should continue to behave as normal network devices. Depending on the bridge configuration knobs below, the expected behavior is documented.h]hX!When a switchdev enabled network device is added as a bridge member, it should not disrupt any functionality of non-bridged network devices and they should continue to behave as normal network devices. Depending on the bridge configuration knobs below, the expected behavior is documented.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubeh}(h]bridged-switch-portsah ]h"]bridged switch portsah$]h&]uh1jUhj< hhhhhMubjV)}(hhh](j[)}(hBridge VLAN filteringh]hBridge VLAN filtering}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jZhj hhhhhMubjk)}(hThe Linux bridge allows the configuration of a VLAN filtering mode (statically, at device creation time, and dynamically, during run time) which must be observed by the underlying switchdev network device/hardware:h]hThe Linux bridge allows the configuration of a VLAN filtering mode (statically, at device creation time, and dynamically, during run time) which must be observed by the underlying switchdev network device/hardware:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubj)}(hhh](j)}(hXwith VLAN filtering turned off: the bridge is strictly VLAN unaware and its data path will process all Ethernet frames as if they are VLAN-untagged. The bridge VLAN database can still be modified, but the modifications should have no effect while VLAN filtering is turned off. Frames ingressing the device with a VID that is not programmed into the bridge/switch's VLAN table must be forwarded and may be processed using a VLAN device (see below). h]jk)}(hXwith VLAN filtering turned off: the bridge is strictly VLAN unaware and its data path will process all Ethernet frames as if they are VLAN-untagged. The bridge VLAN database can still be modified, but the modifications should have no effect while VLAN filtering is turned off. Frames ingressing the device with a VID that is not programmed into the bridge/switch's VLAN table must be forwarded and may be processed using a VLAN device (see below).h]hXwith VLAN filtering turned off: the bridge is strictly VLAN unaware and its data path will process all Ethernet frames as if they are VLAN-untagged. The bridge VLAN database can still be modified, but the modifications should have no effect while VLAN filtering is turned off. Frames ingressing the device with a VID that is not programmed into the bridge/switch’s VLAN table must be forwarded and may be processed using a VLAN device (see below).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(hwith VLAN filtering turned on: the bridge is VLAN-aware and frames ingressing the device with a VID that is not programmed into the bridges/switch's VLAN table must be dropped (strict VID checking). h]jk)}(hwith VLAN filtering turned on: the bridge is VLAN-aware and frames ingressing the device with a VID that is not programmed into the bridges/switch's VLAN table must be dropped (strict VID checking).h]hwith VLAN filtering turned on: the bridge is VLAN-aware and frames ingressing the device with a VID that is not programmed into the bridges/switch’s VLAN table must be dropped (strict VID checking).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj hhhhhNubeh}(h]h ]h"]h$]h&]j j uh1jhhhMhj hhubjk)}(hWhen there is a VLAN device (e.g: sw0p1.100) configured on top of a switchdev network device which is a bridge port member, the behavior of the software network stack must be preserved, or the configuration must be refused if that is not possible.h]hWhen there is a VLAN device (e.g: sw0p1.100) configured on top of a switchdev network device which is a bridge port member, the behavior of the software network stack must be preserved, or the configuration must be refused if that is not possible.}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubj)}(hhh](j)}(hXwith VLAN filtering turned off, the bridge will process all ingress traffic for the port, except for the traffic tagged with a VLAN ID destined for a VLAN upper. The VLAN upper interface (which consumes the VLAN tag) can even be added to a second bridge, which includes other switch ports or software interfaces. Some approaches to ensure that the forwarding domain for traffic belonging to the VLAN upper interfaces are managed properly: * If forwarding destinations can be managed per VLAN, the hardware could be configured to map all traffic, except the packets tagged with a VID belonging to a VLAN upper interface, to an internal VID corresponding to untagged packets. This internal VID spans all ports of the VLAN-unaware bridge. The VID corresponding to the VLAN upper interface spans the physical port of that VLAN interface, as well as the other ports that might be bridged with it. * Treat bridge ports with VLAN upper interfaces as standalone, and let forwarding be handled in the software data path. h](jk)}(hXwith VLAN filtering turned off, the bridge will process all ingress traffic for the port, except for the traffic tagged with a VLAN ID destined for a VLAN upper. The VLAN upper interface (which consumes the VLAN tag) can even be added to a second bridge, which includes other switch ports or software interfaces. Some approaches to ensure that the forwarding domain for traffic belonging to the VLAN upper interfaces are managed properly:h]hXwith VLAN filtering turned off, the bridge will process all ingress traffic for the port, except for the traffic tagged with a VLAN ID destined for a VLAN upper. The VLAN upper interface (which consumes the VLAN tag) can even be added to a second bridge, which includes other switch ports or software interfaces. Some approaches to ensure that the forwarding domain for traffic belonging to the VLAN upper interfaces are managed properly:}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj<ubj)}(hXK* If forwarding destinations can be managed per VLAN, the hardware could be configured to map all traffic, except the packets tagged with a VID belonging to a VLAN upper interface, to an internal VID corresponding to untagged packets. This internal VID spans all ports of the VLAN-unaware bridge. The VID corresponding to the VLAN upper interface spans the physical port of that VLAN interface, as well as the other ports that might be bridged with it. * Treat bridge ports with VLAN upper interfaces as standalone, and let forwarding be handled in the software data path. h]j)}(hhh](j)}(hXIf forwarding destinations can be managed per VLAN, the hardware could be configured to map all traffic, except the packets tagged with a VID belonging to a VLAN upper interface, to an internal VID corresponding to untagged packets. This internal VID spans all ports of the VLAN-unaware bridge. The VID corresponding to the VLAN upper interface spans the physical port of that VLAN interface, as well as the other ports that might be bridged with it.h]jk)}(hXIf forwarding destinations can be managed per VLAN, the hardware could be configured to map all traffic, except the packets tagged with a VID belonging to a VLAN upper interface, to an internal VID corresponding to untagged packets. This internal VID spans all ports of the VLAN-unaware bridge. The VID corresponding to the VLAN upper interface spans the physical port of that VLAN interface, as well as the other ports that might be bridged with it.h]hXIf forwarding destinations can be managed per VLAN, the hardware could be configured to map all traffic, except the packets tagged with a VID belonging to a VLAN upper interface, to an internal VID corresponding to untagged packets. This internal VID spans all ports of the VLAN-unaware bridge. The VID corresponding to the VLAN upper interface spans the physical port of that VLAN interface, as well as the other ports that might be bridged with it.}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhjUubah}(h]h ]h"]h$]h&]uh1jhjRubj)}(hvTreat bridge ports with VLAN upper interfaces as standalone, and let forwarding be handled in the software data path. h]jk)}(huTreat bridge ports with VLAN upper interfaces as standalone, and let forwarding be handled in the software data path.h]huTreat bridge ports with VLAN upper interfaces as standalone, and let forwarding be handled in the software data path.}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhjmubah}(h]h ]h"]h$]h&]uh1jhjRubeh}(h]h ]h"]h$]h&]j *uh1jhhhMhjNubah}(h]h ]h"]h$]h&]uh1jhhhMhj<ubeh}(h]h ]h"]h$]h&]uh1jhj9hhhhhNubj)}(hX1with VLAN filtering turned on, these VLAN devices can be created as long as the bridge does not have an existing VLAN entry with the same VID on any bridge port. These VLAN devices cannot be enslaved into the bridge since they duplicate functionality/use case with the bridge's VLAN data path processing. h]jk)}(hX0with VLAN filtering turned on, these VLAN devices can be created as long as the bridge does not have an existing VLAN entry with the same VID on any bridge port. These VLAN devices cannot be enslaved into the bridge since they duplicate functionality/use case with the bridge's VLAN data path processing.h]hX2with VLAN filtering turned on, these VLAN devices can be created as long as the bridge does not have an existing VLAN entry with the same VID on any bridge port. These VLAN devices cannot be enslaved into the bridge since they duplicate functionality/use case with the bridge’s VLAN data path processing.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhjubah}(h]h ]h"]h$]h&]uh1jhj9hhhhhNubeh}(h]h ]h"]h$]h&]j j uh1jhhhMhj hhubjk)}(hXkNon-bridged network ports of the same switch fabric must not be disturbed in any way by the enabling of VLAN filtering on the bridge device(s). If the VLAN filtering setting is global to the entire chip, then the standalone ports should indicate to the network stack that VLAN filtering is required by setting 'rx-vlan-filter: on [fixed]' in the ethtool features.h]hXoNon-bridged network ports of the same switch fabric must not be disturbed in any way by the enabling of VLAN filtering on the bridge device(s). If the VLAN filtering setting is global to the entire chip, then the standalone ports should indicate to the network stack that VLAN filtering is required by setting ‘rx-vlan-filter: on [fixed]’ in the ethtool features.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubjk)}(hXBecause VLAN filtering can be turned on/off at runtime, the switchdev driver must be able to reconfigure the underlying hardware on the fly to honor the toggling of that option and behave appropriately. If that is not possible, the switchdev driver can also refuse to support dynamic toggling of the VLAN filtering knob at runtime and require a destruction of the bridge device(s) and creation of new bridge device(s) with a different VLAN filtering value to ensure VLAN awareness is pushed down to the hardware.h]hXBecause VLAN filtering can be turned on/off at runtime, the switchdev driver must be able to reconfigure the underlying hardware on the fly to honor the toggling of that option and behave appropriately. If that is not possible, the switchdev driver can also refuse to support dynamic toggling of the VLAN filtering knob at runtime and require a destruction of the bridge device(s) and creation of new bridge device(s) with a different VLAN filtering value to ensure VLAN awareness is pushed down to the hardware.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubjk)}(hEven when VLAN filtering in the bridge is turned off, the underlying switch hardware and driver may still configure itself in a VLAN-aware mode provided that the behavior described above is observed.h]hEven when VLAN filtering in the bridge is turned off, the underlying switch hardware and driver may still configure itself in a VLAN-aware mode provided that the behavior described above is observed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubjk)}(hThe VLAN protocol of the bridge plays a role in deciding whether a packet is treated as tagged or not: a bridge using the 802.1ad protocol must treat both VLAN-untagged packets, as well as packets tagged with 802.1Q headers, as untagged.h]hThe VLAN protocol of the bridge plays a role in deciding whether a packet is treated as tagged or not: a bridge using the 802.1ad protocol must treat both VLAN-untagged packets, as well as packets tagged with 802.1Q headers, as untagged.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubjk)}(hThe 802.1p (VID 0) tagged packets must be treated in the same way by the device as untagged packets, since the bridge device does not allow the manipulation of VID 0 in its database.h]hThe 802.1p (VID 0) tagged packets must be treated in the same way by the device as untagged packets, since the bridge device does not allow the manipulation of VID 0 in its database.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM hj hhubjk)}(hXWhen the bridge has VLAN filtering enabled and a PVID is not configured on the ingress port, untagged and 802.1p tagged packets must be dropped. When the bridge has VLAN filtering enabled and a PVID exists on the ingress port, untagged and priority-tagged packets must be accepted and forwarded according to the bridge's port membership of the PVID VLAN. When the bridge has VLAN filtering disabled, the presence/lack of a PVID should not influence the packet forwarding decision.h]hXWhen the bridge has VLAN filtering enabled and a PVID is not configured on the ingress port, untagged and 802.1p tagged packets must be dropped. When the bridge has VLAN filtering enabled and a PVID exists on the ingress port, untagged and priority-tagged packets must be accepted and forwarded according to the bridge’s port membership of the PVID VLAN. When the bridge has VLAN filtering disabled, the presence/lack of a PVID should not influence the packet forwarding decision.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj hhubeh}(h]bridge-vlan-filteringah ]h"]bridge vlan filteringah$]h&]uh1jUhj< hhhhhMubjV)}(hhh](j[)}(hBridge IGMP snoopingh]hBridge IGMP snooping}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jZhjhhhhhMubjk)}(hThe Linux bridge allows the configuration of IGMP snooping (statically, at interface creation time, or dynamically, during runtime) which must be observed by the underlying switchdev network device/hardware in the following way:h]hThe Linux bridge allows the configuration of IGMP snooping (statically, at interface creation time, or dynamically, during runtime) which must be observed by the underlying switchdev network device/hardware in the following way:}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhjhhubj)}(hhh](j)}(hXwhen IGMP snooping is turned off, multicast traffic must be flooded to all ports within the same bridge that have mcast_flood=true. The CPU/management port should ideally not be flooded (unless the ingress interface has IFF_ALLMULTI or IFF_PROMISC) and continue to learn multicast traffic through the network stack notifications. If the hardware is not capable of doing that then the CPU/management port must also be flooded and multicast filtering happens in software. h]jk)}(hXwhen IGMP snooping is turned off, multicast traffic must be flooded to all ports within the same bridge that have mcast_flood=true. The CPU/management port should ideally not be flooded (unless the ingress interface has IFF_ALLMULTI or IFF_PROMISC) and continue to learn multicast traffic through the network stack notifications. If the hardware is not capable of doing that then the CPU/management port must also be flooded and multicast filtering happens in software.h]hXwhen IGMP snooping is turned off, multicast traffic must be flooded to all ports within the same bridge that have mcast_flood=true. The CPU/management port should ideally not be flooded (unless the ingress interface has IFF_ALLMULTI or IFF_PROMISC) and continue to learn multicast traffic through the network stack notifications. If the hardware is not capable of doing that then the CPU/management port must also be flooded and multicast filtering happens in software.}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhMhj4ubah}(h]h ]h"]h$]h&]uh1jhj1hhhhhNubj)}(hX!when IGMP snooping is turned on, multicast traffic must selectively flow to the appropriate network ports (including CPU/management port). Flooding of unknown multicast should be only towards the ports connected to a multicast router (the local device may also act as a multicast router). h]jk)}(hX when IGMP snooping is turned on, multicast traffic must selectively flow to the appropriate network ports (including CPU/management port). Flooding of unknown multicast should be only towards the ports connected to a multicast router (the local device may also act as a multicast router).h]hX when IGMP snooping is turned on, multicast traffic must selectively flow to the appropriate network ports (including CPU/management port). Flooding of unknown multicast should be only towards the ports connected to a multicast router (the local device may also act as a multicast router).}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM%hjLubah}(h]h ]h"]h$]h&]uh1jhj1hhhhhNubeh}(h]h ]h"]h$]h&]j j uh1jhhhMhjhhubjk)}(hThe switch must adhere to RFC 4541 and flood multicast traffic accordingly since that is what the Linux bridge implementation does.h]hThe switch must adhere to RFC 4541 and flood multicast traffic accordingly since that is what the Linux bridge implementation does.}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM*hjhhubjk)}(hBecause IGMP snooping can be turned on/off at runtime, the switchdev driver must be able to reconfigure the underlying hardware on the fly to honor the toggling of that option and behave appropriately.h]hBecause IGMP snooping can be turned on/off at runtime, the switchdev driver must be able to reconfigure the underlying hardware on the fly to honor the toggling of that option and behave appropriately.}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM-hjhhubjk)}(hA switchdev driver can also refuse to support dynamic toggling of the multicast snooping knob at runtime and require the destruction of the bridge device(s) and creation of a new bridge device(s) with a different multicast snooping value.h]hA switchdev driver can also refuse to support dynamic toggling of the multicast snooping knob at runtime and require the destruction of the bridge device(s) and creation of a new bridge device(s) with a different multicast snooping value.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhhhM1hjhhubeh}(h]bridge-igmp-snoopingah ]h"]bridge igmp snoopingah$]h&]uh1jUhj< hhhhhMubeh}(h]device-driver-expected-behaviorah ]h"]device driver expected behaviorah$]h&]uh1jUhjWhhhhhMubeh}(h](-ethernet-switch-device-driver-model-switchdevjTeh ]h"](/ethernet switch device driver model (switchdev) switchdeveh$]h&]uh1jUhhhhhhhKexpect_referenced_by_name}jjIsexpect_referenced_by_id}jTjIsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(jZN generatorN datestampN source_linkN source_urlN toc_backlinksj footnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}(hhhhhhj jjjj*jj9j-jHj<jWjKjfjZjujijjxjjjjjjjjjjjjjjjjj jjjj)jj8j,jGj;jVjJjejYjtjhjjwjjjjjjjjjjjjjjjjj jjj j(jj7j+jFj:jUjIjdjXjsjgjjvjjjjjjjjjjjjjjjjj jjj j'jj6j*jEj9jTjHjcjWjrjfjjujjjjjjjjjjjjjjjjjjjj j&jj5j)jDj8usubstitution_names}(amphߌaposhasthbrvbarj bsoljcentj*colonj9commajHcommatjWcopyjfcurrenjudarrjdegjdividejdollarjequalsjexcljfrac12jfrac14jfrac18jfrac34j frac38jfrac58j)frac78j8gtjGhalfjVhorbarjehyphenjtiexcljiquestjlaquojlarrjlcubjldquojlowbarjlparjlsqbjlsquoj ltjmicroj(middotj7nbspjFnotjUnumjdohmjsordfjordmjparajpercntjperiodjplusjplusmnjpoundjquestjquotj raquojrarrj'rcubj6rdquojEregjTrparjcrsqbjrrsquojsectjsemijshyjsoljsungjsup1jsup2jsup3jtimesjtradejuarrj&verbarj5yenjDurefnames}refids}jT]jIasnameids}(jjTjjjjj9j6jljijjjjj/j,jdjaj? j< j j jG jD j| jy j j j j j7 j4 j9 j6 j1 j. jjj j j j jj jju nametypes}(jjjj9jljjj/jdj? j jG j| j j j7 j9 j1 jj j jjuh}(jTjWjjWjjj6jjij<jjwjjj,jjaj2j< joj jjD j jy jJ j j j j j4 j j6 jB j. j jj< j j[ j j j j jju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages]hsystem_message)}(hhh]jk)}(hhh]h/Hyperlink target "switchdev" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1jjhjubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehlineKYuh1juba transformerN include_log]&Documentation/networking/switchdev.rst(NNNNta decorationNhhub.