Documentation/networking/representors.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/representors.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/representors.rst
Extension
.rst
Size
13745 bytes
Lines
263
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0
.. _representors:

=============================
Network Function Representors
=============================

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
:ref:`Documentation/networking/switchdev.rst <switchdev>`.

Motivation
----------

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.

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).

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.

Definitions
-----------

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.

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.

What does a representor do?
---------------------------

A representor has three main roles.

1. 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.
2. It 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

Annotation

Implementation Notes