[ovs-dev,v2,3/9] doc: Move additional sections to "physical ports" doc

Message ID 20180416143026.24561-4-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.
The "hotplugging", "flow control", and "Rx checksum offload" sections
only apply to 'dpdk' ports and are too detailed to include in a
high-level howto. Move them, reworking some aspects of this in the
process.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
v2:
- Split out vdev into its own document (and patch)
- Add cross-references from DPDK howto guide to detailed topic guides
- Add flow control
---
 Documentation/howto/dpdk.rst        | 103 ++++++------------------------------
 Documentation/topics/dpdk/index.rst |  11 ++--
 Documentation/topics/dpdk/phy.rst   |  86 ++++++++++++++++++++++++++++++
 3 files changed, 110 insertions(+), 90 deletions(-)

Comments

Ian Stokes April 18, 2018, 3:31 p.m. | #1
> The "hotplugging", "flow control", and "Rx checksum offload" sections only
> apply to 'dpdk' ports and are too detailed to include in a high-level
> howto. Move them, reworking some aspects of this in the process.
> 
> Signed-off-by: Stephen Finucane <stephen@that.guru>
> ---
> v2:
> - Split out vdev into its own document (and patch)
> - Add cross-references from DPDK howto guide to detailed topic guides
> - Add flow control
> ---
>  Documentation/howto/dpdk.rst        | 103 ++++++-------------------------
> -----
>  Documentation/topics/dpdk/index.rst |  11 ++--
>  Documentation/topics/dpdk/phy.rst   |  86 ++++++++++++++++++++++++++++++
>  3 files changed, 110 insertions(+), 90 deletions(-)

LGTM.

Ian

> 
> diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> index 388728363..531612880 100644
> --- a/Documentation/howto/dpdk.rst
> +++ b/Documentation/howto/dpdk.rst
> @@ -57,8 +57,12 @@ usage is suggested::
>      $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
>          options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:02"
> 
> -Note: such syntax won't support hotplug. The hotplug is supposed to work
> with -future DPDK release, v18.05.
> +.. important::
> +
> +    Hotplugging physical interfaces is not supported using the above
> syntax.
> +    This is expected to change with the release of DPDK v18.05. For
> information
> +    on hotplugging physical interfaces, you should instead refer to
> +    :ref:`port-hotplug`.
> 
>  After the DPDK ports get added to switch, a polling thread continuously
> polls  DPDK devices and consumes 100% of the core, as can be checked from
> ``top`` and @@ -123,34 +127,6 @@ To clear the ingress policer
> configuration from the port::
> 
>  Refer to vswitch.xml for more details on ingress-policer.
> 
> -Flow Control
> -------------
> -
> -Flow control can be enabled only on DPDK physical ports. To enable flow
> control -support at tx side while adding a port, run::
> -
> -    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> -        options:dpdk-devargs=0000:01:00.0 options:tx-flow-ctrl=true
> -
> -Similarly, to enable rx flow control, run::
> -
> -    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> -        options:dpdk-devargs=0000:01:00.0 options:rx-flow-ctrl=true
> -
> -To enable flow control auto-negotiation, run::
> -
> -    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> -        options:dpdk-devargs=0000:01:00.0 options:flow-ctrl-autoneg=true
> -
> -To turn ON the tx flow control at run time for an existing port, run::
> -
> -    $ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=true
> -
> -The flow control parameters can be turned off by setting ``false`` to the
> -respective parameter. To disable the flow control at tx side, run::
> -
> -    $ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=false
> -
>  pdump
>  -----
> 
> @@ -236,16 +212,6 @@ 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.
> 
> -Rx Checksum Offload
> --------------------
> -
> -By default, DPDK physical ports are enabled with Rx checksum offload.
> -
> -Rx checksum offload can offer performance improvement only for tunneling
> -traffic in OVS-DPDK because the checksum validation of tunnel packets is
> -offloaded to the NIC. Also enabling Rx checksum may slightly reduce the -
> performance of non-tunnel traffic, specifically for smaller size packet.
> -
>  .. _extended-statistics:
> 
>  Extended & Custom Statistics
> @@ -278,52 +244,6 @@ Note about "Extended Statistics": vHost ports
> supports only partial  statistics. RX packet size based counter are only
> supported and  doesn't include TX packet size counters.
> 
> -.. _port-hotplug:
> -
> -Port Hotplug
> -------------
> -
> -OVS supports port hotplugging, allowing the use of ports that were not
> bound -to DPDK when vswitchd was started.
> -In order to attach a port, it has to be bound to DPDK using the -
> ``dpdk_nic_bind.py`` script::
> -
> -    $ $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio 0000:01:00.0
> -
> -Then it can be attached to OVS::
> -
> -    $ ovs-vsctl add-port br0 dpdkx -- set Interface dpdkx type=dpdk \
> -        options:dpdk-devargs=0000:01:00.0
> -
> -Detaching will be performed while processing del-port command::
> -
> -    $ ovs-vsctl del-port dpdkx
> -
> -Sometimes, the del-port command may not detach the device.
> -Detaching can be confirmed by the appearance of an INFO log.
> -For example::
> -
> -    INFO|Device '0000:04:00.1' has been detached
> -
> -If the log is not seen, then the port can be detached using::
> -
> -$ ovs-appctl netdev-dpdk/detach 0000:01:00.0
> -
> -Detaching can be confirmed by console output::
> -
> -    Device '0000:04:00.1' has been detached
> -
> -.. warning::
> -    Detaching should not be done if a device is known to be non-
> detachable, as
> -    this may cause the device to behave improperly when added back with
> -    add-port. The Chelsio Terminator adapters which use the cxgbe driver
> seem
> -    to be an example of this behavior; check the driver documentation if
> this
> -    is suspected.
> -
> -This feature does not work with some NICs.
> -For more information please refer to the `DPDK Port Hotplug Framework -
> <http://dpdk.org/doc/guides/prog_guide/port_hotplug_framework.html#hotplug
> >`__.
> -
>  .. _vdev-support:
> 
>  Vdev Support
> @@ -653,3 +573,14 @@ devices to bridge ``br0``. Once complete, follow the
> below steps:
>     Check traffic on multiple queues::
> 
>         $ cat /proc/interrupts | grep virtio
> +
> +Further Reading
> +---------------
> +
> +More detailed information can be found in the :doc:`DPDK topics section
> +</topics/dpdk/index>` of the documentation. These guides are listed
> below.
> +
> +.. NOTE(stephenfin): Remember to keep this in sync with
> +topics/dpdk/index
> +
> +.. include:: ../topics/dpdk/index.rst
> +   :start-line: 30
> diff --git a/Documentation/topics/dpdk/index.rst
> b/Documentation/topics/dpdk/index.rst
> index dfde88377..4b4dc119a 100644
> --- a/Documentation/topics/dpdk/index.rst
> +++ b/Documentation/topics/dpdk/index.rst
> @@ -25,10 +25,13 @@
>  The DPDK Datapath
>  =================
> 
> +.. NOTE(stephenfin): Part of this doc is included in 'howto/dpdk'.
> +Update that .. if you modify this document
> +
>  .. toctree::
>     :maxdepth: 2
> 
> -   phy
> -   vhost-user
> -   ring
> -   pmd
> +   /topics/dpdk/phy
> +   /topics/dpdk/vhost-user
> +   /topics/dpdk/ring
> +   /topics/dpdk/pmd
> diff --git a/Documentation/topics/dpdk/phy.rst
> b/Documentation/topics/dpdk/phy.rst
> index ad191dad0..929f394ea 100644
> --- a/Documentation/topics/dpdk/phy.rst
> +++ b/Documentation/topics/dpdk/phy.rst
> @@ -125,3 +125,89 @@ utilize is a requirement in order to deliver the
> high-performance possible with  DPDK acceleration. It is possible to
> configure multiple Rx queues for ``dpdk``  ports, thus ensuring this is
> not a bottleneck for performance. For information  on configuring PMD
> threads, refer to :doc:`pmd`.
> +
> +Flow Control
> +------------
> +
> +Flow control can be enabled only on DPDK physical ports. To enable flow
> +control support at Tx side while adding a port, run::
> +
> +    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> +        options:dpdk-devargs=0000:01:00.0 options:tx-flow-ctrl=true
> +
> +Similarly, to enable Rx flow control, run::
> +
> +    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> +        options:dpdk-devargs=0000:01:00.0 options:rx-flow-ctrl=true
> +
> +To enable flow control auto-negotiation, run::
> +
> +    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> +        options:dpdk-devargs=0000:01:00.0
> + options:flow-ctrl-autoneg=true
> +
> +To turn on the Tx flow control at run time for an existing port, run::
> +
> +    $ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=true
> +
> +The flow control parameters can be turned off by setting ``false`` to
> +the respective parameter. To disable the flow control at Tx side, run::
> +
> +    $ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=false
> +
> +Rx Checksum Offload
> +-------------------
> +
> +By default, DPDK physical ports are enabled with Rx checksum offload.
> +
> +Rx checksum offload can offer performance improvement only for
> +tunneling traffic in OVS-DPDK because the checksum validation of tunnel
> +packets is offloaded to the NIC. Also enabling Rx checksum may slightly
> +reduce the performance of non-tunnel traffic, specifically for smaller
> size packet.
> +
> +.. _port-hotplug:
> +
> +Hotplugging
> +-----------
> +
> +OVS supports port hotplugging, allowing the use of physical ports that
> +were not bound to DPDK when ovs-vswitchd was started.
> +
> +.. warning::
> +
> +    This feature is not compatible with all NICs. Refer to vendor
> documentation
> +    for more information.
> +
> +.. important::
> +
> +   Ports must be bound to DPDK. Refer to :ref:`dpdk-binding-nics` for
> more
> +   information.
> +
> +To *hotplug* a port, simply add it like any other port::
> +
> +    $ ovs-vsctl add-port br0 dpdkx -- set Interface dpdkx type=dpdk \
> +        options:dpdk-devargs=0000:01:00.0
> +
> +Ports can be detached using the ``del-port`` command::
> +
> +    $ ovs-vsctl del-port dpdkx
> +
> +This should both delete the port and detach the device. If successful,
> +you should see an ``INFO`` log. For example::
> +
> +    INFO|Device '0000:04:00.1' has been detached
> +
> +If the log is not seen then the port can be detached like so::
> +
> +    $ ovs-appctl netdev-dpdk/detach 0000:01:00.0
> +
> +.. warning::
> +
> +    Detaching should not be done if a device is known to be non-
> detachable, as
> +    this may cause the device to behave improperly when added back with
> +    add-port. The Chelsio Terminator adapters which use the cxgbe driver
> seem
> +    to be an example of this behavior; check the driver documentation if
> this
> +    is suspected.
> +
> +For more information please refer to the `DPDK Port Hotplug Framework`__.
> +
> +__
> +http://dpdk.org/doc/guides/prog_guide/port_hotplug_framework.html#hotpl
> +ug
> --
> 2.14.3

Patch

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 388728363..531612880 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -57,8 +57,12 @@  usage is suggested::
     $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
         options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:02"
 
-Note: such syntax won't support hotplug. The hotplug is supposed to work with
-future DPDK release, v18.05.
+.. important::
+
+    Hotplugging physical interfaces is not supported using the above syntax.
+    This is expected to change with the release of DPDK v18.05. For information
+    on hotplugging physical interfaces, you should instead refer to
+    :ref:`port-hotplug`.
 
 After the DPDK ports get added to switch, a polling thread continuously polls
 DPDK devices and consumes 100% of the core, as can be checked from ``top`` and
@@ -123,34 +127,6 @@  To clear the ingress policer configuration from the port::
 
 Refer to vswitch.xml for more details on ingress-policer.
 
-Flow Control
-------------
-
-Flow control can be enabled only on DPDK physical ports. To enable flow control
-support at tx side while adding a port, run::
-
-    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-        options:dpdk-devargs=0000:01:00.0 options:tx-flow-ctrl=true
-
-Similarly, to enable rx flow control, run::
-
-    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-        options:dpdk-devargs=0000:01:00.0 options:rx-flow-ctrl=true
-
-To enable flow control auto-negotiation, run::
-
-    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-        options:dpdk-devargs=0000:01:00.0 options:flow-ctrl-autoneg=true
-
-To turn ON the tx flow control at run time for an existing port, run::
-
-    $ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=true
-
-The flow control parameters can be turned off by setting ``false`` to the
-respective parameter. To disable the flow control at tx side, run::
-
-    $ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=false
-
 pdump
 -----
 
@@ -236,16 +212,6 @@  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.
 
-Rx Checksum Offload
--------------------
-
-By default, DPDK physical ports are enabled with Rx checksum offload.
-
-Rx checksum offload can offer performance improvement only for tunneling
-traffic in OVS-DPDK because the checksum validation of tunnel packets is
-offloaded to the NIC. Also enabling Rx checksum may slightly reduce the
-performance of non-tunnel traffic, specifically for smaller size packet.
-
 .. _extended-statistics:
 
 Extended & Custom Statistics
@@ -278,52 +244,6 @@  Note about "Extended Statistics": vHost ports supports only partial
 statistics. RX packet size based counter are only supported and
 doesn't include TX packet size counters.
 
-.. _port-hotplug:
-
-Port Hotplug
-------------
-
-OVS supports port hotplugging, allowing the use of ports that were not bound
-to DPDK when vswitchd was started.
-In order to attach a port, it has to be bound to DPDK using the
-``dpdk_nic_bind.py`` script::
-
-    $ $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio 0000:01:00.0
-
-Then it can be attached to OVS::
-
-    $ ovs-vsctl add-port br0 dpdkx -- set Interface dpdkx type=dpdk \
-        options:dpdk-devargs=0000:01:00.0
-
-Detaching will be performed while processing del-port command::
-
-    $ ovs-vsctl del-port dpdkx
-
-Sometimes, the del-port command may not detach the device.
-Detaching can be confirmed by the appearance of an INFO log.
-For example::
-
-    INFO|Device '0000:04:00.1' has been detached
-
-If the log is not seen, then the port can be detached using::
-
-$ ovs-appctl netdev-dpdk/detach 0000:01:00.0
-
-Detaching can be confirmed by console output::
-
-    Device '0000:04:00.1' has been detached
-
-.. warning::
-    Detaching should not be done if a device is known to be non-detachable, as
-    this may cause the device to behave improperly when added back with
-    add-port. The Chelsio Terminator adapters which use the cxgbe driver seem
-    to be an example of this behavior; check the driver documentation if this
-    is suspected.
-
-This feature does not work with some NICs.
-For more information please refer to the `DPDK Port Hotplug Framework
-<http://dpdk.org/doc/guides/prog_guide/port_hotplug_framework.html#hotplug>`__.
-
 .. _vdev-support:
 
 Vdev Support
@@ -653,3 +573,14 @@  devices to bridge ``br0``. Once complete, follow the below steps:
    Check traffic on multiple queues::
 
        $ cat /proc/interrupts | grep virtio
+
+Further Reading
+---------------
+
+More detailed information can be found in the :doc:`DPDK topics section
+</topics/dpdk/index>` of the documentation. These guides are listed below.
+
+.. NOTE(stephenfin): Remember to keep this in sync with topics/dpdk/index
+
+.. include:: ../topics/dpdk/index.rst
+   :start-line: 30
diff --git a/Documentation/topics/dpdk/index.rst b/Documentation/topics/dpdk/index.rst
index dfde88377..4b4dc119a 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -25,10 +25,13 @@ 
 The DPDK Datapath
 =================
 
+.. NOTE(stephenfin): Part of this doc is included in 'howto/dpdk'. Update that
+.. if you modify this document
+
 .. toctree::
    :maxdepth: 2
 
-   phy
-   vhost-user
-   ring
-   pmd
+   /topics/dpdk/phy
+   /topics/dpdk/vhost-user
+   /topics/dpdk/ring
+   /topics/dpdk/pmd
diff --git a/Documentation/topics/dpdk/phy.rst b/Documentation/topics/dpdk/phy.rst
index ad191dad0..929f394ea 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -125,3 +125,89 @@  utilize is a requirement in order to deliver the high-performance possible with
 DPDK acceleration. It is possible to configure multiple Rx queues for ``dpdk``
 ports, thus ensuring this is not a bottleneck for performance. For information
 on configuring PMD threads, refer to :doc:`pmd`.
+
+Flow Control
+------------
+
+Flow control can be enabled only on DPDK physical ports. To enable flow control
+support at Tx side while adding a port, run::
+
+    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
+        options:dpdk-devargs=0000:01:00.0 options:tx-flow-ctrl=true
+
+Similarly, to enable Rx flow control, run::
+
+    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
+        options:dpdk-devargs=0000:01:00.0 options:rx-flow-ctrl=true
+
+To enable flow control auto-negotiation, run::
+
+    $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
+        options:dpdk-devargs=0000:01:00.0 options:flow-ctrl-autoneg=true
+
+To turn on the Tx flow control at run time for an existing port, run::
+
+    $ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=true
+
+The flow control parameters can be turned off by setting ``false`` to the
+respective parameter. To disable the flow control at Tx side, run::
+
+    $ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=false
+
+Rx Checksum Offload
+-------------------
+
+By default, DPDK physical ports are enabled with Rx checksum offload.
+
+Rx checksum offload can offer performance improvement only for tunneling
+traffic in OVS-DPDK because the checksum validation of tunnel packets is
+offloaded to the NIC. Also enabling Rx checksum may slightly reduce the
+performance of non-tunnel traffic, specifically for smaller size packet.
+
+.. _port-hotplug:
+
+Hotplugging
+-----------
+
+OVS supports port hotplugging, allowing the use of physical ports that were not
+bound to DPDK when ovs-vswitchd was started.
+
+.. warning::
+
+    This feature is not compatible with all NICs. Refer to vendor documentation
+    for more information.
+
+.. important::
+
+   Ports must be bound to DPDK. Refer to :ref:`dpdk-binding-nics` for more
+   information.
+
+To *hotplug* a port, simply add it like any other port::
+
+    $ ovs-vsctl add-port br0 dpdkx -- set Interface dpdkx type=dpdk \
+        options:dpdk-devargs=0000:01:00.0
+
+Ports can be detached using the ``del-port`` command::
+
+    $ ovs-vsctl del-port dpdkx
+
+This should both delete the port and detach the device. If successful, you
+should see an ``INFO`` log. For example::
+
+    INFO|Device '0000:04:00.1' has been detached
+
+If the log is not seen then the port can be detached like so::
+
+    $ ovs-appctl netdev-dpdk/detach 0000:01:00.0
+
+.. warning::
+
+    Detaching should not be done if a device is known to be non-detachable, as
+    this may cause the device to behave improperly when added back with
+    add-port. The Chelsio Terminator adapters which use the cxgbe driver seem
+    to be an example of this behavior; check the driver documentation if this
+    is suspected.
+
+For more information please refer to the `DPDK Port Hotplug Framework`__.
+
+__ http://dpdk.org/doc/guides/prog_guide/port_hotplug_framework.html#hotplug