[ovs-dev,7/8] doc: Split Jumbo Frames guide between two docs

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

Commit Message

Stephen Finucane Feb. 12, 2018, 6:13 p.m.
While there is some duplication going on here, that's not necessarily a
bad thing. If nothing else, it lets us remove one more overly-detailed
step from the howto.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 Documentation/howto/dpdk.rst             | 52 ++------------------------------
 Documentation/topics/dpdk/phy.rst        | 24 +++++++++++++++
 Documentation/topics/dpdk/vhost-user.rst | 36 ++++++++++++++++++++++
 3 files changed, 63 insertions(+), 49 deletions(-)

Comments

Ian Stokes April 9, 2018, 3:17 p.m. | #1
> While there is some duplication going on here, that's not necessarily a
> bad thing. If nothing else, it lets us remove one more overly-detailed
> step from the howto.
> 

I think it's cleaner to move Jumbo frames to its own doc altogether rather than splitting in two.
From the point of view flagging known issues and future maintenance this will help.

Maybe just add a small section in both phy and vhost user noting Jumbo frames are supported and then link to the main jumbo frame doc.

Ian

> Signed-off-by: Stephen Finucane <stephen@that.guru>
> ---
>  Documentation/howto/dpdk.rst             | 52 ++-------------------------
> -----
>  Documentation/topics/dpdk/phy.rst        | 24 +++++++++++++++
>  Documentation/topics/dpdk/vhost-user.rst | 36 ++++++++++++++++++++++
>  3 files changed, 63 insertions(+), 49 deletions(-)
> 
> diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> index 1a72e90bf..ba01810f8 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/phy.rst
> b/Documentation/topics/dpdk/phy.rst
> index 93aff628c..d49269567 100644
> --- a/Documentation/topics/dpdk/phy.rst
> +++ b/Documentation/topics/dpdk/phy.rst
> @@ -216,3 +216,27 @@ Flow Control
> 
>  Flow control is available for DPDK physical ports. For more information,
> refer  to :ref:`dpdk-flow-control`.
> +
> +Jumbo Frames
> +------------
> +
> +By default, ``dpdk`` ports are configured with standard Ethernet MTU
> (1500B).
> +To enable Jumbo Frames support for such a port, change the interface's
> +``mtu_request`` attribute to a sufficiently large value. For example,
> +to add a ``dpdk`` port with 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::
> +
> +    $ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
> +
> +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/vhost-user.rst
> b/Documentation/topics/dpdk/vhost-user.rst
> index d84d99246..7b2777121 100644
> --- a/Documentation/topics/dpdk/vhost-user.rst
> +++ b/Documentation/topics/dpdk/vhost-user.rst
> @@ -458,6 +458,42 @@ 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
> +------------
> +
> +By default, vHost User ports are configured with standard Ethernet MTU
> (1500B).
> +To enable Jumbo Frames support for such a port, you must:
> +
> +- Enable *mergeable buffers* for the 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. For example::
> +
> +       $ ip link set eth1 mtu 9000
> +
> +  .. note::
> +
> +     The '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. As a result, the actual size of the frame above is
> 9018B.
> +
> +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.
> +
>  vhost-user Dequeue Zero Copy (experimental)
>  -------------------------------------------
> 
> --
> 2.14.3
> 
> _______________________________________________
> dev mailing list
> dev@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Patch

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 1a72e90bf..ba01810f8 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/phy.rst b/Documentation/topics/dpdk/phy.rst
index 93aff628c..d49269567 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -216,3 +216,27 @@  Flow Control
 
 Flow control is available for DPDK physical ports. For more information, refer
 to :ref:`dpdk-flow-control`.
+
+Jumbo Frames
+------------
+
+By default, ``dpdk`` ports are configured with standard Ethernet MTU (1500B).
+To enable Jumbo Frames support for such a port, change the interface's
+``mtu_request`` attribute to a sufficiently large value. For example, to add a
+``dpdk`` port with 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::
+
+    $ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
+
+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/vhost-user.rst b/Documentation/topics/dpdk/vhost-user.rst
index d84d99246..7b2777121 100644
--- a/Documentation/topics/dpdk/vhost-user.rst
+++ b/Documentation/topics/dpdk/vhost-user.rst
@@ -458,6 +458,42 @@  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
+------------
+
+By default, vHost User ports are configured with standard Ethernet MTU (1500B).
+To enable Jumbo Frames support for such a port, you must:
+
+- Enable *mergeable buffers* for the 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. For example::
+
+       $ ip link set eth1 mtu 9000
+
+  .. note::
+
+     The '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. As a result, the actual size of the frame above is 9018B.
+
+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.
+
 vhost-user Dequeue Zero Copy (experimental)
 -------------------------------------------