[ovs-dev,v2,4/9] doc: Add "vdev" topic document

Message ID 20180416143026.24561-5-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.
These are separate things from physical, ring and vhost-user interfaces
and deserve their own documents. A couple of small typos are fixed along
the way.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 Documentation/howto/dpdk.rst        | 29 ------------------
 Documentation/topics/dpdk/index.rst |  1 +
 Documentation/topics/dpdk/vdev.rst  | 59 +++++++++++++++++++++++++++++++++++++
 3 files changed, 60 insertions(+), 29 deletions(-)
 create mode 100644 Documentation/topics/dpdk/vdev.rst

Comments

Stokes, Ian April 18, 2018, 3:32 p.m. | #1
> These are separate things from physical, ring and vhost-user interfaces
> and deserve their own documents. A couple of small typos are fixed along
> the way.
> 
> Signed-off-by: Stephen Finucane <stephen@that.guru>
> ---
>  Documentation/howto/dpdk.rst        | 29 ------------------
>  Documentation/topics/dpdk/index.rst |  1 +
> Documentation/topics/dpdk/vdev.rst  | 59
> +++++++++++++++++++++++++++++++++++++
>  3 files changed, 60 insertions(+), 29 deletions(-)  create mode 100644
> Documentation/topics/dpdk/vdev.rst
> 
> diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> index 531612880..9cb76b7e1 100644
> --- a/Documentation/howto/dpdk.rst
> +++ b/Documentation/howto/dpdk.rst
> @@ -244,35 +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.
> 
> -.. _vdev-support:
> -
> -Vdev Support
> -------------
> -
> -DPDK provides drivers for both physical and virtual devices. Physical
> DPDK -devices are added to OVS by specifying a valid PCI address in 'dpdk-
> devargs'.
> -Virtual DPDK devices which do not have PCI addresses can be added using a
> -different format for 'dpdk-devargs'.
> -
> -Typically, the format expected is 'eth_<driver_name><x>' where 'x' is a -
> unique identifier of your choice for the given port.
> -
> -For example to add a dpdk port that uses the 'null' DPDK PMD driver::
> -
> -       $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
> -           options:dpdk-devargs=eth_null0
> -
> -Similarly, to add a dpdk port that uses the 'af_packet' DPDK PMD driver::
> -
> -       $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk
> \
> -           options:dpdk-devargs=eth_af_packet0,iface=eth0
> -
> -More information on the different types of virtual DPDK PMDs can be found
> in -the `DPDK documentation -
> <http://dpdk.org/doc/guides/nics/overview.html>`__.
> -
> -Note: Not all DPDK virtual PMD drivers have been tested and verified to
> work.
> -
>  EMC Insertion Probability
>  -------------------------
>  By default 1 in every 100 flows are inserted into the Exact Match Cache
> (EMC).
> diff --git a/Documentation/topics/dpdk/index.rst
> b/Documentation/topics/dpdk/index.rst
> index 4b4dc119a..c1e6ea78c 100644
> --- a/Documentation/topics/dpdk/index.rst
> +++ b/Documentation/topics/dpdk/index.rst
> @@ -34,4 +34,5 @@ The DPDK Datapath
>     /topics/dpdk/phy
>     /topics/dpdk/vhost-user
>     /topics/dpdk/ring
> +   /topics/dpdk/vdev
>     /topics/dpdk/pmd
> diff --git a/Documentation/topics/dpdk/vdev.rst
> b/Documentation/topics/dpdk/vdev.rst

Compilation error, vdev.rst not listed in Documentation/automake.mk

> new file mode 100644
> index 000000000..1b00ac573
> --- /dev/null
> +++ b/Documentation/topics/dpdk/vdev.rst
> @@ -0,0 +1,59 @@
> +..
> +      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.
> +
> +====================
> +DPDK Virtual Devices
> +====================
> +

Support for vdevs was added as part of OVS 2.7, version change tag here to flag it wasn't there for 2.6 would be good.

> +DPDK provides drivers for both physical and virtual devices. Physical
> +DPDK devices are added to OVS by specifying a valid PCI address in
> ``dpdk-devargs``.
> +Virtual DPDK devices which do not have PCI addresses can be added using
> +a different format for ``dpdk-devargs``.
> +
> +.. note::
> +
> +    Not all DPDK virtual PMD drivers have been tested and verified to
> work.
> +

Similar to vhost and phy devices I'd add a cross reference to the bridge document here after it's added.

> +Quick Example
> +-------------
> +
> +To add a virtual ``dpdk`` devices, the ``dpdk-devargs`` argument should
> +be of the format ``eth_<driver_name><x>``, where ``x``' is a unique
> +identifier of your choice for the given port. For example to add a
> +``dpdk`` port that uses the ``null`` DPDK PMD driver, run::
> +
> +   $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
> +       options:dpdk-devargs=eth_null0
> +
> +Similarly, to add a ``dpdk`` port that uses the ``af_packet`` DPDK PMD
> +driver,
> +run::
> +
> +   $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk \
> +       options:dpdk-devargs=eth_af_packet0,iface=eth0
> +
> +More information on the different types of virtual DPDK PMDs can be
> +found in the `DPDK documentation`__.
> +
> +__ http://dpdk.org/doc/guides/nics/overview.html
> --
> 2.14.3
Stephen Finucane April 19, 2018, 12:45 p.m. | #2
On Wed, 2018-04-18 at 15:32 +0000, Stokes, Ian wrote:
> > These are separate things from physical, ring and vhost-user interfaces
> > and deserve their own documents. A couple of small typos are fixed along
> > the way.
> > 
> > Signed-off-by: Stephen Finucane <stephen@that.guru>
> > ---
> >  Documentation/howto/dpdk.rst        | 29 ------------------
> >  Documentation/topics/dpdk/index.rst |  1 +
> > Documentation/topics/dpdk/vdev.rst  | 59
> > +++++++++++++++++++++++++++++++++++++
> >  3 files changed, 60 insertions(+), 29 deletions(-)  create mode 100644
> > Documentation/topics/dpdk/vdev.rst
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index 531612880..9cb76b7e1 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -244,35 +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.
> > 
> > -.. _vdev-support:
> > -
> > -Vdev Support
> > -------------
> > -
> > -DPDK provides drivers for both physical and virtual devices. Physical
> > DPDK -devices are added to OVS by specifying a valid PCI address in 'dpdk-
> > devargs'.
> > -Virtual DPDK devices which do not have PCI addresses can be added using a
> > -different format for 'dpdk-devargs'.
> > -
> > -Typically, the format expected is 'eth_<driver_name><x>' where 'x' is a -
> > unique identifier of your choice for the given port.
> > -
> > -For example to add a dpdk port that uses the 'null' DPDK PMD driver::
> > -
> > -       $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
> > -           options:dpdk-devargs=eth_null0
> > -
> > -Similarly, to add a dpdk port that uses the 'af_packet' DPDK PMD driver::
> > -
> > -       $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk
> > \
> > -           options:dpdk-devargs=eth_af_packet0,iface=eth0
> > -
> > -More information on the different types of virtual DPDK PMDs can be found
> > in -the `DPDK documentation -
> > <http://dpdk.org/doc/guides/nics/overview.html>`__.
> > -
> > -Note: Not all DPDK virtual PMD drivers have been tested and verified to
> > work.
> > -
> >  EMC Insertion Probability
> >  -------------------------
> >  By default 1 in every 100 flows are inserted into the Exact Match Cache
> > (EMC).
> > diff --git a/Documentation/topics/dpdk/index.rst
> > b/Documentation/topics/dpdk/index.rst
> > index 4b4dc119a..c1e6ea78c 100644
> > --- a/Documentation/topics/dpdk/index.rst
> > +++ b/Documentation/topics/dpdk/index.rst
> > @@ -34,4 +34,5 @@ The DPDK Datapath
> >     /topics/dpdk/phy
> >     /topics/dpdk/vhost-user
> >     /topics/dpdk/ring
> > +   /topics/dpdk/vdev
> >     /topics/dpdk/pmd
> > diff --git a/Documentation/topics/dpdk/vdev.rst
> > b/Documentation/topics/dpdk/vdev.rst
> 
> Compilation error, vdev.rst not listed in Documentation/automake.mk
> 
> > new file mode 100644
> > index 000000000..1b00ac573
> > --- /dev/null
> > +++ b/Documentation/topics/dpdk/vdev.rst
> > @@ -0,0 +1,59 @@
> > +..
> > +      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.
> > +
> > +====================
> > +DPDK Virtual Devices
> > +====================
> > +
> 
> Support for vdevs was added as part of OVS 2.7, version change tag
> here to flag it wasn't there for 2.6 would be good.

Done

> > +DPDK provides drivers for both physical and virtual devices. Physical
> > +DPDK devices are added to OVS by specifying a valid PCI address in
> > ``dpdk-devargs``.
> > +Virtual DPDK devices which do not have PCI addresses can be added using
> > +a different format for ``dpdk-devargs``.
> > +
> > +.. note::
> > +
> > +    Not all DPDK virtual PMD drivers have been tested and verified to
> > work.
> > +
> 
> Similar to vhost and phy devices I'd add a cross reference to the
> bridge document here after it's added.

Will do.

> > +Quick Example
> > +-------------
> > +
> > +To add a virtual ``dpdk`` devices, the ``dpdk-devargs`` argument should
> > +be of the format ``eth_<driver_name><x>``, where ``x``' is a unique
> > +identifier of your choice for the given port. For example to add a
> > +``dpdk`` port that uses the ``null`` DPDK PMD driver, run::
> > +
> > +   $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
> > +       options:dpdk-devargs=eth_null0
> > +
> > +Similarly, to add a ``dpdk`` port that uses the ``af_packet`` DPDK PMD
> > +driver,
> > +run::
> > +
> > +   $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk \
> > +       options:dpdk-devargs=eth_af_packet0,iface=eth0
> > +
> > +More information on the different types of virtual DPDK PMDs can be
> > +found in the `DPDK documentation`__.
> > +
> > +__ http://dpdk.org/doc/guides/nics/overview.html
> > --
> > 2.14.3
> 
>

Patch

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 531612880..9cb76b7e1 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -244,35 +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.
 
-.. _vdev-support:
-
-Vdev Support
-------------
-
-DPDK provides drivers for both physical and virtual devices. Physical DPDK
-devices are added to OVS by specifying a valid PCI address in 'dpdk-devargs'.
-Virtual DPDK devices which do not have PCI addresses can be added using a
-different format for 'dpdk-devargs'.
-
-Typically, the format expected is 'eth_<driver_name><x>' where 'x' is a
-unique identifier of your choice for the given port.
-
-For example to add a dpdk port that uses the 'null' DPDK PMD driver::
-
-       $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
-           options:dpdk-devargs=eth_null0
-
-Similarly, to add a dpdk port that uses the 'af_packet' DPDK PMD driver::
-
-       $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk \
-           options:dpdk-devargs=eth_af_packet0,iface=eth0
-
-More information on the different types of virtual DPDK PMDs can be found in
-the `DPDK documentation
-<http://dpdk.org/doc/guides/nics/overview.html>`__.
-
-Note: Not all DPDK virtual PMD drivers have been tested and verified to work.
-
 EMC Insertion Probability
 -------------------------
 By default 1 in every 100 flows are inserted into the Exact Match Cache (EMC).
diff --git a/Documentation/topics/dpdk/index.rst b/Documentation/topics/dpdk/index.rst
index 4b4dc119a..c1e6ea78c 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -34,4 +34,5 @@  The DPDK Datapath
    /topics/dpdk/phy
    /topics/dpdk/vhost-user
    /topics/dpdk/ring
+   /topics/dpdk/vdev
    /topics/dpdk/pmd
diff --git a/Documentation/topics/dpdk/vdev.rst b/Documentation/topics/dpdk/vdev.rst
new file mode 100644
index 000000000..1b00ac573
--- /dev/null
+++ b/Documentation/topics/dpdk/vdev.rst
@@ -0,0 +1,59 @@ 
+..
+      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.
+
+====================
+DPDK Virtual Devices
+====================
+
+DPDK provides drivers for both physical and virtual devices. Physical DPDK
+devices are added to OVS by specifying a valid PCI address in ``dpdk-devargs``.
+Virtual DPDK devices which do not have PCI addresses can be added using a
+different format for ``dpdk-devargs``.
+
+.. note::
+
+    Not all DPDK virtual PMD drivers have been tested and verified to work.
+
+Quick Example
+-------------
+
+To add a virtual ``dpdk`` devices, the ``dpdk-devargs`` argument should be of
+the format ``eth_<driver_name><x>``, where ``x``' is a unique identifier of
+your choice for the given port. For example to add a ``dpdk`` port that uses
+the ``null`` DPDK PMD driver, run::
+
+   $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
+       options:dpdk-devargs=eth_null0
+
+Similarly, to add a ``dpdk`` port that uses the ``af_packet`` DPDK PMD driver,
+run::
+
+   $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk \
+       options:dpdk-devargs=eth_af_packet0,iface=eth0
+
+More information on the different types of virtual DPDK PMDs can be found in
+the `DPDK documentation`__.
+
+__ http://dpdk.org/doc/guides/nics/overview.html