[ovs-dev,6/8] doc: Move "pdump" guide to its own document

Message ID 20180212181306.6674-7-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.
Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 Documentation/howto/dpdk.rst        | 39 ----------------------
 Documentation/topics/dpdk/index.rst |  7 ++++
 Documentation/topics/dpdk/pdump.rst | 65 +++++++++++++++++++++++++++++++++++++
 3 files changed, 72 insertions(+), 39 deletions(-)
 create mode 100644 Documentation/topics/dpdk/pdump.rst

Comments

Stokes, Ian April 9, 2018, 3:17 p.m. | #1
Minor nit, would like to see a commit message here. I think you modify caption headers in the patch also, these could be kept in the final clean up patch of the series.

Ian

> Signed-off-by: Stephen Finucane <stephen@that.guru>
> ---
>  Documentation/howto/dpdk.rst        | 39 ----------------------
>  Documentation/topics/dpdk/index.rst |  7 ++++
> Documentation/topics/dpdk/pdump.rst | 65
> +++++++++++++++++++++++++++++++++++++
>  3 files changed, 72 insertions(+), 39 deletions(-)  create mode 100644
> Documentation/topics/dpdk/pdump.rst
> 
> diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> index c01bf7a39..1a72e90bf 100644
> --- a/Documentation/howto/dpdk.rst
> +++ b/Documentation/howto/dpdk.rst
> @@ -85,45 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
>      $ ovs-appctl -t ovsdb-server exit
>      $ ovs-vsctl del-br br0
> 
> -pdump
> ------
> -
> -pdump allows you to listen on DPDK ports and view the traffic that is
> passing -on them. To use this utility, one must have libpcap installed on
> the system.
> -Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and -
> ``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
> -
> -.. warning::
> -  A performance decrease is expected when using a monitoring application
> like
> -  the DPDK pdump app.
> -
> -To use pdump, simply launch OVS as usual, then navigate to the
> ``app/pdump`` -directory in DPDK, ``make`` the application and run like
> so::
> -
> -    $ sudo ./build/app/dpdk-pdump -- \
> -        --pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
> -        --server-socket-path=/usr/local/var/run/openvswitch
> -
> -The above command captures traffic received on queue 0 of port 0 and
> stores it -in ``/tmp/pkts.pcap``. Other combinations of port numbers,
> queues numbers and -pcap locations are of course also available to use.
> For example, to capture all -packets that traverse port 0 in a single pcap
> file::
> -
> -    $ sudo ./build/app/dpdk-pdump -- \
> -        --pdump 'port=0,queue=*,rx-dev=/tmp/pkts.pcap,tx-
> dev=/tmp/pkts.pcap' \
> -        --server-socket-path=/usr/local/var/run/openvswitch
> -
> -``server-socket-path`` must be set to the value of ``ovs_rundir()`` which
> -typically resolves to ``/usr/local/var/run/openvswitch``.
> -
> -Many tools are available to view the contents of the pcap file. Once
> example is -tcpdump. Issue the following command to view the contents of
> ``pkts.pcap``::
> -
> -    $ tcpdump -r pkts.pcap
> -
> -More information on the pdump app and its usage can be found in the `DPDK
> docs -<http://dpdk.org/doc/guides/tools/pdump.html>`__.
> -
>  Jumbo Frames
>  ------------
> 
> diff --git a/Documentation/topics/dpdk/index.rst
> b/Documentation/topics/dpdk/index.rst
> index 52cacaef6..c9b231f06 100644
> --- a/Documentation/topics/dpdk/index.rst
> +++ b/Documentation/topics/dpdk/index.rst
> @@ -27,10 +27,17 @@ The DPDK Datapath
> 
>  .. toctree::
>     :maxdepth: 2
> +   :caption: Bridges and Ports
> 
>     bridge
>     phy
>     vhost-user
>     ring
> +
> +.. toctree::
> +   :maxdepth: 2
> +   :caption: Advanced Configuration
> +
>     pmd
>     qos
> +   pdump
> diff --git a/Documentation/topics/dpdk/pdump.rst
> b/Documentation/topics/dpdk/pdump.rst
> new file mode 100644
> index 000000000..f1a408989
> --- /dev/null
> +++ b/Documentation/topics/dpdk/pdump.rst
> @@ -0,0 +1,65 @@
> +..
> +      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.
> +
> +=====
> +pdump
> +=====
> +
> +pdump allows you to listen on DPDK ports and view the traffic that is
> +passing on them. To use this utility, one must have libpcap installed on
> the system.
> +Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and
> +``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
> +
> +.. warning::
> +
> +   A performance decrease is expected when using a monitoring application
> like
> +   the DPDK pdump app.
> +
> +To use pdump, simply launch OVS as usual, then navigate to the
> +``app/pdump`` directory in DPDK, ``make`` the application and run like
> so::
> +
> +    $ sudo ./build/app/dpdk-pdump -- \
> +        --pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
> +        --server-socket-path=/usr/local/var/run/openvswitch
> +
> +The above command captures traffic received on queue 0 of port 0 and
> +stores it in ``/tmp/pkts.pcap``. Other combinations of port numbers,
> +queues numbers and pcap locations are of course also available to use.
> +For example, to capture all packets that traverse port 0 in a single pcap
> file::
> +
> +    $ sudo ./build/app/dpdk-pdump -- \
> +        --pdump 'port=0,queue=*,rx-dev=/tmp/pkts.pcap,tx-
> dev=/tmp/pkts.pcap' \
> +        --server-socket-path=/usr/local/var/run/openvswitch
> +
> +``server-socket-path`` must be set to the value of ``ovs_rundir()``
> +which typically resolves to ``/usr/local/var/run/openvswitch``.
> +
> +Many tools are available to view the contents of the pcap file. Once
> +example is tcpdump. Issue the following command to view the contents of
> ``pkts.pcap``::
> +
> +    $ tcpdump -r pkts.pcap
> +
> +More information on the pdump app and its usage can be found in the
> +`DPDK documentation`__.
> +
> +__ http://dpdk.org/doc/guides/tools/pdump.html
> --
> 2.14.3
> 
> _______________________________________________
> dev mailing list
> dev@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev
Stephen Finucane April 16, 2018, 2:04 p.m. | #2
On Mon, 2018-04-09 at 15:17 +0000, Stokes, Ian wrote:
> Minor nit, would like to see a commit message here. I think you
> modify caption headers in the patch also, these could be kept in the
> final clean up patch of the series.

I've added the commit message and split the caption headers into a
separate patch.

Stephen

> Ian
> 
> > Signed-off-by: Stephen Finucane <stephen@that.guru>
> > ---
> >  Documentation/howto/dpdk.rst        | 39 ----------------------
> >  Documentation/topics/dpdk/index.rst |  7 ++++
> > Documentation/topics/dpdk/pdump.rst | 65
> > +++++++++++++++++++++++++++++++++++++
> >  3 files changed, 72 insertions(+), 39 deletions(-)  create mode 100644
> > Documentation/topics/dpdk/pdump.rst
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index c01bf7a39..1a72e90bf 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -85,45 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
> >      $ ovs-appctl -t ovsdb-server exit
> >      $ ovs-vsctl del-br br0
> > 
> > -pdump
> > ------
> > -
> > -pdump allows you to listen on DPDK ports and view the traffic that is
> > passing -on them. To use this utility, one must have libpcap installed on
> > the system.
> > -Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and -
> > ``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
> > -
> > -.. warning::
> > -  A performance decrease is expected when using a monitoring application
> > like
> > -  the DPDK pdump app.
> > -
> > -To use pdump, simply launch OVS as usual, then navigate to the
> > ``app/pdump`` -directory in DPDK, ``make`` the application and run like
> > so::
> > -
> > -    $ sudo ./build/app/dpdk-pdump -- \
> > -        --pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
> > -        --server-socket-path=/usr/local/var/run/openvswitch
> > -
> > -The above command captures traffic received on queue 0 of port 0 and
> > stores it -in ``/tmp/pkts.pcap``. Other combinations of port numbers,
> > queues numbers and -pcap locations are of course also available to use.
> > For example, to capture all -packets that traverse port 0 in a single pcap
> > file::
> > -
> > -    $ sudo ./build/app/dpdk-pdump -- \
> > -        --pdump 'port=0,queue=*,rx-dev=/tmp/pkts.pcap,tx-
> > dev=/tmp/pkts.pcap' \
> > -        --server-socket-path=/usr/local/var/run/openvswitch
> > -
> > -``server-socket-path`` must be set to the value of ``ovs_rundir()`` which
> > -typically resolves to ``/usr/local/var/run/openvswitch``.
> > -
> > -Many tools are available to view the contents of the pcap file. Once
> > example is -tcpdump. Issue the following command to view the contents of
> > ``pkts.pcap``::
> > -
> > -    $ tcpdump -r pkts.pcap
> > -
> > -More information on the pdump app and its usage can be found in the `DPDK
> > docs -<http://dpdk.org/doc/guides/tools/pdump.html>`__.
> > -
> >  Jumbo Frames
> >  ------------
> > 
> > diff --git a/Documentation/topics/dpdk/index.rst
> > b/Documentation/topics/dpdk/index.rst
> > index 52cacaef6..c9b231f06 100644
> > --- a/Documentation/topics/dpdk/index.rst
> > +++ b/Documentation/topics/dpdk/index.rst
> > @@ -27,10 +27,17 @@ The DPDK Datapath
> > 
> >  .. toctree::
> >     :maxdepth: 2
> > +   :caption: Bridges and Ports
> > 
> >     bridge
> >     phy
> >     vhost-user
> >     ring
> > +
> > +.. toctree::
> > +   :maxdepth: 2
> > +   :caption: Advanced Configuration
> > +
> >     pmd
> >     qos
> > +   pdump
> > diff --git a/Documentation/topics/dpdk/pdump.rst
> > b/Documentation/topics/dpdk/pdump.rst
> > new file mode 100644
> > index 000000000..f1a408989
> > --- /dev/null
> > +++ b/Documentation/topics/dpdk/pdump.rst
> > @@ -0,0 +1,65 @@
> > +..
> > +      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.
> > +
> > +=====
> > +pdump
> > +=====
> > +
> > +pdump allows you to listen on DPDK ports and view the traffic that is
> > +passing on them. To use this utility, one must have libpcap installed on
> > the system.
> > +Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and
> > +``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
> > +
> > +.. warning::
> > +
> > +   A performance decrease is expected when using a monitoring application
> > like
> > +   the DPDK pdump app.
> > +
> > +To use pdump, simply launch OVS as usual, then navigate to the
> > +``app/pdump`` directory in DPDK, ``make`` the application and run like
> > so::
> > +
> > +    $ sudo ./build/app/dpdk-pdump -- \
> > +        --pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
> > +        --server-socket-path=/usr/local/var/run/openvswitch
> > +
> > +The above command captures traffic received on queue 0 of port 0 and
> > +stores it in ``/tmp/pkts.pcap``. Other combinations of port numbers,
> > +queues numbers and pcap locations are of course also available to use.
> > +For example, to capture all packets that traverse port 0 in a single pcap
> > file::
> > +
> > +    $ sudo ./build/app/dpdk-pdump -- \
> > +        --pdump 'port=0,queue=*,rx-dev=/tmp/pkts.pcap,tx-
> > dev=/tmp/pkts.pcap' \
> > +        --server-socket-path=/usr/local/var/run/openvswitch
> > +
> > +``server-socket-path`` must be set to the value of ``ovs_rundir()``
> > +which typically resolves to ``/usr/local/var/run/openvswitch``.
> > +
> > +Many tools are available to view the contents of the pcap file. Once
> > +example is tcpdump. Issue the following command to view the contents of
> > ``pkts.pcap``::
> > +
> > +    $ tcpdump -r pkts.pcap
> > +
> > +More information on the pdump app and its usage can be found in the
> > +`DPDK documentation`__.
> > +
> > +__ http://dpdk.org/doc/guides/tools/pdump.html
> > --
> > 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 c01bf7a39..1a72e90bf 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -85,45 +85,6 @@  To stop ovs-vswitchd & delete bridge, run::
     $ ovs-appctl -t ovsdb-server exit
     $ ovs-vsctl del-br br0
 
-pdump
------
-
-pdump allows you to listen on DPDK ports and view the traffic that is passing
-on them. To use this utility, one must have libpcap installed on the system.
-Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and
-``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
-
-.. warning::
-  A performance decrease is expected when using a monitoring application like
-  the DPDK pdump app.
-
-To use pdump, simply launch OVS as usual, then navigate to the ``app/pdump``
-directory in DPDK, ``make`` the application and run like so::
-
-    $ sudo ./build/app/dpdk-pdump -- \
-        --pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
-        --server-socket-path=/usr/local/var/run/openvswitch
-
-The above command captures traffic received on queue 0 of port 0 and stores it
-in ``/tmp/pkts.pcap``. Other combinations of port numbers, queues numbers and
-pcap locations are of course also available to use. For example, to capture all
-packets that traverse port 0 in a single pcap file::
-
-    $ sudo ./build/app/dpdk-pdump -- \
-        --pdump 'port=0,queue=*,rx-dev=/tmp/pkts.pcap,tx-dev=/tmp/pkts.pcap' \
-        --server-socket-path=/usr/local/var/run/openvswitch
-
-``server-socket-path`` must be set to the value of ``ovs_rundir()`` which
-typically resolves to ``/usr/local/var/run/openvswitch``.
-
-Many tools are available to view the contents of the pcap file. Once example is
-tcpdump. Issue the following command to view the contents of ``pkts.pcap``::
-
-    $ tcpdump -r pkts.pcap
-
-More information on the pdump app and its usage can be found in the `DPDK docs
-<http://dpdk.org/doc/guides/tools/pdump.html>`__.
-
 Jumbo Frames
 ------------
 
diff --git a/Documentation/topics/dpdk/index.rst b/Documentation/topics/dpdk/index.rst
index 52cacaef6..c9b231f06 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -27,10 +27,17 @@  The DPDK Datapath
 
 .. toctree::
    :maxdepth: 2
+   :caption: Bridges and Ports
 
    bridge
    phy
    vhost-user
    ring
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Advanced Configuration
+
    pmd
    qos
+   pdump
diff --git a/Documentation/topics/dpdk/pdump.rst b/Documentation/topics/dpdk/pdump.rst
new file mode 100644
index 000000000..f1a408989
--- /dev/null
+++ b/Documentation/topics/dpdk/pdump.rst
@@ -0,0 +1,65 @@ 
+..
+      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.
+
+=====
+pdump
+=====
+
+pdump allows you to listen on DPDK ports and view the traffic that is passing
+on them. To use this utility, one must have libpcap installed on the system.
+Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and
+``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
+
+.. warning::
+
+   A performance decrease is expected when using a monitoring application like
+   the DPDK pdump app.
+
+To use pdump, simply launch OVS as usual, then navigate to the ``app/pdump``
+directory in DPDK, ``make`` the application and run like so::
+
+    $ sudo ./build/app/dpdk-pdump -- \
+        --pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
+        --server-socket-path=/usr/local/var/run/openvswitch
+
+The above command captures traffic received on queue 0 of port 0 and stores it
+in ``/tmp/pkts.pcap``. Other combinations of port numbers, queues numbers and
+pcap locations are of course also available to use. For example, to capture all
+packets that traverse port 0 in a single pcap file::
+
+    $ sudo ./build/app/dpdk-pdump -- \
+        --pdump 'port=0,queue=*,rx-dev=/tmp/pkts.pcap,tx-dev=/tmp/pkts.pcap' \
+        --server-socket-path=/usr/local/var/run/openvswitch
+
+``server-socket-path`` must be set to the value of ``ovs_rundir()`` which
+typically resolves to ``/usr/local/var/run/openvswitch``.
+
+Many tools are available to view the contents of the pcap file. Once example is
+tcpdump. Issue the following command to view the contents of ``pkts.pcap``::
+
+    $ tcpdump -r pkts.pcap
+
+More information on the pdump app and its usage can be found in the `DPDK
+documentation`__.
+
+__ http://dpdk.org/doc/guides/tools/pdump.html