[dpdk-dev] [PATCH v8] drivers/net:new PMD using tun/tap host interface

[Mcnamara, John]

Hi,

Some doc comments below. Apologies, for the late review, I didn't see
the docs inline.



> -Original Message-
> From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Keith Wiles
> Sent: Thursday, October 13, 2016 5:11 PM
> To: dev at dpdk.org
> Cc: pmatilai at redhat.com; yuanhan.liu at linux.intel.com; Yigit, Ferruh
> 
> Subject: [dpdk-dev] [PATCH v8] drivers/net:new PMD using tun/tap host
> interface
> 
> The rte_eth_tap.c PMD creates a device using TUN/TAP interfaces on the
> local host. The PMD allows for DPDK and the host to communicate using a
> raw device interface on the host and in the DPDK application. The device
> created is a Tap device with a L2 packet header.
> 
> v8 - Fix issue with tap_tx_queue_setup() not return zero on success.
> v7 - Reword the comment in common_base and fix the data->name issue
> v6 - fixed the checkpatch issues
> v5 - merge in changes from list review see related emails
>  fixed many minor edits
> v4 - merge with latest driver changes
> v3 - fix includes by removing ifdef for other type besides Linux
>  Fix the copyright notice in the Makefile
> v2 - merge all of the patches into one patch
>  Fix a typo on naming the tap device
>  Update the maintainers list
> 
> Signed-off-by: Keith Wiles 
> ---
>  MAINTAINERS |   5 +
>  config/common_base  |   9 +
>  config/common_linuxapp  |   1 +
>  doc/guides/nics/tap.rst | 138 ++
>  drivers/net/Makefile|   1 +
>  drivers/net/tap/Makefile|  57 +++
>  drivers/net/tap/rte_eth_tap.c   | 756


You need to add "tap" to the doc/guides/nics/index.rst file to
include the tap.rst in the docs.


> +
> +Tun/Tap Poll Mode Driver
> +
> +
> +The rte_eth_tap.c PMD creates a device using TUN/TAP interfaces on the
> +local host. The PMD allows for DPDK and the host to communicate using a
> +raw device interface on the host and in the DPDK application.
> +
> +The device created is a TAP device, which sends/receives packet in a
> +raw format with a L2 header. The usage for a TAP PMD is for
> +connectivity to the local host using a TAP interface. When the TAP PMD
> +is initialized it will create a number of tap devices in the host
> +accessed via 'ifconfig -a' or 'ip' command. The commands can be used to
> assign and query the virtual like device.

The apostrophes around the commands should be replaced with `` to render
them as fixed width.


> +
> +These TAP interfaces can be used with wireshark or tcpdump or
> +Pktgen-DPDK along with being able to be used as a network connection to
> +the DPDK application. The method enable one or more interfaces is to
> +use the --vdev=net_tap option on the DPDK application  command line.
> +Each --vdev=net_tap option give will create an interface named dtap0,
> dtap1, ... and so forth.

Same here, include any commands or variable names in backticks to render
them as fixed width in the text: ``--vdev=net_tap``


> +
> +.. code-block:: console
> +
> +   The interfaced name can be changed by adding the iface=foo0
> +   e.g. --vdev=net_tap,iface=foo0 --vdev=net_tap,iface=foo1, ...

This would be better formatted as follows:

The interfaced name can be changed by adding the ``iface=foo0``, for example::

   --vdev=eth_tap,iface=foo0 --vdev=eth_tap,iface=foo1, ...



> +If you have a Network Stack in your DPDK application or something like
> +it you can utilize that stack to handle the network protocols. Plus you
> +would be able to address the interface using an IP address assigned to
> the internal interface.
> +
> +A very crude test you can do the following:
> +
> +Apply the patch below and make sure you have socat installed on your
> system.

There is no patch below in the docs. ;-) Also, this would probably be better
as a new section. Something like:


Example
---

The following is a simple example of using the TUN/TAP PMD with the Pktgen
packet generator. It requires that the ``socat`` utility is installed on the
test system.

Build DPDK, then pull down Pktgen and build pktgen using the DPDK SDK/Target
used to build the dpdk you pulled down.

...

> +
> +Build DPDK, then pull down Pktgen and build pktgen using the DPDK
> +SDK/Target used to build the dpdk you pulled down.
> +
> +Run pktgen from the pktgen repo directory in an xterm:
> +Note: change the -b options to blacklist all of your physical ports.
> The
> +  following command line is all one line.


The RST syntax for Note and the indentation are wrong here. Also the note
would be better after the example. Something like:


.. Note:

   Change the ``-b`` options to blacklist 

[dpdk-dev] [PATCH v8] drivers/net:new PMD using tun/tap host interface

[Keith Wiles]

The rte_eth_tap.c PMD creates a device using TUN/TAP interfaces
on the local host. The PMD allows for DPDK and the host to
communicate using a raw device interface on the host and in
the DPDK application. The device created is a Tap device with
a L2 packet header.

v8 - Fix issue with tap_tx_queue_setup() not return zero on success.
v7 - Reword the comment in common_base and fix the data->name issue
v6 - fixed the checkpatch issues
v5 - merge in changes from list review see related emails
 fixed many minor edits
v4 - merge with latest driver changes
v3 - fix includes by removing ifdef for other type besides Linux
 Fix the copyright notice in the Makefile
v2 - merge all of the patches into one patch
 Fix a typo on naming the tap device
 Update the maintainers list

Signed-off-by: Keith Wiles 
---
 MAINTAINERS |   5 +
 config/common_base  |   9 +
 config/common_linuxapp  |   1 +
 doc/guides/nics/tap.rst | 138 ++
 drivers/net/Makefile|   1 +
 drivers/net/tap/Makefile|  57 +++
 drivers/net/tap/rte_eth_tap.c   | 756 
 drivers/net/tap/rte_pmd_tap_version.map |   4 +
 mk/rte.app.mk   |   1 +
 9 files changed, 972 insertions(+)
 create mode 100644 doc/guides/nics/tap.rst
 create mode 100644 drivers/net/tap/Makefile
 create mode 100644 drivers/net/tap/rte_eth_tap.c
 create mode 100644 drivers/net/tap/rte_pmd_tap_version.map

diff --git a/MAINTAINERS b/MAINTAINERS
index cd8d167..f905709 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -394,6 +394,11 @@ F: doc/guides/nics/pcap_ring.rst
 F: app/test/test_pmd_ring.c
 F: app/test/test_pmd_ring_perf.c

+Tap PMD
+M: Keith Wiles 
+F: drivers/net/tap
+F: doc/guides/nics/tap.rst
+
 Null Networking PMD
 M: Tetsuya Mukawa 
 F: drivers/net/null/
diff --git a/config/common_base b/config/common_base
index f5d2eff..47ef843 100644
--- a/config/common_base
+++ b/config/common_base
@@ -592,3 +592,12 @@ CONFIG_RTE_APP_TEST_RESOURCE_TAR=n
 CONFIG_RTE_TEST_PMD=y
 CONFIG_RTE_TEST_PMD_RECORD_CORE_CYCLES=n
 CONFIG_RTE_TEST_PMD_RECORD_BURST_STATS=n
+
+#
+# Compile the TAP PMD
+#
+# The TAP PMD is currently only built for Linux and the
+# option is enabled by default in common_linuxapp file,
+# set to 'n' in the common_base file.
+#
+CONFIG_RTE_LIBRTE_PMD_TAP=n
diff --git a/config/common_linuxapp b/config/common_linuxapp
index 2483dfa..782b503 100644
--- a/config/common_linuxapp
+++ b/config/common_linuxapp
@@ -44,3 +44,4 @@ CONFIG_RTE_LIBRTE_PMD_VHOST=y
 CONFIG_RTE_LIBRTE_PMD_AF_PACKET=y
 CONFIG_RTE_LIBRTE_POWER=y
 CONFIG_RTE_VIRTIO_USER=y
+CONFIG_RTE_LIBRTE_PMD_TAP=y
diff --git a/doc/guides/nics/tap.rst b/doc/guides/nics/tap.rst
new file mode 100644
index 000..bffc649
--- /dev/null
+++ b/doc/guides/nics/tap.rst
@@ -0,0 +1,138 @@
+..  BSD LICENSE
+Copyright(c) 2016 Intel Corporation. All rights reserved.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+* Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in
+the documentation and/or other materials provided with the
+distribution.
+* Neither the name of Intel Corporation nor the names of its
+contributors may be used to endorse or promote products derived
+from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Tun/Tap Poll Mode Driver
+
+
+The rte_eth_tap.c PMD creates a device using TUN/TAP interfaces on the local
+host. The PMD allows for DPDK and the host to communicate using a raw device
+interface on the host and in the DPDK application.
+
+The device created is a TAP device, which sends/receives packet in a raw format
+with a L2 header. The usage for a TAP PMD is for connectivity to the local host
+using a TAP int