Documentation/networking/switchdev.rst

1 .. SPDX-License-Identifier: GPL-2.0
11 Copyright |copy| 2014-2015 Scott Feldman <sfeldma@gmail.com>
14 The Ethernet switch device driver model (switchdev) is an in-kernel driver
18 Figure 1 is a block diagram showing the components of the switchdev model for
19 an example setup using a data-center-class switch ASIC chip.  Other setups
20 with SR-IOV or soft switches, such as OVS, are possible.
25 			     User-space tools
28       +-------------------------------------------------------------------+
31 		     +--------------+-------------------------------+
35 		     +----------------------------------------------+
41 		     +--+----+----+----+----+----+---+  +-----+-----+
45 		     +--------------+----------------+  +-----------+
48       +-------------------------------------------------------------------+
50 		     +--------------+----------------+
52 		     |  +----+                       +--------+
55 		     +--|----|----+----+----+----+---+
60 			     front-panel ports
67 -------------
76 -------------
82 Switch Ports
83 ------------
87 port, called the port netdev.  A port netdev is the software representation of
92 provide to the user access to the physical properties of the switch port such
95 There is (currently) no higher-level kernel object for the switch beyond the
96 port netdevs.  All of the switchdev driver ops are netdev ops or switchdev ops.
98 A switch management port is outside the scope of the switchdev driver model.
108 each port of a switch. The ID must be unique between switches on the same
112 The switch ID is used to locate ports on a switch and to know if aggregated
113 ports belong to the same switch.
119 of the port as a key, for example the port MAC address or the port PHYS name.
120 Hard-coding of kernel netdev names within the driver is discouraged; let the
121 kernel pick the default netdev name, and let udev set the final name based on a
125 useful for dynamically-named ports where the device names its ports based on
127 into 4 10G ports, resulting in 4 port netdevs, the device can give a unique
134 is the port name or ID, and Z is the sub-port name or ID.  For example, sw1p1s0
135 would be sub-port 0 on port 1 on switch 1.
140 dev->netns_local
142 If the switchdev driver (and device) only supports offloading of the default
143 network namespace (netns), the driver should set this private flag to prevent
144 the port netdev from being moved out of the default netns.  A netns-aware
145 driver/device would not set this flag and be responsible for partitioning
152 The port netdevs representing the physical switch ports can be organized into
153 higher-level switching constructs.  The default construct is a standalone
154 router port, used to offload L3 forwarding.  Two or more ports can be bonded
155 together to form a LAG.  Two or more ports (or LAGs) can be bridged to bridge
156 L2 networks.  VLANs can be applied to sub-divide L2 networks.  L2-over-L3
157 tunnels can be built on ports.  These constructs are built using standard Linux
158 tools such as the bridge driver, the bonding/team drivers, and netlink-based
169 ---------------------
177 	- Static FDB entries installed on a bridge port
178 	- Notification of learned/forgotten src mac/vlans from device
179 	- STP state changes on the port
180 	- VLAN flooding of multicast/broadcast and unknown unicast packets
191 (the "static" keyword is non-optional: if not specified, the entry defaults to
194 The "self" keyword (optional because it is implicit) has the role of
196 implementation of the ``DEV`` device itself. If ``DEV`` is a bridge port, this
197 will bypass the bridge and therefore leave the software database out of sync
204 The above command instructs the kernel to search for a master interface of
205 ``DEV`` and fulfill the operation through the ``ndo_fdb_add`` method of that.
216 notifying the operating system of newly learned/forgotten dynamic FDB
226 Notification of Learned/Forgotten Source MAC/VLANs
230 and notify the switch driver of the mac/vlan/port tuples.  The switch driver,
258 	bridge link set dev DEV learning off
262 	bridge link set dev DEV learning on self
263 	bridge link set dev DEV learning_sync on self
265 Learning_sync attribute enables syncing of the learned/forgotten FDB entry to
276 the responsibility of the port driver/device to age out these entries.  If the
282 example of driver running ageing timer.
286 notification will reset the FDB entry's last-used time to now.  The driver
288 second.  (The last-used time is visible using the bridge -s fdb option).
293 Internally or with a third-party STP protocol implementation (e.g. mstpd), the
294 bridge driver maintains the STP state for ports, and will notify the switch
295 driver of STP state change on a port using the switchdev op
298 State is one of BR_STATE_*.  The switch driver can use STP state updates to
301 and other IEEE 01:80:c2:xx:xx:xx link-local multicast packets can pass.
311 and unknown unicast packets to all ports in domain, if allowed by port's
312 current STP state.  The switch driver, knowing which ports are within which
315 bridge should not reflood the packet to the same ports the device flooded,
319 forwarded by setting the skb->offload_fwd_mark bit. The bridge driver will mark
325 of ports scale in the L2 domain as the device is much more efficient at
339 traffic groups only to the configured ports.
342 ------------------
347 forwards the packet to the matching FIB entry's nexthop(s) egress ports.
375 of the port netdevs mentioned in the route's next hop list.
393 The "offload" flag is set in case at least one device offloads the FIB entry.
414 -------------------------------
416 Below is a set of defined behavior that switchdev enabled network devices must
419 Configuration-less state
425 from other network devices/ports (e.g.: as is frequent with a switch ASIC). How
427 use per-port VLAN identifiers unless a better mechanism is available
430 The network device must be capable of running a full IP protocol stack
438 When configuring VLANs on top of the network device, all VLANs must be working,
439 irrespective of the state of other network devices (e.g.: other ports being part
440 of a VLAN-aware bridge doing ingress VID checking). See below for details.
443 promiscuous mode should allow the reception of all VLAN tags (including those
446 Bridged switch ports
450 not disrupt any functionality of non-bridged network devices and they
457 The Linux bridge allows the configuration of a VLAN filtering mode (statically,
461 - with VLAN filtering turned off: the bridge is strictly VLAN unaware and its
462   data path will process all Ethernet frames as if they are VLAN-untagged.
468 - with VLAN filtering turned on: the bridge is VLAN-aware and frames ingressing
472 When there is a VLAN device (e.g: sw0p1.100) configured on top of a switchdev
473 network device which is a bridge port member, the behavior of the software
477 - with VLAN filtering turned off, the bridge will process all ingress traffic
480   be added to a second bridge, which includes other switch ports or software
487       untagged packets. This internal VID spans all ports of the VLAN-unaware
489       physical port of that VLAN interface, as well as the other ports that
491     * Treat bridge ports with VLAN upper interfaces as standalone, and let
494 - with VLAN filtering turned on, these VLAN devices can be created as long as
499 Non-bridged network ports of the same switch fabric must not be disturbed in any
500 way by the enabling of VLAN filtering on the bridge device(s). If the VLAN
501 filtering setting is global to the entire chip, then the standalone ports
503 'rx-vlan-filter: on [fixed]' in the ethtool features.
507 toggling of that option and behave appropriately. If that is not possible, the
508 switchdev driver can also refuse to support dynamic toggling of the VLAN
509 filtering knob at runtime and require a destruction of the bridge device(s) and
510 creation of new bridge device(s) with a different VLAN filtering value to
514 hardware and driver may still configure itself in a VLAN-aware mode provided
517 The VLAN protocol of the bridge plays a role in deciding whether a packet is
519 VLAN-untagged packets, as well as packets tagged with 802.1Q headers, as
523 as untagged packets, since the bridge device does not allow the manipulation of
529 priority-tagged packets must be accepted and forwarded according to the
530 bridge's port membership of the PVID VLAN. When the bridge has VLAN filtering
531 disabled, the presence/lack of a PVID should not influence the packet
537 The Linux bridge allows the configuration of IGMP snooping (statically, at
541 - when IGMP snooping is turned off, multicast traffic must be flooded to all
542   ports within the same bridge that have mcast_flood=true. The CPU/management
545   the network stack notifications. If the hardware is not capable of doing that
549 - when IGMP snooping is turned on, multicast traffic must selectively flow
550   to the appropriate network ports (including CPU/management port). Flooding of
551   unknown multicast should be only towards the ports connected to a multicast
559 toggling of that option and behave appropriately.
561 A switchdev driver can also refuse to support dynamic toggling of the multicast
562 snooping knob at runtime and require the destruction of the bridge device(s)
563 and creation of a new bridge device(s) with a different multicast snooping