€•<¿Œsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œtranslations”Œ LanguagesNode”“”)”}”(hhh]”(hŒpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ+/translations/zh_CN/networking/representors”Œmodname”NŒ classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/zh_TW/networking/representors”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/it_IT/networking/representors”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/ja_JP/networking/representors”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/ko_KR/networking/representors”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/pt_BR/networking/representors”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh–sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/sp_SP/networking/representors”Œmodname”NŒ classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh·sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1hµhhh²hh³ŒE/var/lib/git/docbuild/linux/Documentation/networking/representors.rst”h´KubhŒtarget”“”)”}”(hŒ.. _representors:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œrepresentors”uh1hÈh´Khhh²hh³hÇubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒNetwork Function Representors”h]”hŒNetwork Function Representors”…””}”(hhÝh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhhØh²hh³hÇh´KubhŒ paragraph”“”)”}”(hXThis document describes the semantics and usage of representor netdevices, as used to control internal switching on SmartNICs. For the closely-related port representors on physical (multi-port) switches, see :ref:`Documentation/networking/switchdev.rst `.”h]”(hŒÑThis document describes the semantics and usage of representor netdevices, as used to control internal switching on SmartNICs. For the closely-related port representors on physical (multi-port) switches, see ”…””}”(hhíh²hh³Nh´Nubh)”}”(hŒ9:ref:`Documentation/networking/switchdev.rst `”h]”hŒinline”“”)”}”(hh÷h]”hŒ&Documentation/networking/switchdev.rst”…””}”(hhûh²hh³Nh´Nubah}”(h]”h ]”(Œxref”Œstd”Œstd-ref”eh"]”h$]”h&]”uh1hùhhõubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”Œnetworking/representors”Œ refdomain”jŒreftype”Œref”Œrefexplicit”ˆŒrefwarn”ˆŒ reftarget”Œ switchdev”uh1hh³hÇh´KhhíubhŒ.”…””}”(hhíh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KhhØh²hubh×)”}”(hhh]”(hÜ)”}”(hŒ Motivation”h]”hŒ Motivation”…””}”(hj'h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhj$h²hh³hÇh´Kubhì)”}”(hX“Since the mid-2010s, network cards have started offering more complex virtualisation capabilities than the legacy SR-IOV approach (with its simple MAC/VLAN-based switching model) can support. This led to a desire to offload software-defined networks (such as OpenVSwitch) to these NICs to specify the network connectivity of each function. The resulting designs are variously called SmartNICs or DPUs.”h]”hX“Since the mid-2010s, network cards have started offering more complex virtualisation capabilities than the legacy SR-IOV approach (with its simple MAC/VLAN-based switching model) can support. This led to a desire to offload software-defined networks (such as OpenVSwitch) to these NICs to specify the network connectivity of each function. The resulting designs are variously called SmartNICs or DPUs.”…””}”(hj5h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Khj$h²hubhì)”}”(hX_Network function representors bring the standard Linux networking stack to virtual switches and IOV devices. Just as each physical port of a Linux- controlled switch has a separate netdev, so does each virtual port of a virtual switch. When the system boots, and before any offload is configured, all packets from the virtual functions appear in the networking stack of the PF via the representors. The PF can thus always communicate freely with the virtual functions. The PF can configure standard Linux forwarding between representors, the uplink or any other netdev (routing, bridging, TC classifiers).”h]”hX_Network function representors bring the standard Linux networking stack to virtual switches and IOV devices. Just as each physical port of a Linux- controlled switch has a separate netdev, so does each virtual port of a virtual switch. When the system boots, and before any offload is configured, all packets from the virtual functions appear in the networking stack of the PF via the representors. The PF can thus always communicate freely with the virtual functions. The PF can configure standard Linux forwarding between representors, the uplink or any other netdev (routing, bridging, TC classifiers).”…””}”(hjCh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Khj$h²hubhì)”}”(hX™Thus, a representor is both a control plane object (representing the function in administrative commands) and a data plane object (one end of a virtual pipe). As a virtual link endpoint, the representor can be configured like any other netdevice; in some cases (e.g. link state) the representee will follow the representor's configuration, while in others there are separate APIs to configure the representee.”h]”hX›Thus, a representor is both a control plane object (representing the function in administrative commands) and a data plane object (one end of a virtual pipe). As a virtual link endpoint, the representor can be configured like any other netdevice; in some cases (e.g. link state) the representee will follow the representorâ€™s configuration, while in others there are separate APIs to configure the representee.”…””}”(hjQh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K"hj$h²hubeh}”(h]”Œ motivation”ah ]”h"]”Œ motivation”ah$]”h&]”uh1hÖhhØh²hh³hÇh´Kubh×)”}”(hhh]”(hÜ)”}”(hŒDefinitions”h]”hŒDefinitions”…””}”(hjjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhjgh²hh³hÇh´K*ubhì)”}”(hXäThis document uses the term "switchdev function" to refer to the PCIe function which has administrative control over the virtual switch on the device. Typically, this will be a PF, but conceivably a NIC could be configured to grant these administrative privileges instead to a VF or SF (subfunction). Depending on NIC design, a multi-port NIC might have a single switchdev function for the whole device or might have a separate virtual switch, and hence switchdev function, for each physical network port. If the NIC supports nested switching, there might be separate switchdev functions for each nested switch, in which case each switchdev function should only create representors for the ports on the (sub-)switch it directly administers.”h]”hXèThis document uses the term â€œswitchdev functionâ€ to refer to the PCIe function which has administrative control over the virtual switch on the device. Typically, this will be a PF, but conceivably a NIC could be configured to grant these administrative privileges instead to a VF or SF (subfunction). Depending on NIC design, a multi-port NIC might have a single switchdev function for the whole device or might have a separate virtual switch, and hence switchdev function, for each physical network port. If the NIC supports nested switching, there might be separate switchdev functions for each nested switch, in which case each switchdev function should only create representors for the ports on the (sub-)switch it directly administers.”…””}”(hjxh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K,hjgh²hubhì)”}”(hŒ–A "representee" is the object that a representor represents. So for example in the case of a VF representor, the representee is the corresponding VF.”h]”hŒšA â€œrepresenteeâ€ is the object that a representor represents. So for example in the case of a VF representor, the representee is the corresponding VF.”…””}”(hj†h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K8hjgh²hubeh}”(h]”Œdefinitions”ah ]”h"]”Œdefinitions”ah$]”h&]”uh1hÖhhØh²hh³hÇh´K*ubh×)”}”(hhh]”(hÜ)”}”(hŒWhat does a representor do?”h]”hŒWhat does a representor do?”…””}”(hjŸh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhjœh²hh³hÇh´Khjœh²hubhŒenumerated_list”“”)”}”(hhh]”(hŒ list_item”“”)”}”(hŒßIt is used to configure the network connection the representee sees, e.g. link up/down, MTU, etc. For instance, bringing the representor administratively UP should cause the representee to see a link up / carrier on event.”h]”hì)”}”(hŒßIt is used to configure the network connection the representee sees, e.g. link up/down, MTU, etc. For instance, bringing the representor administratively UP should cause the representee to see a link up / carrier on event.”h]”hŒßIt is used to configure the network connection the representee sees, e.g. link up/down, MTU, etc. For instance, bringing the representor administratively UP should cause the representee to see a link up / carrier on event.”…””}”(hjÆh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K@hjÂubah}”(h]”h ]”h"]”h$]”h&]”uh1jÀhj½h²hh³hÇh´NubjÁ)”}”(hXUIt provides the slow path for traffic which does not hit any offloaded fast-path rules in the virtual switch. Packets transmitted on the representor netdevice should be delivered to the representee; packets transmitted by the representee which fail to match any switching rule should be received on the representor netdevice. (That is, there is a virtual pipe connecting the representor to the representee, similar in concept to a veth pair.) This allows software switch implementations (such as OpenVSwitch or a Linux bridge) to forward packets between representees and the rest of the network.”h]”hì)”}”(hXUIt provides the slow path for traffic which does not hit any offloaded fast-path rules in the virtual switch. Packets transmitted on the representor netdevice should be delivered to the representee; packets transmitted by the representee which fail to match any switching rule should be received on the representor netdevice. (That is, there is a virtual pipe connecting the representor to the representee, similar in concept to a veth pair.) This allows software switch implementations (such as OpenVSwitch or a Linux bridge) to forward packets between representees and the rest of the network.”h]”hXUIt provides the slow path for traffic which does not hit any offloaded fast-path rules in the virtual switch. Packets transmitted on the representor netdevice should be delivered to the representee; packets transmitted by the representee which fail to match any switching rule should be received on the representor netdevice. (That is, there is a virtual pipe connecting the representor to the representee, similar in concept to a veth pair.) This allows software switch implementations (such as OpenVSwitch or a Linux bridge) to forward packets between representees and the rest of the network.”…””}”(hjÞh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KDhjÚubah}”(h]”h ]”h"]”h$]”h&]”uh1jÀhj½h²hh³hÇh´NubjÁ)”}”(hŒ†It acts as a handle by which switching rules (such as TC filters) can refer to the representee, allowing these rules to be offloaded. ”h]”hì)”}”(hŒ…It acts as a handle by which switching rules (such as TC filters) can refer to the representee, allowing these rules to be offloaded.”h]”hŒ…It acts as a handle by which switching rules (such as TC filters) can refer to the representee, allowing these rules to be offloaded.”…””}”(hjöh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KMhjòubah}”(h]”h ]”h"]”h$]”h&]”uh1jÀhj½h²hh³hÇh´Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1j»hjœh²hh³hÇh´K@ubhì)”}”(hXÊThe combination of 2) and 3) means that the behaviour (apart from performance) should be the same whether a TC filter is offloaded or not. E.g. a TC rule on a VF representor applies in software to packets received on that representor netdevice, while in hardware offload it would apply to packets transmitted by the representee VF. Conversely, a mirred egress redirect to a VF representor corresponds in hardware to delivery directly to the representee VF.”h]”hXÊThe combination of 2) and 3) means that the behaviour (apart from performance) should be the same whether a TC filter is offloaded or not. E.g. a TC rule on a VF representor applies in software to packets received on that representor netdevice, while in hardware offload it would apply to packets transmitted by the representee VF. Conversely, a mirred egress redirect to a VF representor corresponds in hardware to delivery directly to the representee VF.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KPhjœh²hubeh}”(h]”Œwhat-does-a-representor-do”ah ]”h"]”Œwhat does a representor do?”ah$]”h&]”uh1hÖhhØh²hh³hÇh´Kdev.parent`` / ``SET_NETDEV_DEV()``), either of the representee or of the switchdev function. Instead, the driver should use the ``SET_NETDEV_DEVLINK_PORT`` macro to assign a devlink port instance to the netdevice before registering the netdevice; the kernel uses the devlink port to provide the ``phys_switch_id`` and ``phys_port_name`` sysfs nodes. (Some legacy drivers implement ``ndo_get_port_parent_id()`` and ``ndo_get_phys_port_name()`` directly, but this is deprecated.) See :ref:`Documentation/networking/devlink/devlink-port.rst ` for the details of this API.”h]”(hŒ!The representor netdevice should ”…””}”(hjh²hh³Nh´Nubj/)”}”(hŒ*not*”h]”hŒnot”…””}”(hj$h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j.hjubhŒ/ directly refer to a PCIe device (e.g. through ”…””}”(hjh²hh³Nh´NubjÊ)”}”(hŒ``net_dev->dev.parent``”h]”hŒnet_dev->dev.parent”…””}”(hj6h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjubhŒ / ”…””}”(hjh²hh³Nh´NubjÊ)”}”(hŒ``SET_NETDEV_DEV()``”h]”hŒSET_NETDEV_DEV()”…””}”(hjHh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjubhŒ^), either of the representee or of the switchdev function. Instead, the driver should use the ”…””}”(hjh²hh³Nh´NubjÊ)”}”(hŒ``SET_NETDEV_DEVLINK_PORT``”h]”hŒSET_NETDEV_DEVLINK_PORT”…””}”(hjZh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjubhŒŒ macro to assign a devlink port instance to the netdevice before registering the netdevice; the kernel uses the devlink port to provide the ”…””}”(hjh²hh³Nh´NubjÊ)”}”(hŒ``phys_switch_id``”h]”hŒphys_switch_id”…””}”(hjlh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjubhŒ and ”…””}”(hjh²hh³Nh´NubjÊ)”}”(hŒ``phys_port_name``”h]”hŒphys_port_name”…””}”(hj~h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjubhŒ- sysfs nodes. (Some legacy drivers implement ”…””}”(hjh²hh³Nh´NubjÊ)”}”(hŒ``ndo_get_port_parent_id()``”h]”hŒndo_get_port_parent_id()”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjubhŒ and ”…””}”(hjh²hh³Nh´NubjÊ)”}”(hŒ``ndo_get_phys_port_name()``”h]”hŒndo_get_phys_port_name()”…””}”(hj¢h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjubhŒ) directly, but this is deprecated.) See ”…””}”(hjh²hh³Nh´Nubh)”}”(hŒG:ref:`Documentation/networking/devlink/devlink-port.rst `”h]”hú)”}”(hj¶h]”hŒ1Documentation/networking/devlink/devlink-port.rst”…””}”(hj¸h²hh³Nh´Nubah}”(h]”h ]”(jŒstd”Œstd-ref”eh"]”h$]”h&]”uh1hùhj´ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”jŒ refdomain”jÂŒreftype”Œref”Œrefexplicit”ˆŒrefwarn”ˆjŒdevlink_port”uh1hh³hÇh´K£hjubhŒ for the details of this API.”…””}”(hjh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K£hjh²hubhì)”}”(hX0It is expected that userland will use this information (e.g. through udev rules) to construct an appropriately informative name or alias for the netdevice. For instance if the switchdev function is ``eth4`` then a representor with a ``phys_port_name`` of ``p0pf1vf2`` might be renamed ``eth4pf1vf2rep``.”h]”(hŒÇIt is expected that userland will use this information (e.g. through udev rules) to construct an appropriately informative name or alias for the netdevice. For instance if the switchdev function is ”…””}”(hjÞh²hh³Nh´NubjÊ)”}”(hŒ``eth4``”h]”hŒeth4”…””}”(hjæh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjÞubhŒ then a representor with a ”…””}”(hjÞh²hh³Nh´NubjÊ)”}”(hŒ``phys_port_name``”h]”hŒphys_port_name”…””}”(hjøh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjÞubhŒ of ”…””}”(hjÞh²hh³Nh´NubjÊ)”}”(hŒ``p0pf1vf2``”h]”hŒp0pf1vf2”…””}”(hj h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjÞubhŒ might be renamed ”…””}”(hjÞh²hh³Nh´NubjÊ)”}”(hŒ``eth4pf1vf2rep``”h]”hŒ eth4pf1vf2rep”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjÞubhŒ.”…””}”(hjÞh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K¯hjh²hubhì)”}”(hŒŽThere are as yet no established conventions for naming representors which do not correspond to PCIe functions (e.g. accelerators and plugins).”h]”hŒŽThere are as yet no established conventions for naming representors which do not correspond to PCIe functions (e.g. accelerators and plugins).”…””}”(hj4h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K´hjh²hubeh}”(h]”Œhow-are-representors-identified”ah ]”h"]”Œ how are representors identified?”ah$]”h&]”uh1hÖhhØh²hh³hÇh´K¡ubh×)”}”(hhh]”(hÜ)”}”(hŒ+How do representors interact with TC rules?”h]”hŒ+How do representors interact with TC rules?”…””}”(hjMh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhjJh²hh³hÇh´K¸ubhì)”}”(hX+Any TC rule on a representor applies (in software TC) to packets received by that representor netdevice. Thus, if the delivery part of the rule corresponds to another port on the virtual switch, the driver may choose to offload it to hardware, applying it to packets transmitted by the representee.”h]”hX+Any TC rule on a representor applies (in software TC) to packets received by that representor netdevice. Thus, if the delivery part of the rule corresponds to another port on the virtual switch, the driver may choose to offload it to hardware, applying it to packets transmitted by the representee.”…””}”(hj[h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KºhjJh²hubhì)”}”(hŒüSimilarly, since a TC mirred egress action targeting the representor would (in software) send the packet through the representor (and thus indirectly deliver it to the representee), hardware offload should interpret this as delivery to the representee.”h]”hŒüSimilarly, since a TC mirred egress action targeting the representor would (in software) send the packet through the representor (and thus indirectly deliver it to the representee), hardware offload should interpret this as delivery to the representee.”…””}”(hjih²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K¿hjJh²hubhì)”}”(hŒ€As a simple example, if ``PORT_DEV`` is the physical port representor and ``REP_DEV`` is a VF representor, the following rules::”h]”(hŒAs a simple example, if ”…””}”(hjwh²hh³Nh´NubjÊ)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjwubhŒ& is the physical port representor and ”…””}”(hjwh²hh³Nh´NubjÊ)”}”(hŒ``REP_DEV``”h]”hŒREP_DEV”…””}”(hj‘h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjwubhŒ* is a VF representor, the following rules:”…””}”(hjwh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KÄhjJh²hubhŒ literal_block”“”)”}”(hŒãtc filter add dev $REP_DEV parent ffff: protocol ipv4 flower \ action mirred egress redirect dev $PORT_DEV tc filter add dev $PORT_DEV parent ffff: protocol ipv4 flower skip_sw \ action mirred egress mirror dev $REP_DEV”h]”hŒãtc filter add dev $REP_DEV parent ffff: protocol ipv4 flower \ action mirred egress redirect dev $PORT_DEV tc filter add dev $PORT_DEV parent ffff: protocol ipv4 flower skip_sw \ action mirred egress mirror dev $REP_DEV”…””}”hj«sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1j©h³hÇh´KÇhjJh²hubhì)”}”(hXtwould mean that all IPv4 packets from the VF are sent out the physical port, and all IPv4 packets received on the physical port are delivered to the VF in addition to ``PORT_DEV``. (Note that without ``skip_sw`` on the second rule, the VF would get two copies, as the packet reception on ``PORT_DEV`` would trigger the TC rule again and mirror the packet to ``REP_DEV``.)”h]”(hŒ§would mean that all IPv4 packets from the VF are sent out the physical port, and all IPv4 packets received on the physical port are delivered to the VF in addition to ”…””}”(hj¹h²hh³Nh´NubjÊ)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hjÁh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhj¹ubhŒ. (Note that without ”…””}”(hj¹h²hh³Nh´NubjÊ)”}”(hŒ``skip_sw``”h]”hŒskip_sw”…””}”(hjÓh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhj¹ubhŒM on the second rule, the VF would get two copies, as the packet reception on ”…””}”(hj¹h²hh³Nh´NubjÊ)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hjåh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhj¹ubhŒ: would trigger the TC rule again and mirror the packet to ”…””}”(hj¹h²hh³Nh´NubjÊ)”}”(hŒ``REP_DEV``”h]”hŒREP_DEV”…””}”(hj÷h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhj¹ubhŒ.)”…””}”(hj¹h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KÌhjJh²hubhì)”}”(hŒ†On devices without separate port and uplink representors, ``PORT_DEV`` would instead be the switchdev function's own uplink netdevice.”h]”(hŒ:On devices without separate port and uplink representors, ”…””}”(hjh²hh³Nh´NubjÊ)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjubhŒB would instead be the switchdev functionâ€™s own uplink netdevice.”…””}”(hjh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KÒhjJh²hubhì)”}”(hŒ™Of course the rules can (if supported by the NIC) include packet-modifying actions (e.g. VLAN push/pop), which should be performed by the virtual switch.”h]”hŒ™Of course the rules can (if supported by the NIC) include packet-modifying actions (e.g. VLAN push/pop), which should be performed by the virtual switch.”…””}”(hj/h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KÕhjJh²hubhì)”}”(hXpTunnel encapsulation and decapsulation are rather more complicated, as they involve a third netdevice (a tunnel netdev operating in metadata mode, such as a VxLAN device created with ``ip link add vxlan0 type vxlan external``) and require an IP address to be bound to the underlay device (e.g. switchdev function uplink netdev or port representor). TC rules such as::”h]”(hŒ·Tunnel encapsulation and decapsulation are rather more complicated, as they involve a third netdevice (a tunnel netdev operating in metadata mode, such as a VxLAN device created with ”…””}”(hj=h²hh³Nh´NubjÊ)”}”(hŒ*``ip link add vxlan0 type vxlan external``”h]”hŒ&ip link add vxlan0 type vxlan external”…””}”(hjEh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhj=ubhŒŽ) and require an IP address to be bound to the underlay device (e.g. switchdev function uplink netdev or port representor). TC rules such as:”…””}”(hj=h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KØhjJh²hubjª)”}”(hX—tc filter add dev $REP_DEV parent ffff: flower \ action tunnel_key set id $VNI src_ip $LOCAL_IP dst_ip $REMOTE_IP \ dst_port 4789 \ action mirred egress redirect dev vxlan0 tc filter add dev vxlan0 parent ffff: flower enc_src_ip $REMOTE_IP \ enc_dst_ip $LOCAL_IP enc_key_id $VNI enc_dst_port 4789 \ action tunnel_key unset action mirred egress redirect dev $REP_DEV”h]”hX—tc filter add dev $REP_DEV parent ffff: flower \ action tunnel_key set id $VNI src_ip $LOCAL_IP dst_ip $REMOTE_IP \ dst_port 4789 \ action mirred egress redirect dev vxlan0 tc filter add dev vxlan0 parent ffff: flower enc_src_ip $REMOTE_IP \ enc_dst_ip $LOCAL_IP enc_key_id $VNI enc_dst_port 4789 \ action tunnel_key unset action mirred egress redirect dev $REP_DEV”…””}”hj]sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1j©h³hÇh´KÞhjJh²hubhì)”}”(hXCwhere ``LOCAL_IP`` is an IP address bound to ``PORT_DEV``, and ``REMOTE_IP`` is another IP address on the same subnet, mean that packets sent by the VF should be VxLAN encapsulated and sent out the physical port (the driver has to deduce this by a route lookup of ``LOCAL_IP`` leading to ``PORT_DEV``, and also perform an ARP/neighbour table lookup to find the MAC addresses to use in the outer Ethernet frame), while UDP packets received on the physical port with UDP port 4789 should be parsed as VxLAN and, if their VSID matches ``$VNI``, decapsulated and forwarded to the VF.”h]”(hŒwhere ”…””}”(hjkh²hh³Nh´NubjÊ)”}”(hŒ``LOCAL_IP``”h]”hŒLOCAL_IP”…””}”(hjsh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjkubhŒ is an IP address bound to ”…””}”(hjkh²hh³Nh´NubjÊ)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hj…h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjkubhŒ, and ”…””}”(hjkh²hh³Nh´NubjÊ)”}”(hŒ ``REMOTE_IP``”h]”hŒ REMOTE_IP”…””}”(hj—h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjkubhŒ¼ is another IP address on the same subnet, mean that packets sent by the VF should be VxLAN encapsulated and sent out the physical port (the driver has to deduce this by a route lookup of ”…””}”(hjkh²hh³Nh´NubjÊ)”}”(hŒ``LOCAL_IP``”h]”hŒLOCAL_IP”…””}”(hj©h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjkubhŒ leading to ”…””}”(hjkh²hh³Nh´NubjÊ)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hj»h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjkubhŒè, and also perform an ARP/neighbour table lookup to find the MAC addresses to use in the outer Ethernet frame), while UDP packets received on the physical port with UDP port 4789 should be parsed as VxLAN and, if their VSID matches ”…””}”(hjkh²hh³Nh´NubjÊ)”}”(hŒ``$VNI``”h]”hŒ$VNI”…””}”(hjÍh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjkubhŒ', decapsulated and forwarded to the VF.”…””}”(hjkh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KæhjJh²hubhì)”}”(hX]If this all seems complicated, just remember the 'golden rule' of TC offload: the hardware should ensure the same final results as if the packets were processed through the slow path, traversed software TC (except ignoring any ``skip_hw`` rules and applying any ``skip_sw`` rules) and were transmitted or received through the representor netdevices.”h]”(hŒçIf this all seems complicated, just remember the â€˜golden ruleâ€™ of TC offload: the hardware should ensure the same final results as if the packets were processed through the slow path, traversed software TC (except ignoring any ”…””}”(hjåh²hh³Nh´NubjÊ)”}”(hŒ``skip_hw``”h]”hŒskip_hw”…””}”(hjíh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjåubhŒ rules and applying any ”…””}”(hjåh²hh³Nh´NubjÊ)”}”(hŒ``skip_sw``”h]”hŒskip_sw”…””}”(hjÿh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjåubhŒL rules) and were transmitted or received through the representor netdevices.”…””}”(hjåh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KïhjJh²hubeh}”(h]”Œ*how-do-representors-interact-with-tc-rules”ah ]”h"]”Œ+how do representors interact with tc rules?”ah$]”h&]”uh1hÖhhØh²hh³hÇh´K¸ubh×)”}”(hhh]”(hÜ)”}”(hŒ!Configuring the representee's MAC”h]”hŒ#Configuring the representeeâ€™s MAC”…””}”(hj"h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhjh²hh³hÇh´Köubhì)”}”(hŒ«The representee's link state is controlled through the representor. Setting the representor administratively UP or DOWN should cause carrier ON or OFF at the representee.”h]”hŒThe representeeâ€™s link state is controlled through the representor. Setting the representor administratively UP or DOWN should cause carrier ON or OFF at the representee.”…””}”(hj0h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Køhjh²hubhì)”}”(hŒþSetting an MTU on the representor should cause that same MTU to be reported to the representee. (On hardware that allows configuring separate and distinct MTU and MRU values, the representor MTU should correspond to the representee's MRU and vice-versa.)”h]”hXSetting an MTU on the representor should cause that same MTU to be reported to the representee. (On hardware that allows configuring separate and distinct MTU and MRU values, the representor MTU should correspond to the representeeâ€™s MRU and vice-versa.)”…””}”(hj>h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Kühjh²hubhì)”}”(hŒ™Currently there is no way to use the representor to set the station permanent MAC address of the representee; other methods available to do this include:”h]”hŒ™Currently there is no way to use the representor to set the station permanent MAC address of the representee; other methods available to do this include:”…””}”(hjLh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Mhjh²hubjY)”}”(hŒº- legacy SR-IOV (``ip link set DEVICE vf NUM mac LLADDR``) - devlink port function (see **devlink-port(8)** and :ref:`Documentation/networking/devlink/devlink-port.rst `)”h]”j_)”}”(hhh]”(jÁ)”}”(hŒ8legacy SR-IOV (``ip link set DEVICE vf NUM mac LLADDR``)”h]”hì)”}”(hjch]”(hŒlegacy SR-IOV (”…””}”(hjeh²hh³Nh´NubjÊ)”}”(hŒ(``ip link set DEVICE vf NUM mac LLADDR``”h]”hŒ$ip link set DEVICE vf NUM mac LLADDR”…””}”(hjlh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÉhjeubhŒ)”…””}”(hjeh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Mhjaubah}”(h]”h ]”h"]”h$]”h&]”uh1jÀhj^ubjÁ)”}”(hŒ{devlink port function (see **devlink-port(8)** and :ref:`Documentation/networking/devlink/devlink-port.rst `)”h]”hì)”}”(hŒ{devlink port function (see **devlink-port(8)** and :ref:`Documentation/networking/devlink/devlink-port.rst `)”h]”(hŒdevlink port function (see ”…””}”(hjŽh²hh³Nh´NubhŒstrong”“”)”}”(hŒ**devlink-port(8)**”h]”hŒdevlink-port(8)”…””}”(hj˜h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j–hjŽubhŒ and ”…””}”(hjŽh²hh³Nh´Nubh)”}”(hŒG:ref:`Documentation/networking/devlink/devlink-port.rst `”h]”hú)”}”(hj¬h]”hŒ1Documentation/networking/devlink/devlink-port.rst”…””}”(hj®h²hh³Nh´Nubah}”(h]”h ]”(jŒstd”Œstd-ref”eh"]”h$]”h&]”uh1hùhjªubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”jŒ refdomain”j¸Œreftype”Œref”Œrefexplicit”ˆŒrefwarn”ˆjŒdevlink_port”uh1hh³hÇh´MhjŽubhŒ)”…””}”(hjŽh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´MhjŠubah}”(h]”h ]”h"]”h$]”h&]”uh1jÀhj^ubeh}”(h]”h ]”h"]”h$]”h&]”jjuh1j^h³hÇh´MhjZubah}”(h]”h ]”h"]”h$]”h&]”uh1jXh³hÇh´Mhjh²hubeh}”(h]”Œ!configuring-the-representee-s-mac”ah ]”h"]”Œ!configuring the representee's mac”ah$]”h&]”uh1hÖhhØh²hh³hÇh´Köubeh}”(h]”(Œnetwork-function-representors”hÕeh ]”h"]”(Œnetwork function representors”Œrepresentors”eh$]”h&]”uh1hÖhhh²hh³hÇh´KŒexpect_referenced_by_name”}”jôhÊsŒexpect_referenced_by_id”}”hÕhÊsubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”hÇuh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hÛNŒ generator”NŒ datestamp”NŒsource_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒreport_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jŒerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”hÇŒ_destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”(hÕ]”hÊajÇ]”j·auŒnameids”}”(jôhÕjójðjdjaj™j–j(j%jjªjjjGjDjjjëjèj¥jÇuŒ nametypes”}”(jôˆjó‰jd‰j™‰j(‰j‰j‰jG‰j‰jë‰j¥ˆuh}”(hÕhØjðhØjaj$j–jgj%jœjªj+jÁj·jÇjJjj°jDjjjJjèjuŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”jJaŒautofootnote_refs”]”j·aŒsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œcollections”ŒCounter”“”}”j,Ks…”R”Œparse_messages”]”Œtransform_messages”]”hŒsystem_message”“”)”}”(hhh]”hì)”}”(hhh]”hŒ2Hyperlink target "representors" is not referenced.”…””}”hj‰sbah}”(h]”h ]”h"]”h$]”h&]”uh1hëhj†ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”hÇŒline”Kuh1j„ubaŒtransformer”NŒinclude_log”]”Œ decoration”Nh²hub.