[ovs-dev] [PATCH v1] doc: Add "Representors" topic document

Ian Stokes ian.stokes at intel.com
Tue Feb 12 17:17:12 UTC 2019


On 2/12/2019 1:15 PM, Ilya Maximets wrote:
> On 11.02.2019 3:01, Ophir Munk wrote:
>> This details how to configure representors ports.
>>
>> Signed-off-by: Ophir Munk <ophirmu at mellanox.com>
>> ---
>>   Documentation/topics/dpdk/phy.rst | 80 +++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 80 insertions(+)
>>
>> diff --git a/Documentation/topics/dpdk/phy.rst b/Documentation/topics/dpdk/phy.rst
>> index 1470623..3792fde 100644
>> --- a/Documentation/topics/dpdk/phy.rst
>> +++ b/Documentation/topics/dpdk/phy.rst
>> @@ -219,6 +219,86 @@ For more information please refer to the `DPDK Port Hotplug Framework`__.
>>   
>>   __ http://dpdk.org/doc/guides/prog_guide/port_hotplug_framework.html#hotplug
>>   
>> +.. _representors:
>> +
>> +Representors
>> +------------
>> +
>> +DPDK representors enable configuring a phy port to a guest (VM) machine.
>> +
>> +OVS resides in the hypervisor which has one or more physical interfaces also
>> +known as the physical functions (PFs). If a PF supports SR-IOV it can be used
>> +to enable communication with the VMs via Virtual Functions (VFs).
>> +The VFs are virtual PCIe devices created from the physical Ethernet controller.
>> +
>> +DPDK models a physical interface as a rte device on top of which an eth
>> +device is created.
>> +DPDK (version 18.xx) introduced the representors eth devices.
>> +A representor device represents the VF eth device (VM side) on the hypervisor
>> +side and operates on top of a PF.
>> +Representors are multi devices created on top of one PF.
>> +
>> +For more information, refer to the `DPDK documentation`__.
>> +
>> +__ https://doc.dpdk.org/guides-18.11/prog_guide/switch_representation.html
>> +
>> +Prior to port representors there was a one-to-one relationship between the PF
>> +and the eth device. With port representors the relationship becomes one PF to
>> +many eth devices.
>> +In case of two representors ports, when one of the ports is closed - the PCI
>> +bus cannot be detached until the second representor port is closed as well.
>> +
>> +.. _representors-configuration:
>> +
>> +When configuring a PF-based port, OVS traditionally assigns the device PCI
>> +address in devargs. For an existing bridge called ``br0`` and PCI address
>> +``0000:08:00.0`` an ``add-port`` command is written as::
>> +
>> +    $ ovs-vsctl add-port br0 dpdk-pf -- set Interface dpdk-pf type=dpdk \
>> +       options:dpdk-devargs=0000:08:00.0
>> +
>> +When configuring a VF-based port, DPDK uses an extended devargs syntax which
>> +has the following format::
>> +
>> +    BDBF,representor=[<representor id>]
>> +
>> +This syntax shows that a representor is an enumerated eth device (with
>> +a representor ID) which uses the PF PCI address.
>> +The following commands add representors 3 and 5 using PCI device address
>> +``0000:08:00.0``::
>> +
>> +    $ ovs-vsctl add-port br0 dpdk-rep3 -- set Interface dpdk-rep3 type=dpdk \
>> +       options:dpdk-devargs=0000:08:00.0,representor=[3]
>> +
>> +    $ ovs-vsctl add-port br0 dpdk-rep5 -- set Interface dpdk-rep5 type=dpdk \
>> +       options:dpdk-devargs=0000:08:00.0,representor=[5]
>> +
>> +.. important::
>> +
>> +   Representors ports are configured prior to OVS invocation and independently
>> +   of it, or by other means as well. Please consult a NIC vendor instructions
>> +   on how to establish representors.
> 
> It'll be good to have configuration example for at least one commonly used NIC
> (ixgbe/i40e ?). Or maybe a link to the docs where the process described.
> 
> What do you think ?
> Ian, maybe you could add some example, since you have already tried it in practice?
> 

Good call, I'll draw up an incremental and post here, if acceptable we 
can roll it into the same patch.

Ian
>> To verify their correct configuration,
>> +   execute::
>> +
>> +    $ ovs-vsctl show
>> +
>> +   and make sure no errors are indicated.
>> +
>> +.. _multi-dev-configuration:
>> +
>> +
>> +Port representors are an example of multi devices. There are NICs which support
>> +multi devices by other methods than representors for which a generic devargs
>> +syntax is used. The generic syntax is based on the device mac address::
>> +
>> +    class=eth,mac=<MAC address>
>> +
>> +For example, the following command adds a port to a bridge called ``br0`` using
>> +an eth device whose mac address is ``00:11:22:33:44:55``::
>> +
>> +    $ ovs-vsctl add-port br0 dpdk-mac -- set Interface dpdk-mac type=dpdk \
>> +       options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55"
>> +
>>   Jumbo Frames
>>   ------------
>>   
>>



More information about the dev mailing list