[ovs-dev,V4,3/4] INSTALL.DPDK.md: add Jumbo Frames section

Signed-off-by: Mark Kavanagh <mark.b.kavanagh@intel.com>
---
 INSTALL.DPDK.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

On Tue, 16 Feb 2016 11:31:50 +0000
Mark Kavanagh <mark.b.kavanagh@intel.com> wrote:

> Signed-off-by: Mark Kavanagh <mark.b.kavanagh@intel.com>
> ---
>  INSTALL.DPDK.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 59 insertions(+)
> 
> diff --git a/INSTALL.DPDK.md b/INSTALL.DPDK.md
> index 722fb9e..4ca98cb 100644
> --- a/INSTALL.DPDK.md
> +++ b/INSTALL.DPDK.md
> @@ -878,6 +878,60 @@ by adding the following string:
>  to <interface> sections of all network devices used by DPDK. Parameter 'N'
>  determines how many queues can be used by the guest.
>  
> +Jumbo Frames
> +------------
> +
> +Support for Jumbo Frames may be enabled at run-time for DPDK-type ports.
> +
> +To avail of Jumbo Frame support, add the 'mtu_request' option to the ovs-vsctl
> +'add-port' command-line, along with the required MTU for the port.
> +e.g.
> +
> +     ```
> +     ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk options:mtu_request=9000
> +     ```
> +
> +When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments are
> +increased, such that a full Jumbo Frame may be accommodated inside a single
> +mbuf segment. Once set, the MTU for a DPDK port is immutable.
> +
> +Note that from an OVSDB perspective, the `mtu_request` option for a specific
> +port may be disregarded once initially set, as subsequent modifications to this
> +field are disregarded by the DPDK port. As with non-DPDK ports, the MTU of DPDK
> +ports is reported by the `Interface` table's `mtu` field.
> +
> +Jumbo frame support has been validated against 13312B frames, using the
> +DPDK `igb_uio` driver, but larger frames and other DPDK NIC drivers may
> +theoretically be supported. Supported port types excludes vHost-Cuse ports, as
> +that feature is pending deprecation.
> +
> +vHost Ports and Jumbo Frames
> +----------------------------
> +Jumbo frame support is available for DPDK vHost-User ports only. Some additional
> +configuration is needed to take advantage of this feature:
> +
> +  1. `mergeable buffers` must be enabled for vHost ports, as demonstrated in
> +      the QEMU command line snippet below:
> +
> +      ```
> +      '-netdev type=vhost-user,id=mynet1,chardev=char0,vhostforce \'
> +      '-device virtio-net-pci,mac=00:00:00:00:00:01,netdev=mynet1,mrg_rxbuf=on'
> +      ```
> +
> +  2. Where virtio devices are bound to the Linux kernel driver in a guest
> +     environment (i.e. interfaces are not bound to an in-guest DPDK driver), the
> +     MTU of those logical network interfaces must also be increased. This
> +     avoids segmentation of Jumbo Frames in the guest. Note that 'MTU' refers
> +     to the length of the IP packet only, and not that of the entire frame.
> +
> +     e.g. To calculate the exact MTU of a standard IPv4 frame, subtract the L2
> +     header and CRC lengths (i.e. 18B) from the max supported frame size.
> +     So, to set the MTU for a 13312B Jumbo Frame:
> +
> +      ```
> +      ifconfig eth1 mtu 13294
> +      ```
> +
>  Restrictions:
>  -------------
>  
> @@ -921,6 +975,11 @@ Restrictions:
>      the next release of DPDK (which includes the above patch) is available and
>      integrated into OVS.
>  
> +  Jumbo Frames:
> +  - `virtio-pmd`: DPDK apps in the guest do not exit gracefully. This is a DPDK
> +     issue that is currently being investigated.
> +  - vHost-Cuse: Jumbo Frame support is not available for vHost Cuse ports.
> +
>  Bug Reporting:
>  --------------
>  

This should be in the patch adding the feature.  The rationale is that if you
bisect you can't have the code without the documentation.

>
>On Tue, 16 Feb 2016 11:31:50 +0000
>Mark Kavanagh <mark.b.kavanagh@intel.com> wrote:
>
>> Signed-off-by: Mark Kavanagh <mark.b.kavanagh@intel.com>
>> ---
>>  INSTALL.DPDK.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 59 insertions(+)
>>
>> diff --git a/INSTALL.DPDK.md b/INSTALL.DPDK.md
>> index 722fb9e..4ca98cb 100644
>> --- a/INSTALL.DPDK.md
>> +++ b/INSTALL.DPDK.md
>> @@ -878,6 +878,60 @@ by adding the following string:
>>  to <interface> sections of all network devices used by DPDK. Parameter 'N'
>>  determines how many queues can be used by the guest.
>>
>> +Jumbo Frames
>> +------------
>> +
>> +Support for Jumbo Frames may be enabled at run-time for DPDK-type ports.
>> +
>> +To avail of Jumbo Frame support, add the 'mtu_request' option to the ovs-vsctl
>> +'add-port' command-line, along with the required MTU for the port.
>> +e.g.
>> +
>> +     ```
>> +     ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk
>options:mtu_request=9000
>> +     ```
>> +
>> +When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments are
>> +increased, such that a full Jumbo Frame may be accommodated inside a single
>> +mbuf segment. Once set, the MTU for a DPDK port is immutable.
>> +
>> +Note that from an OVSDB perspective, the `mtu_request` option for a specific
>> +port may be disregarded once initially set, as subsequent modifications to this
>> +field are disregarded by the DPDK port. As with non-DPDK ports, the MTU of DPDK
>> +ports is reported by the `Interface` table's `mtu` field.
>> +
>> +Jumbo frame support has been validated against 13312B frames, using the
>> +DPDK `igb_uio` driver, but larger frames and other DPDK NIC drivers may
>> +theoretically be supported. Supported port types excludes vHost-Cuse ports, as
>> +that feature is pending deprecation.
>> +
>> +vHost Ports and Jumbo Frames
>> +----------------------------
>> +Jumbo frame support is available for DPDK vHost-User ports only. Some additional
>> +configuration is needed to take advantage of this feature:
>> +
>> +  1. `mergeable buffers` must be enabled for vHost ports, as demonstrated in
>> +      the QEMU command line snippet below:
>> +
>> +      ```
>> +      '-netdev type=vhost-user,id=mynet1,chardev=char0,vhostforce \'
>> +      '-device virtio-net-pci,mac=00:00:00:00:00:01,netdev=mynet1,mrg_rxbuf=on'
>> +      ```
>> +
>> +  2. Where virtio devices are bound to the Linux kernel driver in a guest
>> +     environment (i.e. interfaces are not bound to an in-guest DPDK driver), the
>> +     MTU of those logical network interfaces must also be increased. This
>> +     avoids segmentation of Jumbo Frames in the guest. Note that 'MTU' refers
>> +     to the length of the IP packet only, and not that of the entire frame.
>> +
>> +     e.g. To calculate the exact MTU of a standard IPv4 frame, subtract the L2
>> +     header and CRC lengths (i.e. 18B) from the max supported frame size.
>> +     So, to set the MTU for a 13312B Jumbo Frame:
>> +
>> +      ```
>> +      ifconfig eth1 mtu 13294
>> +      ```
>> +
>>  Restrictions:
>>  -------------
>>
>> @@ -921,6 +975,11 @@ Restrictions:
>>      the next release of DPDK (which includes the above patch) is available and
>>      integrated into OVS.
>>
>> +  Jumbo Frames:
>> +  - `virtio-pmd`: DPDK apps in the guest do not exit gracefully. This is a DPDK
>> +     issue that is currently being investigated.
>> +  - vHost-Cuse: Jumbo Frame support is not available for vHost Cuse ports.
>> +
>>  Bug Reporting:
>>  --------------
>>
>
>This should be in the patch adding the feature.  The rationale is that if you
>bisect you can't have the code without the documentation.
>

I was a bit on the fence as to whether I should split this out or not myself; I'll merge this and the NEWS changes back into the feature patch.

>--
>fbl