[dpdk-dev] [PATCH 1/8] doc: add doc to explain compiling and testing of PMD

[Shijith Thotton <shijith.thotton@caviumnetworks.com>]

Add a section in NIC drivers documentation to explain compiling and
testing of a PMD. It also mentions about host setup, which is required
before running testpmd.

Add label "testpmd_ug" to refer user guide.

Signed-off-by: Shijith Thotton <shijith.thotton@caviumnetworks.com>
---
 doc/guides/nics/build_and_test.rst  | 134 ++++++++++++++++++++++++++++++++++++
 doc/guides/nics/index.rst           |   1 +
 doc/guides/testpmd_app_ug/index.rst |   2 +
 3 files changed, 137 insertions(+)
 create mode 100644 doc/guides/nics/build_and_test.rst

diff --git a/doc/guides/nics/build_and_test.rst b/doc/guides/nics/build_and_test.rst
new file mode 100644
index 0000000..4b87af6
--- /dev/null
+++ b/doc/guides/nics/build_and_test.rst
@@ -0,0 +1,134 @@
+..  BSD LICENSE
+    Copyright(c) 2017 Cavium, Inc.. 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 Cavium, Inc. 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(S) 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.
+
+.. _pmd_build_and_test:
+
+Compiling and testing a PMD for a NIC
+=====================================
+
+This section demonstrates how to compile and run a Poll Mode Driver (PMD) for
+the available Network Interface Cards in DPDK using TestPMD.
+
+TestPMD is one of the reference applications distributed with the DPDK. Its main
+purpose is to forward packets between Ethernet ports on a network interface and
+as such is the best way to test a PMD.
+
+Refer to the :ref:`testpmd application user guide <testpmd_ug>` for detailed
+information on how to build and run testpmd.
+
+Driver Compilation
+------------------
+
+To compile a PMD for Linux x86_64 gcc target, run the following "make" command.
+It will also build testpmd.
+
+.. code-block:: console
+
+   cd <DPDK-source-directory>
+   make install T=x86_64-native-linuxapp-gcc
+
+
+FreeBSD targets should use "gmake" command instead of "make".
+
+For more information, refer to the :ref:`Getting Started Guide for Linux <linux_gsg>`
+or :ref:`Getting Started Guide for FreeBSD <freebsd_gsg>` depending on your platform.
+
+Running testpmd in Linux
+------------------------
+
+This section demonstrates how to setup and run ``testpmd`` in Linux.
+
+#. Mount huge pages:
+
+   .. code-block:: console
+
+      mkdir /mnt/huge
+      mount -t hugetlbfs nodev /mnt/huge
+
+#. Request huge pages:
+
+   .. code-block:: console
+
+      echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
+
+#. Load ``igb_uio`` or ``vfio-pci`` driver:
+
+   .. code-block:: console
+
+      modprobe uio
+      insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
+
+   or
+
+   .. code-block:: console
+
+      modprobe vfio-pci
+
+#. Setup VFIO permissions for regular users before binding to ``vfio-pci``:
+
+   .. code-block:: console
+
+      sudo chmod a+x /dev/vfio
+
+      sudo chmod 0666 /dev/vfio/*
+
+#. Bind the adapters to ``igb_uio`` or ``vfio-pci`` loaded in the previous step:
+
+   .. code-block:: console
+
+      ./usertools/dpdk-devbind.py --bind igb_uio DEVICE1 DEVICE2 ...
+
+   Or setup VFIO permissions for regular users and then bind to ``vfio-pci``:
+
+   .. code-block:: console
+
+      ./usertools/dpdk-devbind.py --bind vfio-pci DEVICE1 DEVICE2 ...
+
+   .. note::
+
+      DEVICE1, DEVICE2 are specified via PCI "domain:bus:slot.func" syntax or
+      "bus:slot.func" syntax.
+
+#. Start ``testpmd`` with basic parameters:
+
+   .. code-block:: console
+
+      ./x86_64-native-linuxapp-gcc/app/testpmd -l 0-3 -n 4 -- -i
+
+   Successful execution will show initialization messages from EAL, PMD and
+   testpmd application. A prompt will be displayed at the end for user commands
+   as interactive mode (``-i``) is on.
+
+   .. code-block:: console
+
+      testpmd>
+
+   Refer to the :ref:`testpmd runtime functions <testpmd_runtime>` for a list
+   of available commands.
diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index 4537113..245b53d 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -36,6 +36,7 @@ Network Interface Controller Drivers
     :numbered:
 
     overview
+    build_and_test
     avp
     bnx2x
     bnxt
diff --git a/doc/guides/testpmd_app_ug/index.rst b/doc/guides/testpmd_app_ug/index.rst
index 1c39a17..61a9121 100644
--- a/doc/guides/testpmd_app_ug/index.rst
+++ b/doc/guides/testpmd_app_ug/index.rst
@@ -28,6 +28,8 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+.. _testpmd_ug:
+
 Testpmd Application User Guide
 ==============================
 
-- 
1.8.3.1