Documentation/networking/representors.rst

1 .. SPDX-License-Identifier: GPL-2.0
9 used to control internal switching on SmartNICs.  For the closely-related port
10 representors on physical (multi-port) switches, see
14 ----------
16 Since the mid-2010s, network cards have started offering more complex
17 virtualisation capabilities than the legacy SR-IOV approach (with its simple
18 MAC/VLAN-based switching model) can support.  This led to a desire to offload
19 software-defined networks (such as OpenVSwitch) to these NICs to specify the
24 virtual switches and IOV devices.  Just as each physical port of a Linux-
25 controlled switch has a separate netdev, so does each virtual port of a virtual
42 -----------
48 Depending on NIC design, a multi-port NIC might have a single switchdev function
53 only create representors for the ports on the (sub-)switch it directly
60 ---------------------------
69    fast-path rules in the virtual switch.  Packets transmitted on the
83 netdevice, while in hardware offload it would apply to packets transmitted by
85 corresponds in hardware to delivery directly to the representee VF.
88 -----------------------------------------
99  - VFs belonging to the switchdev function.
100  - Other PFs on the local PCIe controller, and any VFs belonging to them.
101  - PFs and VFs on external PCIe controllers on the device (e.g. for any embedded
102    System-on-Chip within the SmartNIC).
103  - PFs and VFs with other personalities, including network block devices (such
104    as a vDPA virtio-blk PF backed by remote/distributed storage), if (and only
108  - Subfunctions (SFs) belonging to any of the above PFs or VFs, if they have
110  - Any accelerators or plugins on the device whose interface to the network is
114 This allows the entire switching behaviour of the NIC to be controlled through
122 (not even indirectly through the hardware implementation of whatever services
130 .. [#] The concept here is that a hardware IP stack in the device performs the
138    Contrast this with the case of a virtio-blk implementation which forwards the
141    run over the virtual switch and the virtio-blk PF should thus *not* have a
145 -----------------------------
148 port on the switch, create a pure-software netdevice which has some form of
149 in-kernel reference to the switchdev function's own netdevice or driver private
156 the packet through a hardware TX queue attached to the switchdev function, with
161 --------------------------------
164 through ``net_dev->dev.parent`` / ``SET_NETDEV_DEV()``), either of the
172 :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>` for the
184 -------------------------------------------
189 hardware, applying it to packets transmitted by the representee.
193 it to the representee), hardware offload should interpret this as delivery to
213 Of course the rules can (if supported by the NIC) include packet-modifying
240 the hardware should ensure the same final results as if the packets were
246 ---------------------------------
248 The representee's link state is controlled through the representor.  Setting the
254 (On hardware that allows configuring separate and distinct MTU and MRU values,
255 the representor MTU should correspond to the representee's MRU and vice-versa.)
260  - legacy SR-IOV (``ip link set DEVICE vf NUM mac LLADDR``)
261  - devlink port function (see **devlink-port(8)** and
262    :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>`)