[ovs-dev,v2,8/9] doc: Add "jumbo frames" topic document

Message ID 20180416143026.24561-9-stephen@that.guru
State Changes Requested
Delegated to: Ian Stokes
Headers show
Series
  • Split up the DPDK how-to
Related show

Commit Message

Stephen Finucane April 16, 2018, 2:30 p.m.
We include refrences from the physical and vhost-user interface guides.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
v2:
- Don't split the document into multiple docs
---
 Documentation/howto/dpdk.rst               | 52 ++--------------------
 Documentation/topics/dpdk/index.rst        |  1 +
 Documentation/topics/dpdk/jumbo-frames.rst | 71 ++++++++++++++++++++++++++++++
 Documentation/topics/dpdk/phy.rst          |  6 +++
 Documentation/topics/dpdk/vhost-user.rst   |  6 +++
 5 files changed, 87 insertions(+), 49 deletions(-)
 create mode 100644 Documentation/topics/dpdk/jumbo-frames.rst

Comments

Stokes, Ian April 18, 2018, 3:32 p.m. | #1
> We include refrences from the physical and vhost-user interface guides.

Minor type above, 'reference'.

> 
> Signed-off-by: Stephen Finucane <stephen@that.guru>
> ---
> v2:
> - Don't split the document into multiple docs
> ---
>  Documentation/howto/dpdk.rst               | 52 ++--------------------
>  Documentation/topics/dpdk/index.rst        |  1 +
>  Documentation/topics/dpdk/jumbo-frames.rst | 71
> ++++++++++++++++++++++++++++++
>  Documentation/topics/dpdk/phy.rst          |  6 +++
>  Documentation/topics/dpdk/vhost-user.rst   |  6 +++
>  5 files changed, 87 insertions(+), 49 deletions(-)  create mode 100644
> Documentation/topics/dpdk/jumbo-frames.rst
> 
> diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> index 1a0fb6df1..e65e7dfaa 100644
> --- a/Documentation/howto/dpdk.rst
> +++ b/Documentation/howto/dpdk.rst
> @@ -48,9 +48,9 @@ number of dpdk devices found in the log file::
>      $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
>          options:dpdk-devargs=0000:01:00.1
> 
> -Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address associated
> -with multiple ports. Using a PCI device like above won't work. Instead,
> below -usage is suggested::
> +Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address
> +associated with multiple ports. Using a PCI device like above won't
> +work. Instead, below usage is suggested::
> 
>      $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
>          options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:01"
> @@ -85,52 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
>      $ ovs-appctl -t ovsdb-server exit
>      $ ovs-vsctl del-br br0
> 
> -Jumbo Frames
> -------------
> -
> -By default, DPDK ports are configured with standard Ethernet MTU (1500B).
> To -enable Jumbo Frames support for a DPDK port, change the Interface's -
> ``mtu_request`` attribute to a sufficiently large value. For example, to
> add a -DPDK Phy port with MTU of 9000::
> -
> -    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> -          options:dpdk-devargs=0000:01:00.0 mtu_request=9000
> -
> -Similarly, to change the MTU of an existing port to 6200::
> -
> -    $ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
> -
> -Some additional configuration is needed to take advantage of jumbo frames
> with -vHost ports:
> -
> -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 to a
> -   sufficiently large value. This avoids segmentation of Jumbo Frames
> received
> -   in the guest. Note that 'MTU' refers to the length of the IP packet
> only,
> -   and not that of the entire frame.
> -
> -   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 9018B Jumbo Frame::
> -
> -       $ ip link set eth1 mtu 9000
> -
> -When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments
> are -increased, such that a full Jumbo Frame of a specific size may be
> accommodated -within a single mbuf segment.
> -
> -Jumbo frame support has been validated against 9728B frames, which is the
> -largest frame size supported by Fortville NIC using the DPDK i40e driver,
> but -larger frames and other DPDK NIC drivers may be supported. These
> cases are -common for use cases involving East-West traffic only.
> -
>  .. _dpdk-ovs-in-guest:
> 
>  OVS with DPDK Inside VMs
> diff --git a/Documentation/topics/dpdk/index.rst
> b/Documentation/topics/dpdk/index.rst
> index d083d929e..181f61abb 100644
> --- a/Documentation/topics/dpdk/index.rst
> +++ b/Documentation/topics/dpdk/index.rst
> @@ -39,3 +39,4 @@ The DPDK Datapath
>     /topics/dpdk/pmd
>     /topics/dpdk/qos
>     /topics/dpdk/pdump
> +   /topics/dpdk/jumbo-frames
> diff --git a/Documentation/topics/dpdk/jumbo-frames.rst
> b/Documentation/topics/dpdk/jumbo-frames.rst
> new file mode 100644
> index 000000000..692b291ac
> --- /dev/null
> +++ b/Documentation/topics/dpdk/jumbo-frames.rst

Compilation error, jumbo-frames.rst not listed in Documentation/automake.mk.

Also was introduced in OVS 2.6, version change tag could flag this.

Ian

> @@ -0,0 +1,71 @@
> +..
> +      Copyright 2018, Red Hat, Inc.
> +
> +      Licensed under the Apache License, Version 2.0 (the "License"); you
> may
> +      not use this file except in compliance with the License. You may
> obtain
> +      a copy of the License at
> +
> +          http://www.apache.org/licenses/LICENSE-2.0
> +
> +      Unless required by applicable law or agreed to in writing, software
> +      distributed under the License is distributed on an "AS IS" BASIS,
> WITHOUT
> +      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> See the
> +      License for the specific language governing permissions and
> limitations
> +      under the License.
> +
> +      Convention for heading levels in Open vSwitch documentation:
> +
> +      =======  Heading 0 (reserved for the title in a document)
> +      -------  Heading 1
> +      ~~~~~~~  Heading 2
> +      +++++++  Heading 3
> +      '''''''  Heading 4
> +
> +      Avoid deeper levels because they do not render well.
> +
> +============
> +Jumbo Frames
> +============
> +
> +By default, DPDK ports are configured with standard Ethernet MTU
> +(1500B). To enable Jumbo Frames support for a DPDK port, change the
> +Interface's ``mtu_request`` attribute to a sufficiently large value.
> +For example, to add a :doc:`DPDK physical port <phy>` with an MTU of
> 9000, run::
> +
> +    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> +          options:dpdk-devargs=0000:01:00.0 mtu_request=9000
> +
> +Similarly, to change the MTU of an existing port to 6200, run::
> +
> +    $ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
> +
> +Some additional configuration is needed to take advantage of jumbo
> +frames with :doc:`vHost User ports <vhost-user>`:
> +
> +- *Mergeable buffers* must be enabled for vHost User 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
> +
> +- 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 to a
> +  sufficiently large value. This avoids segmentation of Jumbo Frames
> +received
> +  in the guest. Note that 'MTU' refers to the length of the IP packet
> +only, and
> +  not that of the entire frame.
> +
> +  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 9018B Jumbo Frame::
> +
> +      $ ip link set eth1 mtu 9000
> +
> +When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments
> +are increased, such that a full Jumbo Frame of a specific size may be
> +accommodated within a single mbuf segment.
> +
> +Jumbo frame support has been validated against 9728B frames, which is
> +the largest frame size supported by Fortville NIC using the DPDK i40e
> +driver, but larger frames and other DPDK NIC drivers may be supported.
> +These cases are common for use cases involving East-West traffic only.
> diff --git a/Documentation/topics/dpdk/phy.rst
> b/Documentation/topics/dpdk/phy.rst
> index c0931b2c4..477b291e4 100644
> --- a/Documentation/topics/dpdk/phy.rst
> +++ b/Documentation/topics/dpdk/phy.rst
> @@ -218,3 +218,9 @@ If the log is not seen then the port can be detached
> like so::
>  For more information please refer to the `DPDK Port Hotplug Framework`__.
> 
>  __
> http://dpdk.org/doc/guides/prog_guide/port_hotplug_framework.html#hotplug
> +
> +Jumbo Frames
> +------------
> +
> +DPDK physical ports can be configured to use Jumbo Frames. For more
> +information, refer to :doc:`jumbo-frames`.
> diff --git a/Documentation/topics/dpdk/vhost-user.rst
> b/Documentation/topics/dpdk/vhost-user.rst
> index 168d5c5ce..67eb77d43 100644
> --- a/Documentation/topics/dpdk/vhost-user.rst
> +++ b/Documentation/topics/dpdk/vhost-user.rst
> @@ -444,6 +444,12 @@ Sample XML
> 
>  .. _QEMU documentation: http://git.qemu-
> project.org/?p=qemu.git;a=blob;f=docs/specs/vhost-
> user.txt;h=7890d7169;hb=HEAD
> 
> +Jumbo Frames
> +------------
> +
> +DPDK vHost User ports can be configured to use Jumbo Frames. For more
> +information, refer to :doc:`jumbo-frames`.
> +
>  vhost-user Dequeue Zero Copy (experimental)
>  -------------------------------------------
> 
> --
> 2.14.3

Patch

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 1a0fb6df1..e65e7dfaa 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -48,9 +48,9 @@  number of dpdk devices found in the log file::
     $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
         options:dpdk-devargs=0000:01:00.1
 
-Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address associated
-with multiple ports. Using a PCI device like above won't work. Instead, below
-usage is suggested::
+Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address associated with
+multiple ports. Using a PCI device like above won't work. Instead, below usage
+is suggested::
 
     $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
         options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:01"
@@ -85,52 +85,6 @@  To stop ovs-vswitchd & delete bridge, run::
     $ ovs-appctl -t ovsdb-server exit
     $ ovs-vsctl del-br br0
 
-Jumbo Frames
-------------
-
-By default, DPDK ports are configured with standard Ethernet MTU (1500B). To
-enable Jumbo Frames support for a DPDK port, change the Interface's
-``mtu_request`` attribute to a sufficiently large value. For example, to add a
-DPDK Phy port with MTU of 9000::
-
-    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-          options:dpdk-devargs=0000:01:00.0 mtu_request=9000
-
-Similarly, to change the MTU of an existing port to 6200::
-
-    $ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
-
-Some additional configuration is needed to take advantage of jumbo frames with
-vHost ports:
-
-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 to a
-   sufficiently large value. This avoids segmentation of Jumbo Frames received
-   in the guest. Note that 'MTU' refers to the length of the IP packet only,
-   and not that of the entire frame.
-
-   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 9018B Jumbo Frame::
-
-       $ ip link set eth1 mtu 9000
-
-When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments are
-increased, such that a full Jumbo Frame of a specific size may be accommodated
-within a single mbuf segment.
-
-Jumbo frame support has been validated against 9728B frames, which is the
-largest frame size supported by Fortville NIC using the DPDK i40e driver, but
-larger frames and other DPDK NIC drivers may be supported. These cases are
-common for use cases involving East-West traffic only.
-
 .. _dpdk-ovs-in-guest:
 
 OVS with DPDK Inside VMs
diff --git a/Documentation/topics/dpdk/index.rst b/Documentation/topics/dpdk/index.rst
index d083d929e..181f61abb 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -39,3 +39,4 @@  The DPDK Datapath
    /topics/dpdk/pmd
    /topics/dpdk/qos
    /topics/dpdk/pdump
+   /topics/dpdk/jumbo-frames
diff --git a/Documentation/topics/dpdk/jumbo-frames.rst b/Documentation/topics/dpdk/jumbo-frames.rst
new file mode 100644
index 000000000..692b291ac
--- /dev/null
+++ b/Documentation/topics/dpdk/jumbo-frames.rst
@@ -0,0 +1,71 @@ 
+..
+      Copyright 2018, Red Hat, Inc.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+============
+Jumbo Frames
+============
+
+By default, DPDK ports are configured with standard Ethernet MTU (1500B). To
+enable Jumbo Frames support for a DPDK port, change the Interface's
+``mtu_request`` attribute to a sufficiently large value. For example, to add a
+:doc:`DPDK physical port <phy>` with an MTU of 9000, run::
+
+    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
+          options:dpdk-devargs=0000:01:00.0 mtu_request=9000
+
+Similarly, to change the MTU of an existing port to 6200, run::
+
+    $ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
+
+Some additional configuration is needed to take advantage of jumbo frames with
+:doc:`vHost User ports <vhost-user>`:
+
+- *Mergeable buffers* must be enabled for vHost User 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
+
+- 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 to a
+  sufficiently large value. This avoids segmentation of Jumbo Frames received
+  in the guest. Note that 'MTU' refers to the length of the IP packet only, and
+  not that of the entire frame.
+
+  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 9018B Jumbo Frame::
+
+      $ ip link set eth1 mtu 9000
+
+When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments are
+increased, such that a full Jumbo Frame of a specific size may be accommodated
+within a single mbuf segment.
+
+Jumbo frame support has been validated against 9728B frames, which is the
+largest frame size supported by Fortville NIC using the DPDK i40e driver, but
+larger frames and other DPDK NIC drivers may be supported. These cases are
+common for use cases involving East-West traffic only.
diff --git a/Documentation/topics/dpdk/phy.rst b/Documentation/topics/dpdk/phy.rst
index c0931b2c4..477b291e4 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -218,3 +218,9 @@  If the log is not seen then the port can be detached like so::
 For more information please refer to the `DPDK Port Hotplug Framework`__.
 
 __ http://dpdk.org/doc/guides/prog_guide/port_hotplug_framework.html#hotplug
+
+Jumbo Frames
+------------
+
+DPDK physical ports can be configured to use Jumbo Frames. For more
+information, refer to :doc:`jumbo-frames`.
diff --git a/Documentation/topics/dpdk/vhost-user.rst b/Documentation/topics/dpdk/vhost-user.rst
index 168d5c5ce..67eb77d43 100644
--- a/Documentation/topics/dpdk/vhost-user.rst
+++ b/Documentation/topics/dpdk/vhost-user.rst
@@ -444,6 +444,12 @@  Sample XML
 
 .. _QEMU documentation: http://git.qemu-project.org/?p=qemu.git;a=blob;f=docs/specs/vhost-user.txt;h=7890d7169;hb=HEAD
 
+Jumbo Frames
+------------
+
+DPDK vHost User ports can be configured to use Jumbo Frames. For more
+information, refer to :doc:`jumbo-frames`.
+
 vhost-user Dequeue Zero Copy (experimental)
 -------------------------------------------