Re: [ovs-dev] [PATCH 5/6] doc: Convert ovs-test to rST

[Stephen Finucane]

On Thu, 2017-04-13 at 21:43 -0700, Ben Pfaff wrote:
> From: Stephen Finucane 
> 
> Signed-off-by: Stephen Finucane 
> Signed-off-by: Ben Pfaff 

Same comment on the 'Synopsis' section. Other than that, LGTM.

Acked-by: Stephen Finucane 
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH 5/6] doc: Convert ovs-test to rST

[Ben Pfaff]

From: Stephen Finucane 

Signed-off-by: Stephen Finucane 
Signed-off-by: Ben Pfaff 
---
 Documentation/automake.mk |   1 +
 Documentation/conf.py |   3 +
 Documentation/ref/index.rst   |   1 +
 Documentation/ref/ovs-test.8.rst  | 163 
 Documentation/ref/ovs-vlan-test.8.rst |  11 +-
 debian/openvswitch-test.manpages  |   1 -
 manpages.mk   | 337 --
 utilities/automake.mk |   3 -
 utilities/ovs-test.8.in   | 144 ---
 9 files changed, 172 insertions(+), 492 deletions(-)
 create mode 100644 Documentation/ref/ovs-test.8.rst
 delete mode 100644 utilities/ovs-test.8.in

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 762255277102..cff33cc659cc 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -137,6 +137,7 @@ endif
 
 # rST formatted manpages under Documentation/ref.
 RST_MANPAGES = \
+   ovs-test.8.rst \
ovs-vlan-test.8.rst
 
 # The GNU standards say that these variables should control
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 8671a097d17e..1737d771ad70 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -328,6 +328,9 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
+('ref/ovs-test.8', 'ovs-test',
+ u'Check Linux drivers for performance, vlan and L3 tunneling problems',
+ [author], 8),
 ('ref/ovs-vlan-test.8', 'ovs-vlan-test',
  u'Check Linux drivers for problems with vlan traffic',
  [author], 8)
diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst
index 6b368809c11b..3e2f8d5d96e0 100644
--- a/Documentation/ref/index.rst
+++ b/Documentation/ref/index.rst
@@ -39,6 +39,7 @@ time:
 .. toctree::
:maxdepth: 3
 
+   ovs-test.8
ovs-vlan-test.8
 
 The remainder are still in roff format can be found below:
diff --git a/Documentation/ref/ovs-test.8.rst b/Documentation/ref/ovs-test.8.rst
new file mode 100644
index ..f902d9c3b05a
--- /dev/null
+++ b/Documentation/ref/ovs-test.8.rst
@@ -0,0 +1,163 @@
+
+ovs-test
+
+
+Synopsis
+
+
+**ovs-test** -s *port*
+
+**ovs-test** -c *server1* *server2* [**-b** *targetbandwidth*] [**-i** 
*testinterval*] [**-d**]
+  [**-l** *vlantag*] [**-t** *tunnelmodes*]
+
+Description
+===
+
+The :program:`ovs-test` program may be used to check for problems sending
+802.1Q or GRE traffic that Open vSwitch may uncover. These problems, for
+example, can occur when Open vSwitch is used to send 802.1Q traffic through
+physical interfaces running certain drivers of certain Linux kernel versions.
+To run a test, configure IP addresses on `server1` and `server2` for interfaces
+you intended to test. These interfaces could also be already configured OVS
+bridges that have a physical interface attached to them. Then, on one of the
+nodes, run :program:`ovs-test` in server mode and on the other node run it in
+client mode. The client will connect to :program:`ovs-test` server and schedule
+tests between both of them. The :program:`ovs-test` client will perform UDP and
+TCP tests.
+
+UDP tests can report packet loss and achieved bandwidth for various datagram
+sizes. By default target bandwidth for UDP tests is 1Mbit/s.
+
+TCP tests report only achieved bandwidth, because kernel TCP stack takes care
+of flow control and packet loss. TCP tests are essential to detect potential
+TSO related issues.
+
+To determine whether Open vSwitch is encountering any problems, the user must
+compare packet loss and achieved bandwidth in a setup where traffic is being
+directly sent and in one where it is not. If in the 802.1Q or L3 tunneled tests
+both :program:`ovs-test` processes are unable to communicate or the achieved
+bandwidth is much lower compared to direct setup, then, most likely, Open
+vSwitch has encountered a pre-existing kernel or driver bug.
+
+Some examples of the types of problems that may be encountered are:
+
+- When NICs use VLAN stripping on receive they must pass a pointer to a
+  `vlan_group` when reporting the stripped tag to the networking core. If no
+  `vlan_group` is in use then some drivers just drop the extracted tag.
+  Drivers are supposed to only enable stripping if a `vlan_group` is registered
+  but not all of them do that.
+
+- On receive, some drivers handle priority tagged packets specially and don't
+  pass the tag onto the network stack at all, so Open vSwitch never has a
+  chance to see it.
+
+- Some drivers size their receive buffers based on whether a `vlan_group` is
+  enabled, meaning that a maximum size packet with a VLAN tag will not fit if
+  no `vlan_group` is configured.
+
+- On transmit, some drivers expect that VLAN acceleration will be used if it is
+  available, which can