Documentation/networking/representors.rst

1 .. SPDX-License-Identifier: GPL-2.0
8 used to control internal switching on SmartNICs.  For the closely-related port
9 representors on physical (multi-port) switches, see
13 ----------
15 Since the mid-2010s, network cards have started offering more complex
16 virtualisation capabilities than the legacy SR-IOV approach (with its simple
17 MAC/VLAN-based switching model) can support.  This led to a desire to offload
18 software-defined networks (such as OpenVSwitch) to these NICs to specify the
23 virtual switches and IOV devices.  Just as each physical port of a Linux-
35 As a virtual link endpoint, the representor can be configured like any other
36 netdevice; in some cases (e.g. link state) the representee will follow the
41 -----------
47 Depending on NIC design, a multi-port NIC might have a single switchdev function
52 only create representors for the ports on the (sub-)switch it directly
59 ---------------------------
63 1. It is used to configure the network connection the representee sees, e.g.
64    link up/down, MTU, etc.  For instance, bringing the representor
65    administratively UP should cause the representee to see a link up / carrier
68    fast-path rules in the virtual switch.  Packets transmitted on the
80 should be the same whether a TC filter is offloaded or not.  E.g. a TC rule
87 -----------------------------------------
98  - VFs belonging to the switchdev function.
99  - Other PFs on the local PCIe controller, and any VFs belonging to them.
100  - PFs and VFs on external PCIe controllers on the device (e.g. for any embedded
101    System-on-Chip within the SmartNIC).
102  - PFs and VFs with other personalities, including network block devices (such
103    as a vDPA virtio-blk PF backed by remote/distributed storage), if (and only
107  - Subfunctions (SFs) belonging to any of the above PFs or VFs, if they have
109  - Any accelerators or plugins on the device whose interface to the network is
133    e.g. its traffic might all be wrapped in a specific VLAN or VxLAN.  However,
137    Contrast this with the case of a virtio-blk implementation which forwards the
140    run over the virtual switch and the virtio-blk PF should thus *not* have a
144 -----------------------------
147 port on the switch, create a pure-software netdevice which has some form of
148 in-kernel reference to the switchdev function's own netdevice or driver private
160 --------------------------------
162 The representor netdevice should *not* directly refer to a PCIe device (e.g.
163 through ``net_dev->dev.parent`` / ``SET_NETDEV_DEV()``), either of the
171 :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>` for the
174 It is expected that userland will use this information (e.g. through udev rules)
180 correspond to PCIe functions (e.g. accelerators and plugins).
183 -------------------------------------------
212 Of course the rules can (if supported by the NIC) include packet-modifying
213 actions (e.g. VLAN push/pop), which should be performed by the virtual switch.
217 a VxLAN device created with ``ip link add vxlan0 type vxlan external``) and
218 require an IP address to be bound to the underlay device (e.g. switchdev
245 ---------------------------------
247 The representee's link state is controlled through the representor.  Setting the
254 the representor MTU should correspond to the representee's MRU and vice-versa.)
259  - legacy SR-IOV (``ip link set DEVICE vf NUM mac LLADDR``)
260  - devlink port function (see **devlink-port(8)** and
261    :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>`)