€•P¾Œ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Œ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”hòŒ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”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjhž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.”…””}”(hj!hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Khjhž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).”…””}”(hj/hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Khjhž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.”…””}”(hj=hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K"hjhžhubeh}”(h]”Œ motivation”ah ]”h"]”Œ motivation”ah$]”h&]”uh1hÂhhÄhžhhŸh³h KubhÃ)”}”(hhh]”(hÈ)”}”(hŒDefinitions”h]”hŒDefinitions”…””}”(hjVhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjShž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.”…””}”(hjdhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K,hjShž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.”…””}”(hjrhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K8hjShž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”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubhŒ/ directly refer to a PCIe device (e.g. through ”…””}”(hjhžhhŸNh Nubj¶)”}”(hŒ``net_dev->dev.parent``”h]”hŒnet_dev->dev.parent”…””}”(hj"hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjubhŒ / ”…””}”(hjhžhhŸNh Nubj¶)”}”(hŒ``SET_NETDEV_DEV()``”h]”hŒSET_NETDEV_DEV()”…””}”(hj4hž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”…””}”(hjFhž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”…””}”(hjXhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjubhŒ and ”…””}”(hjhžhhŸNh Nubj¶)”}”(hŒ``phys_port_name``”h]”hŒphys_port_name”…””}”(hjjhž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()”…””}”(hj|hž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 ]”(hñŒstd”Œstd-ref”eh"]”h$]”h&]”uh1håhj ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hþŒ 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£hj÷hž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¯hj÷hž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).”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K´hj÷hž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?”…””}”(hj9hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj6hž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.”…””}”(hjGhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Kºhj6hž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.”…””}”(hjUhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K¿hj6hž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 ”…””}”(hjchžhhŸNh Nubj¶)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hjkhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjcubhŒ& is the physical port representor and ”…””}”(hjchžhhŸNh Nubj¶)”}”(hŒ``REP_DEV``”h]”hŒREP_DEV”…””}”(hj}hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjcubhŒ* is a VF representor, the following rules:”…””}”(hjchžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KÄhj6hž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Çhj6hž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”…””}”(hjhž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Ìhj6hž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, ”…””}”(hjûhžhhŸNh Nubj¶)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjûubhŒB would instead be the switchdev functionâ€™s own uplink netdevice.”…””}”(hjûhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KÒhj6hž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.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KÕhj6hž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”…””}”(hj1hž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Øhj6hž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”…””}”hjIsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j•hŸh³h KÞhj6hž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 ”…””}”(hjWhžhhŸNh Nubj¶)”}”(hŒ``LOCAL_IP``”h]”hŒLOCAL_IP”…””}”(hj_hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjWubhŒ is an IP address bound to ”…””}”(hjWhžhhŸNh Nubj¶)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hjqhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjWubhŒ, and ”…””}”(hjWhžhhŸNh Nubj¶)”}”(hŒ ``REMOTE_IP``”h]”hŒ REMOTE_IP”…””}”(hjƒhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjWubhŒ¼ 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 ”…””}”(hjWhžhhŸNh Nubj¶)”}”(hŒ``LOCAL_IP``”h]”hŒLOCAL_IP”…””}”(hj•hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjWubhŒ leading to ”…””}”(hjWhžhhŸNh Nubj¶)”}”(hŒ``PORT_DEV``”h]”hŒPORT_DEV”…””}”(hj§hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjWubhŒè, 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 ”…””}”(hjWhžhhŸNh Nubj¶)”}”(hŒ``$VNI``”h]”hŒ$VNI”…””}”(hj¹hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjWubhŒ', decapsulated and forwarded to the VF.”…””}”(hjWhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Kæhj6hž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ïhj6hž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”…””}”(hjhž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.”…””}”(hjhž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:”…””}”(hj8hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MhjhžhubjE)”}”(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]”jK)”}”(hhh]”(j)”}”(hŒ8legacy SR-IOV (``ip link set DEVICE vf NUM mac LLADDR``)”h]”hØ)”}”(hjOh]”(hŒlegacy SR-IOV (”…””}”(hjQhžhhŸNh Nubj¶)”}”(hŒ(``ip link set DEVICE vf NUM mac LLADDR``”h]”hŒ$ip link set DEVICE vf NUM mac LLADDR”…””}”(hjXhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jµhjQubhŒ)”…””}”(hjQhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h MhjMubah}”(h]”h ]”h"]”h$]”h&]”uh1j¬hjJubj)”}”(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 ”…””}”(hjzhžhhŸNh NubhŒstrong”“”)”}”(hŒ**devlink-port(8)**”h]”hŒdevlink-port(8)”…””}”(hj„hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j‚hjzubhŒ and ”…””}”(hjzhž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 ]”(hñŒstd”Œstd-ref”eh"]”h$]”h&]”uh1håhj–ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hþŒ refdomain”j¤Œreftype”Œref”Œrefexplicit”ˆŒrefwarn”ˆjŒdevlink_port”uh1hhŸh³h MhjzubhŒ)”…””}”(hjzhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h Mhjvubah}”(h]”h ]”h"]”h$]”h&]”uh1j¬hjJubeh}”(h]”h ]”h"]”h$]”h&]”jüjýuh1jJhŸh³h MhjFubah}”(h]”h ]”h"]”h$]”h&]”uh1jDhŸ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ÜjPjMj…j‚jjj™j–jôjñj3j0jjj×jÔj‘j³uŒ nametypes”}”(jàˆjß‰jP‰j…‰j‰j™‰jô‰j3‰j‰j×‰j‘ˆuh}”(hÁhÄjÜhÄjMjj‚jSjjˆj–jjj£j³j6jñjœj0j÷jj6jÔjuŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”j6aŒautofootnote_refs”]”j£aŒsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œcollections”ŒCounter”“”}”jKs…”R”Œparse_messages”]”Œtransform_messages”]”hŒsystem_message”“”)”}”(hhh]”hØ)”}”(hhh]”hŒ2Hyperlink target "representors" is not referenced.”…””}”hjusbah}”(h]”h ]”h"]”h$]”h&]”uh1h×hjrubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h³Œline”Kuh1jpubaŒtransformer”NŒinclude_log”]”Œ decoration”Nhžhub.