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-
42 -----------
44 This document uses the term "switchdev function" to refer to the PCIe function
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
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
111    through a virtual switch port, even if they do not have a corresponding PCIe
117 It is a common misunderstanding to conflate virtual ports with PCIe virtual
121 A PCIe function which does not have network access through the internal switch
127 The representor represents the virtual port, not the PCIe function nor the 'end
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
161 --------------------------------
163 The representor netdevice should *not* directly refer to a PCIe device (e.g.
164 through ``net_dev->dev.parent`` / ``SET_NETDEV_DEV()``), either of the
172 :ref:`Documentation/networking/devlink/devlink-port.rst <devlink_port>` for the
181 correspond to PCIe functions (e.g. accelerators and plugins).
184 -------------------------------------------
202         action mirred egress mirror dev $REP_DEV
208 trigger the TC rule again and mirror the packet to ``REP_DEV``.)
213 Of course the rules can (if supported by the NIC) include packet-modifying
246 ---------------------------------
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>`)