1Ethernet switch device driver model (switchdev) 2=============================================== 3Copyright (c) 2014 Jiri Pirko <jiri@resnulli.us> 4Copyright (c) 2014-2015 Scott Feldman <sfeldma@gmail.com> 5 6 7The Ethernet switch device driver model (switchdev) is an in-kernel driver 8model for switch devices which offload the forwarding (data) plane from the 9kernel. 10 11Figure 1 is a block diagram showing the components of the switchdev model for 12an example setup using a data-center-class switch ASIC chip. Other setups 13with SR-IOV or soft switches, such as OVS, are possible. 14 15 16���������������������������������������������������������������������������������������User-space���tools��������������������������������������������������������������������������������������������������� 17������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������ 18���������������������user���space���������������������������������������������������������|��������������������������������������������������������������������������������������������������������������������������� 19������������������+-------------------------------------------------------------------+��������� 20���������������������kernel���������������������������������������������������������������������|���Netlink��������������������������������������������������������������������������������������������������� 21������������������������������������������������������������������������������������������������������������|��������������������������������������������������������������������������������������������������������������������������� 22���������������������������������������������������������������+--------------+-------------------------------+��������������������������� 23���������������������������������������������������������������|���������������������������Network���stack������������������������������������������������������������������������|��������������������������� 24���������������������������������������������������������������|���������������������������������(Linux)������������������������������������������������������������������������������������|��������������������������� 25���������������������������������������������������������������|������������������������������������������������������������������������������������������������������������������������������������������|��������������������������� 26���������������������������������������������������������������+----------------------------------------------+��������������������������� 27������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������ 28 sw1p2 sw1p4 sw1p6 29������������������������������������������������������������������sw1p1��� + sw1p3 + ���sw1p5 + ������������������������eth1��������������������������������������� 30������������������������������������������������������������������������+������������|������������+������������|������������+������������|������������������������������������+��������������������������������������������� 31������������������������������������������������������������������������|������������|������������|������������|������������|������������|������������������������������������|��������������������������������������������� 32���������������������������������������������������������������+--+----+----+----+-+--+----+---+������+-----+-----+��������������������������� 33���������������������������������������������������������������|���������������������������Switch���driver���������������������������|������|������������mgmt���������|��������������������������� 34���������������������������������������������������������������|������������������������(this���document)������������������������|������|���������driver������|��������������������������� 35���������������������������������������������������������������|���������������������������������������������������������������������������������������������|������|���������������������������������|��������������������������� 36���������������������������������������������������������������+--------------+----------------+������+-----------+��������������������������� 37������������������������������������������������������������������������������������������������������������|��������������������������������������������������������������������������� ��������������������������������������������� 38���������������������kernel���������������������������������������������������������������������|���HW���bus���(eg���PCI)��������������������������� ��������������������������������������������� 39������������������+-------------------------------------------------------------------+��������� 40���������������������hardware���������������������������������������������������������������|��������������������������������������������������������������������������� ��������������������������������������������� 41���������������������������������������������������������������+--------------+---+------------+������������������������ ��������������������������������������������� 42���������������������������������������������������������������|���������������������������Switch���device (sw1)���������|������������������������ ��������������������������������������������� 43���������������������������������������������������������������|������+----+���������������������������������������������������������������������+--------+��������������������������������������������� 44���������������������������������������������������������������|������|������������v���offloaded���data���path���������|���mgmt���port������������������������������������������ 45���������������������������������������������������������������|������|������������|���������������������������������������������������������������������|������������������������������������������������������������������������ 46���������������������������������������������������������������+--|----|----+----+----+----+---+������������������������������������������������������������������������ 47������������������������������������������������������������������������|������������|������������|������������|������������|������������|������������������������������������������������������������������������������������ 48������������������������������������������������������������������������+������������+������������+������������+������������+������������+������������������������������������������������������������������������������������ 49���������������������������������������������������������������������p1���������p2���������p3���������p4���������p5���������p6 50��������������������������������������������������������������������������������������������������������������������� 51���������������������������������������������������������������������������������������front-panel���ports������������������������������������������������������������������������������������������������ 52������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������ 53 54 Fig 1. 55 56 57Include Files 58------------- 59 60#include <linux/netdevice.h> 61#include <net/switchdev.h> 62 63 64Configuration 65------------- 66 67Use "depends NET_SWITCHDEV" in driver's Kconfig to ensure switchdev model 68support is built for driver. 69 70 71Switch Ports 72------------ 73 74On switchdev driver initialization, the driver will allocate and register a 75struct net_device (using register_netdev()) for each enumerated physical switch 76port, called the port netdev. A port netdev is the software representation of 77the physical port and provides a conduit for control traffic to/from the 78controller (the kernel) and the network, as well as an anchor point for higher 79level constructs such as bridges, bonds, VLANs, tunnels, and L3 routers. Using 80standard netdev tools (iproute2, ethtool, etc), the port netdev can also 81provide to the user access to the physical properties of the switch port such 82as PHY link state and I/O statistics. 83 84There is (currently) no higher-level kernel object for the switch beyond the 85port netdevs. All of the switchdev driver ops are netdev ops or switchdev ops. 86 87A switch management port is outside the scope of the switchdev driver model. 88Typically, the management port is not participating in offloaded data plane and 89is loaded with a different driver, such as a NIC driver, on the management port 90device. 91 92Port Netdev Naming 93^^^^^^^^^^^^^^^^^^ 94 95Udev rules should be used for port netdev naming, using some unique attribute 96of the port as a key, for example the port MAC address or the port PHYS name. 97Hard-coding of kernel netdev names within the driver is discouraged; let the 98kernel pick the default netdev name, and let udev set the final name based on a 99port attribute. 100 101Using port PHYS name (ndo_get_phys_port_name) for the key is particularly 102useful for dynamically-named ports where the device names its ports based on 103external configuration. For example, if a physical 40G port is split logically 104into 4 10G ports, resulting in 4 port netdevs, the device can give a unique 105name for each port using port PHYS name. The udev rule would be: 106 107SUBSYSTEM=="net", ACTION=="add", DRIVER="<driver>", ATTR{phys_port_name}!="", \ 108 NAME="$attr{phys_port_name}" 109 110Suggested naming convention is "swXpYsZ", where X is the switch name or ID, Y 111is the port name or ID, and Z is the sub-port name or ID. For example, sw1p1s0 112would be sub-port 0 on port 1 on switch 1. 113 114Switch ID 115^^^^^^^^^ 116 117The switchdev driver must implement the switchdev op switchdev_port_attr_get 118for SWITCHDEV_ATTR_ID_PORT_PARENT_ID for each port netdev, returning the same 119physical ID for each port of a switch. The ID must be unique between switches 120on the same system. The ID does not need to be unique between switches on 121different systems. 122 123The switch ID is used to locate ports on a switch and to know if aggregated 124ports belong to the same switch. 125 126Port Features 127^^^^^^^^^^^^^ 128 129NETIF_F_NETNS_LOCAL 130 131If the switchdev driver (and device) only supports offloading of the default 132network namespace (netns), the driver should set this feature flag to prevent 133the port netdev from being moved out of the default netns. A netns-aware 134driver/device would not set this flag and be responsible for partitioning 135hardware to preserve netns containment. This means hardware cannot forward 136traffic from a port in one namespace to another port in another namespace. 137 138Port Topology 139^^^^^^^^^^^^^ 140 141The port netdevs representing the physical switch ports can be organized into 142higher-level switching constructs. The default construct is a standalone 143router port, used to offload L3 forwarding. Two or more ports can be bonded 144together to form a LAG. Two or more ports (or LAGs) can be bridged to bridge 145L2 networks. VLANs can be applied to sub-divide L2 networks. L2-over-L3 146tunnels can be built on ports. These constructs are built using standard Linux 147tools such as the bridge driver, the bonding/team drivers, and netlink-based 148tools such as iproute2. 149 150The switchdev driver can know a particular port's position in the topology by 151monitoring NETDEV_CHANGEUPPER notifications. For example, a port moved into a 152bond will see it's upper master change. If that bond is moved into a bridge, 153the bond's upper master will change. And so on. The driver will track such 154movements to know what position a port is in in the overall topology by 155registering for netdevice events and acting on NETDEV_CHANGEUPPER. 156 157L2 Forwarding Offload 158--------------------- 159 160The idea is to offload the L2 data forwarding (switching) path from the kernel 161to the switchdev device by mirroring bridge FDB entries down to the device. An 162FDB entry is the {port, MAC, VLAN} tuple forwarding destination. 163 164To offloading L2 bridging, the switchdev driver/device should support: 165 166 - Static FDB entries installed on a bridge port 167 - Notification of learned/forgotten src mac/vlans from device 168 - STP state changes on the port 169 - VLAN flooding of multicast/broadcast and unknown unicast packets 170 171Static FDB Entries 172^^^^^^^^^^^^^^^^^^ 173 174The switchdev driver should implement ndo_fdb_add, ndo_fdb_del and ndo_fdb_dump 175to support static FDB entries installed to the device. Static bridge FDB 176entries are installed, for example, using iproute2 bridge cmd: 177 178 bridge fdb add ADDR dev DEV [vlan VID] [self] 179 180The driver should use the helper switchdev_port_fdb_xxx ops for ndo_fdb_xxx 181ops, and handle add/delete/dump of SWITCHDEV_OBJ_ID_PORT_FDB object using 182switchdev_port_obj_xxx ops. 183 184XXX: what should be done if offloading this rule to hardware fails (for 185example, due to full capacity in hardware tables) ? 186 187Note: by default, the bridge does not filter on VLAN and only bridges untagged 188traffic. To enable VLAN support, turn on VLAN filtering: 189 190 echo 1 >/sys/class/net/<bridge>/bridge/vlan_filtering 191 192Notification of Learned/Forgotten Source MAC/VLANs 193^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 194 195The switch device will learn/forget source MAC address/VLAN on ingress packets 196and notify the switch driver of the mac/vlan/port tuples. The switch driver, 197in turn, will notify the bridge driver using the switchdev notifier call: 198 199 err = call_switchdev_notifiers(val, dev, info); 200 201Where val is SWITCHDEV_FDB_ADD when learning and SWITCHDEV_FDB_DEL when 202forgetting, and info points to a struct switchdev_notifier_fdb_info. On 203SWITCHDEV_FDB_ADD, the bridge driver will install the FDB entry into the 204bridge's FDB and mark the entry as NTF_EXT_LEARNED. The iproute2 bridge 205command will label these entries "offload": 206 207 $ bridge fdb 208 52:54:00:12:35:01 dev sw1p1 master br0 permanent 209 00:02:00:00:02:00 dev sw1p1 master br0 offload 210 00:02:00:00:02:00 dev sw1p1 self 211 52:54:00:12:35:02 dev sw1p2 master br0 permanent 212 00:02:00:00:03:00 dev sw1p2 master br0 offload 213 00:02:00:00:03:00 dev sw1p2 self 214 33:33:00:00:00:01 dev eth0 self permanent 215 01:00:5e:00:00:01 dev eth0 self permanent 216 33:33:ff:00:00:00 dev eth0 self permanent 217 01:80:c2:00:00:0e dev eth0 self permanent 218 33:33:00:00:00:01 dev br0 self permanent 219 01:00:5e:00:00:01 dev br0 self permanent 220 33:33:ff:12:35:01 dev br0 self permanent 221 222Learning on the port should be disabled on the bridge using the bridge command: 223 224 bridge link set dev DEV learning off 225 226Learning on the device port should be enabled, as well as learning_sync: 227 228 bridge link set dev DEV learning on self 229 bridge link set dev DEV learning_sync on self 230 231Learning_sync attribute enables syncing of the learned/forgotton FDB entry to 232the bridge's FDB. It's possible, but not optimal, to enable learning on the 233device port and on the bridge port, and disable learning_sync. 234 235To support learning and learning_sync port attributes, the driver implements 236switchdev op switchdev_port_attr_get/set for 237SWITCHDEV_ATTR_PORT_ID_BRIDGE_FLAGS. The driver should initialize the attributes 238to the hardware defaults. 239 240FDB Ageing 241^^^^^^^^^^ 242 243The bridge will skip ageing FDB entries marked with NTF_EXT_LEARNED and it is 244the responsibility of the port driver/device to age out these entries. If the 245port device supports ageing, when the FDB entry expires, it will notify the 246driver which in turn will notify the bridge with SWITCHDEV_FDB_DEL. If the 247device does not support ageing, the driver can simulate ageing using a 248garbage collection timer to monitor FBD entries. Expired entries will be 249notified to the bridge using SWITCHDEV_FDB_DEL. See rocker driver for 250example of driver running ageing timer. 251 252To keep an NTF_EXT_LEARNED entry "alive", the driver should refresh the FDB 253entry by calling call_switchdev_notifiers(SWITCHDEV_FDB_ADD, ...). The 254notification will reset the FDB entry's last-used time to now. The driver 255should rate limit refresh notifications, for example, no more than once a 256second. (The last-used time is visible using the bridge -s fdb option). 257 258STP State Change on Port 259^^^^^^^^^^^^^^^^^^^^^^^^ 260 261Internally or with a third-party STP protocol implementation (e.g. mstpd), the 262bridge driver maintains the STP state for ports, and will notify the switch 263driver of STP state change on a port using the switchdev op 264switchdev_attr_port_set for SWITCHDEV_ATTR_PORT_ID_STP_UPDATE. 265 266State is one of BR_STATE_*. The switch driver can use STP state updates to 267update ingress packet filter list for the port. For example, if port is 268DISABLED, no packets should pass, but if port moves to BLOCKED, then STP BPDUs 269and other IEEE 01:80:c2:xx:xx:xx link-local multicast packets can pass. 270 271Note that STP BDPUs are untagged and STP state applies to all VLANs on the port 272so packet filters should be applied consistently across untagged and tagged 273VLANs on the port. 274 275Flooding L2 domain 276^^^^^^^^^^^^^^^^^^ 277 278For a given L2 VLAN domain, the switch device should flood multicast/broadcast 279and unknown unicast packets to all ports in domain, if allowed by port's 280current STP state. The switch driver, knowing which ports are within which 281vlan L2 domain, can program the switch device for flooding. The packet may 282be sent to the port netdev for processing by the bridge driver. The 283bridge should not reflood the packet to the same ports the device flooded, 284otherwise there will be duplicate packets on the wire. 285 286To avoid duplicate packets, the device/driver should mark a packet as already 287forwarded using skb->offload_fwd_mark. The same mark is set on the device 288ports in the domain using dev->offload_fwd_mark. If the skb->offload_fwd_mark 289is non-zero and matches the forwarding egress port's dev->skb_mark, the kernel 290will drop the skb right before transmit on the egress port, with the 291understanding that the device already forwarded the packet on same egress port. 292The driver can use switchdev_port_fwd_mark_set() to set a globally unique mark 293for port's dev->offload_fwd_mark, based on the port's parent ID (switch ID) and 294a group ifindex. 295 296It is possible for the switch device to not handle flooding and push the 297packets up to the bridge driver for flooding. This is not ideal as the number 298of ports scale in the L2 domain as the device is much more efficient at 299flooding packets that software. 300 301If supported by the device, flood control can be offloaded to it, preventing 302certain netdevs from flooding unicast traffic for which there is no FDB entry. 303 304IGMP Snooping 305^^^^^^^^^^^^^ 306 307XXX: complete this section 308 309 310L3 Routing Offload 311------------------ 312 313Offloading L3 routing requires that device be programmed with FIB entries from 314the kernel, with the device doing the FIB lookup and forwarding. The device 315does a longest prefix match (LPM) on FIB entries matching route prefix and 316forwards the packet to the matching FIB entry's nexthop(s) egress ports. 317 318To program the device, the driver implements support for 319SWITCHDEV_OBJ_IPV[4|6]_FIB object using switchdev_port_obj_xxx ops. 320switchdev_port_obj_add is used for both adding a new FIB entry to the device, 321or modifying an existing entry on the device. 322 323XXX: Currently, only SWITCHDEV_OBJ_ID_IPV4_FIB objects are supported. 324 325SWITCHDEV_OBJ_ID_IPV4_FIB object passes: 326 327 struct switchdev_obj_ipv4_fib { /* IPV4_FIB */ 328 u32 dst; 329 int dst_len; 330 struct fib_info *fi; 331 u8 tos; 332 u8 type; 333 u32 nlflags; 334 u32 tb_id; 335 } ipv4_fib; 336 337to add/modify/delete IPv4 dst/dest_len prefix on table tb_id. The *fi 338structure holds details on the route and route's nexthops. *dev is one of the 339port netdevs mentioned in the routes next hop list. If the output port netdevs 340referenced in the route's nexthop list don't all have the same switch ID, the 341driver is not called to add/modify/delete the FIB entry. 342 343Routes offloaded to the device are labeled with "offload" in the ip route 344listing: 345 346 $ ip route show 347 default via 192.168.0.2 dev eth0 348 11.0.0.0/30 dev sw1p1 proto kernel scope link src 11.0.0.2 offload 349 11.0.0.4/30 via 11.0.0.1 dev sw1p1 proto zebra metric 20 offload 350 11.0.0.8/30 dev sw1p2 proto kernel scope link src 11.0.0.10 offload 351 11.0.0.12/30 via 11.0.0.9 dev sw1p2 proto zebra metric 20 offload 352 12.0.0.2 proto zebra metric 30 offload 353 nexthop via 11.0.0.1 dev sw1p1 weight 1 354 nexthop via 11.0.0.9 dev sw1p2 weight 1 355 12.0.0.3 via 11.0.0.1 dev sw1p1 proto zebra metric 20 offload 356 12.0.0.4 via 11.0.0.9 dev sw1p2 proto zebra metric 20 offload 357 192.168.0.0/24 dev eth0 proto kernel scope link src 192.168.0.15 358 359XXX: add/mod/del IPv6 FIB API 360 361Nexthop Resolution 362^^^^^^^^^^^^^^^^^^ 363 364The FIB entry's nexthop list contains the nexthop tuple (gateway, dev), but for 365the switch device to forward the packet with the correct dst mac address, the 366nexthop gateways must be resolved to the neighbor's mac address. Neighbor mac 367address discovery comes via the ARP (or ND) process and is available via the 368arp_tbl neighbor table. To resolve the routes nexthop gateways, the driver 369should trigger the kernel's neighbor resolution process. See the rocker 370driver's rocker_port_ipv4_resolve() for an example. 371 372The driver can monitor for updates to arp_tbl using the netevent notifier 373NETEVENT_NEIGH_UPDATE. The device can be programmed with resolved nexthops 374for the routes as arp_tbl updates. The driver implements ndo_neigh_destroy 375to know when arp_tbl neighbor entries are purged from the port. 376 377Transaction item queue 378^^^^^^^^^^^^^^^^^^^^^^ 379 380For switchdev ops attr_set and obj_add, there is a 2 phase transaction model 381used. First phase is to "prepare" anything needed, including various checks, 382memory allocation, etc. The goal is to handle the stuff that is not unlikely 383to fail here. The second phase is to "commit" the actual changes. 384 385Switchdev provides an inftrastructure for sharing items (for example memory 386allocations) between the two phases. 387 388The object created by a driver in "prepare" phase and it is queued up by: 389switchdev_trans_item_enqueue() 390During the "commit" phase, the driver gets the object by: 391switchdev_trans_item_dequeue() 392 393If a transaction is aborted during "prepare" phase, switchdev code will handle 394cleanup of the queued-up objects. 395