From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from NAM02-BL2-obe.outbound.protection.outlook.com (mail-bl2nam02on0053.outbound.protection.outlook.com [104.47.38.53]) by dpdk.org (Postfix) with ESMTP id F366B1DB1 for ; Tue, 11 Apr 2017 20:58:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=CAVIUMNETWORKS.onmicrosoft.com; s=selector1-cavium-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=18bvMNYNG17Ss7fkMPvc7vuUW8qBqNQUdEh1PT3vEPs=; b=inBnPwzXzlsEkVP5ftCooRHDHHivQXz9xO2twhI+5qL5iCzlM37TfSzjyKwGMWUOfl34wYWNH05zKl8iKwr+QuWWx48rJUs561p1KQUGvooSWVPgqoGdWq1h1n3PXbDzuFI04x1r+AE8RuKaj5a7HLaViyCTPnOE8iynxGZP2/M= Authentication-Results: intel.com; dkim=none (message not signed) header.d=none;intel.com; dmarc=none action=none header.from=caviumnetworks.com; Received: from lio357.in.caveonetworks.com (14.140.2.178) by DM3PR07MB2284.namprd07.prod.outlook.com (10.164.33.158) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256) id 15.1.1019.17; Tue, 11 Apr 2017 18:58:20 +0000 From: Shijith Thotton To: Ferruh Yigit , John McNamara Cc: dev@dpdk.org, Jerin Jacob Date: Wed, 12 Apr 2017 00:26:41 +0530 Message-Id: <1491937010-16553-2-git-send-email-shijith.thotton@caviumnetworks.com> X-Mailer: git-send-email 1.8.3.1 In-Reply-To: <1491937010-16553-1-git-send-email-shijith.thotton@caviumnetworks.com> References: <1491465117-11252-1-git-send-email-shijith.thotton@caviumnetworks.com> <1491937010-16553-1-git-send-email-shijith.thotton@caviumnetworks.com> MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [14.140.2.178] X-ClientProxiedBy: MAXPR01CA0027.INDPRD01.PROD.OUTLOOK.COM (10.164.147.34) To DM3PR07MB2284.namprd07.prod.outlook.com (10.164.33.158) X-MS-Office365-Filtering-Correlation-Id: 16ccc166-9dec-4b06-0e60-08d4810cb9e6 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(22001)(201703131423075)(201703031133081); SRVR:DM3PR07MB2284; X-Microsoft-Exchange-Diagnostics: 1; DM3PR07MB2284; 3:tZe7MBqOQnYlroo24po3Y08XJEKFd6b7l3KY3xOtuVDHYdHOZMXAUqG0Z+5h8GgRAgKIP4uNAuH/3VEyNCKI8/ZVfQgAxEsWh1xkpiOtSIP+yYsUebCOQpiyBuJCWvtZ76FJMcXeutbKf1CfD7gKwYXFDzvwj4JLXOgz+sv1dmuillHcWJvurJq1jEafy2G69jFbtNWhlRi4lUD9DcIB9w21XVXh3AKviIl8EIP/PLVktfH3zM4J0uwVf0LjLR0fTOCGjCjCK+KbqA2oGT97ITdqXE27TlEPq31/9r2YurcTeyVSexqBo1Tk4fBj6CZNLfUQmzH6i8F8oToYFTvF+w==; 25:RP6/ZrUGexyxUXmJhWBAQj9XvPoJ/A6J6xgscrMnT1zI0BmoeLGfBHUmiws1REMWc5XmHtUyybj4djCxbWvA9Jadzp6xzL9kBjqSPXVfP/Ez6xCVhRuxW4vIfgK7DpZyzY3ngI+84qJ3GpLGs654I4eiFyqdkWIX97tEuoxus+LjWBNYp5swubBJKh+RMYL0pKJk6Q/ylqSC3K8vCY9TUkn5WscfwgSN7WS75QBkAEm84vZqd8+EYNvyfbp2G5S4XPiMXOaXgHKWsDO/xDdcDhyi4zy1VxLfzBqc3fOZEMKrnp8HMI2pRYO/M3tIgt1hSjeBu71cFX7olb+gJQeTSVpy0DC35fQMmbz1POiKfacTNGIcpyZv4u02QLwWJfOQ4pclb8aidBeIKI3Dsf+Akm+k/Wg0+MdEG2Z4QOiVhnOyaf45jNw3kuHSv5u+hBXv26aC/NCl0f+Ek9mgJ0Q3HQ== X-Microsoft-Exchange-Diagnostics: 1; DM3PR07MB2284; 31:pCwyRAAOE1OPX+OHl23LFkZZQ4yV0wWk8/JFd79PRHM1mmzgV78nd+Jf5dTINND730YdarHxchfRfG2J/8Hc8+P82QZTbaOCDJcDgzf+Dbab0MX24Pr0zhuWMC7jsB5fMP0xmh/bcwfCicGOYutMfsOlxyf7iJJ/ExxmTBSUSFePvhGWqEROwWtzrgv5//e+BoRqvaMSmNvYiHseH2lAmm3R1nkW8KzNiXHh1tJlnq4=; 20:fiRyFp4ZZfQ9+RpNwOS6tz7869XkOY4pgT74Tp8XRAdx5Bap0HWd5CMRG6Fe32e6t5kUGDB+APWsz+/AEEXMBIzkMc5n+8zagwUC5axbs7/RHM9LcpTkkUxaF8x/v72WEeRNoOPPKoQbHGh0a7mJvi1aQ+0fVKLn7RJFeGa04RjQlnk89scvN1Ma2Y/V3tBrl9sTocuHllFiaxyiJ2YgWRjq+zQQR64rPm5+2setdG6tgZnp+G5VSIK0vqIgjhFwJy7t2U4PhPy6wyY5iULLMSTHDFLZy4MTLUY0og3X3sEWCmzJnO+TtxLLvrUWdATAIj8iZaKKZPFfxbfUPtfq46NOB5klP5nS2fs+aN+B84iBOskt8jWEwkU8vWhBbR7tGnAkkT49ZQcciBzeq7+E3rp4sxnAZ9JJfWxwqBFfxInjAneo965WC7Dr7GjrDxSOnegGT10jSDC+aC7xpK1XnIKBhN9OMWWnrk53xgpjf4Fts0IFIZsPqskMawTmFBklO2fAZ9+v3ircpgBMModBCDvT06kdHYHpWgoeD8nSGoKgGn8wo4KPqBaif90AffWmWBMxaqHYWsOuTGIwecm5FoBtkzlaDVP+/iuQq3AlIPI= X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(278428928389397)(228905959029699); X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040450)(601004)(2401047)(8121501046)(5005006)(3002001)(10201501046)(93006095)(6041248)(20161123562025)(20161123560025)(201703131423075)(201702281528075)(201703061421075)(20161123555025)(20161123564025)(6072148); SRVR:DM3PR07MB2284; BCL:0; PCL:0; RULEID:; SRVR:DM3PR07MB2284; X-Microsoft-Exchange-Diagnostics: 1; DM3PR07MB2284; 4:U1GZm/LzlehdGRvv1KE4X0t/6Ow9VBnF6zyIEdtDcNHrnw3a8UAKrCx2pNpXUiSstRXEUhZDRBuduUEPLMuZn/h6B916crXn/q3AiGHbWlIGlEvsh/CMz61fU1ytXpMRI5w+s6wBF6wbNTapqhIt7F8RSEv5QjqBomE6smjms5+J3aSMZ0HiUn8QWzEfDh+dBN78PtJjjoy0VJjW1pyHOFjTROvvFR+96mG2Dx4eBec3d8MGicoU6AlF3E6f1E4dWeNh31WG5dwKk9dpaeBxxvXmOkbSPKAcQgk+Aim2TcPXfqefmAV4aTDfF0tuKzhHqZZc25ctGc/+5r4vzDjSJ0OIfdpu9JYMSQlwBElPLykkYQnlHkq1rlhfxgWkis0JgwCzuDVLi03GqWuJf3CTPPbzaKnaIY3aKwzCyt+kSDMAgF+9Fv39IVJKwUjI/CWA8ln/sUWcvxYmxomFQOisoCATLu0+DAT0mgdVlfpGQMJbGQmY70iavUlTCHzdmwhT49h5v5P3VHHnCxRG8QdDwGK72RUlKttET0Bmx6dEKzAQnxuDgKfT0ILhuvTG81403yTv7D270hWSE33OBdhHwmR6cANWth/KrK41b5AEJWOolxNOMcRtuFBmNTKYyGy7plEox/T7Y9MkWD443cMiGh5qq+rbpgHP4qqgWf0tlCk9Zf47Gi8wPvdEL1xA5YaLyNq3tngoiGBDEOQXAMF3Dy+WmvZh402sjtvY0FugjYgajw9oQXr8kuNPuwGy5LDwaS9bazEtRoWdJQgN3p5Gmg== X-Forefront-PRVS: 0274272F87 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10009020)(4630300001)(6009001)(39840400002)(39400400002)(39410400002)(39850400002)(39450400003)(2906002)(6512007)(36756003)(7736002)(53936002)(4326008)(305945005)(189998001)(33646002)(5009440100003)(50466002)(107886003)(81166006)(8676002)(48376002)(50226002)(50986999)(76176999)(38730400002)(5660300001)(6486002)(47776003)(42882006)(6666003)(4720700003)(66066001)(2950100002)(6506006)(5003940100001)(3846002)(42186005)(6116002)(25786009)(110426004); DIR:OUT; SFP:1101; SCL:1; SRVR:DM3PR07MB2284; H:lio357.in.caveonetworks.com; FPR:; SPF:None; MLV:nov; PTR:InfoNoRecords; LANG:en; X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; DM3PR07MB2284; 23:QtKLY5O/DtuyhgPDRuIP/LkC9iZDdS8y/UqFfnxZJ?= =?us-ascii?Q?VnFw4RRtXiPB3tBP0kaE18MsBuK6xv51zI+mSji/XNwVewaPbNPsNcpqMEjJ?= =?us-ascii?Q?Z9hi7vOfjiZWHDFmouLyCckMblLwAh2WvPzq9NzrVjj9qlMT+J5bskrjhAT7?= =?us-ascii?Q?OwUlvKrgkG94YpoVZSbvmzP+rHQ4wQ246ph9rLO5usMATGeQtNxAszWl2XtT?= =?us-ascii?Q?0u9VfjwF/1QHrTD2KR7XrYHcjjr8hdz/ZG4UAqXYU1ggPss8fDQTuFbvDfCs?= =?us-ascii?Q?WHbUAfR35hfyaRDmtDEamX0rdUc/gW707LIfuQbRjZn+vaeSio0g8mYkb1ps?= =?us-ascii?Q?vaiYY8rfqeILL5Jdx6UV9kmbqZG2JNBiqELIYd/Jv3Ze+PzUwAR3xnA/zJtY?= =?us-ascii?Q?4pOxRIaPc8p9EyexLMR85OCfhp0q3XHrd1Fw/9sdN5ubtYD+BOTtVS9kVUw7?= =?us-ascii?Q?Yi3B7Vut5t+rrZpjf2tndhpLoK2Xcu07wIx+vsxFKnONI3aocFw6NpOU/L0j?= =?us-ascii?Q?pNA7uyBJ1Dz+/2+9WCJ5fMyd0z7YeZSp/SuZNhkzUEI88y9zRZeEciOeS4re?= =?us-ascii?Q?hlEl5/CwaXUKh/yfcKMHkkLrP34uFLwfRGOOZJo2LwM6qjQyDHJle4INSnOW?= =?us-ascii?Q?a1C0mapP01T/+VtPizjnRnZO56pXvg4748A4QteQYfR6QWSw1AOGz1QXXuVm?= =?us-ascii?Q?ikjVQXZY5DTaX8J7nkszzMvyAaW0SEKdDuHV5+ZGh7qZvHmtZUFeBqcNhkv1?= =?us-ascii?Q?XEmTbqqR4EPaEtD0a8aQrusbivVpRKk14wyh+FE9bYY4DCMN6Dsxa7CV9r3b?= =?us-ascii?Q?EJ0Yz+3tS7cCSBzlmwpzOLbzXdghtGpnEDPmuMEYloWIxBp/xaEOlKgDkfPr?= =?us-ascii?Q?XqHWwS4lbXR2mbODNbxhbsKezqUqKsDTTO4uKjKFs09kttLDoDhfngH7MXHW?= =?us-ascii?Q?HrDXDpRIM//wqbprMpussM9kF8VUROuN0XMi3NlrX/QNUvfgH7UA9sj8leWI?= =?us-ascii?Q?Jn+FlnB2x9+0CTXnRDYbXc1wqBXSDyvpaW3IQe0sGl7x4J9M7rL0wp6x5fL5?= =?us-ascii?Q?8038O/lKgtCBmtOdYVbt3YmZxZn?= X-Microsoft-Exchange-Diagnostics: 1; DM3PR07MB2284; 6:b+Fn6pP5x8i+qoxn+k1nUrNMvUcs1mluLt0BnurIu2cfDiaMg5UAoSTZQCcJUUdT07d6XtQ0qCUuHgx5iCsB9++LryPOt3m79P4qlkE/qFpB0ns8VuoPOI+fbLvtmgqZxwuSGD14c9d66p+Xx6fh6YyrSA6t7wbNGqpMeMhfgYUsiPVhTu9f3eznsIte+EV+yVDF2cVLDjbUw601/7zL/b++b67sECnVzdu63LGVfGLCT71x3ChN6zuoBVOEgQHBqanN482ZLeRN1TOtG7jL0HzvbpHMrQOb0qcGdGuGuKUZwO2l5T9GoZ+DcpkJXWyxNNGVLF3WdI8poou7GPfvnXlB2UErvAJGeeMXtXGAMgAe0H3BnhS67Z88JUJ4swN9geKdkUqiA+p9w1EY6jWRb/YiEc5e4MSGgCSfu0TgRST+4rx89ps5tsIzH+ZF6qjm+9KxpkBMJWq0R8uoe24PCA==; 5:cb2qkR4VW2gemxUHf8fj8b+DqPVn7WlqB7ea63/MJ/eFf01RefIWI+TYc8YBSG2YzV/SI/XAM3ucwY/yzUxwFT4PjSh5JLhFAPoE5urouU9x1lmEdXpf0SB5jXoJLG0r6X5gZsddwAs9qLcr/tXsOA==; 24:W+O9Mqu2LZLuEgFBmgDmySahlmu5iigKCXfe3iaNTGzK1muI/frb+FXu39I3TWFsuciZkxJiUe3ypAf8WnPD86SPngGn0ekg7AMkds3bJVc= SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-Microsoft-Exchange-Diagnostics: 1; DM3PR07MB2284; 7:4uah+uvzl4eDSDSx3OBL6e4wCUD5Qhw+d4aYGzlVmJWrcSIh7u1qPFzmFs8e7T0UKjUIC/so5+Hw6LTqijoL8NU0VfP3ytz0X1C+Z66LjYYYtjS2NDZdHzLFes6EOEKW43dtuPFU9h+GUpSw/NKmVeQ+m0ETIQbDIH57Ipi/WweezeBqo0OUaBeath+TNXzBMx2tY17VsJxI6p75wBXY1PHkYuuZboD2Bjof4YgOcaUqQd9lEf0wmEvvkbIfHszmHm8j8dk3HBfxwWVbd0ujZNFpDDKibTef6wWYq1+FNP4ftmy/Zhtyq5ne4PKZn7G/cBHSsA0K5w3f/GsCud0ISA== X-OriginatorOrg: caviumnetworks.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 11 Apr 2017 18:58:20.9202 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM3PR07MB2284 Subject: [dpdk-dev] [PATCH v2 01/10] doc: add doc to explain compiling and testing of PMD X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 11 Apr 2017 18:58:24 -0000 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 Signed-off-by: Jerin Jacob Acked-by: John McNamara --- doc/guides/nics/build_and_test.rst | 179 ++++++++++++++++++++++++++++++++++++ doc/guides/nics/index.rst | 1 + doc/guides/testpmd_app_ug/index.rst | 2 + 3 files changed, 182 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..2d70af8 --- /dev/null +++ b/doc/guides/nics/build_and_test.rst @@ -0,0 +1,179 @@ +.. BSD LICENSE + Copyright(c) 2017 Cavium, Inc. + + 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 ` for detailed +information on how to build and run testpmd. + +Driver Compilation +------------------ + +To compile a PMD for a platform, run make with appropriate target as shown below. +Use "make" command in Linux and "gmake" in FreeBSD. This will also build testpmd. + +To check available targets: + +.. code-block:: console + + cd + make showconfigs + +Example output: + +.. code-block:: console + + arm-armv7a-linuxapp-gcc + arm64-armv8a-linuxapp-gcc + arm64-dpaa2-linuxapp-gcc + arm64-thunderx-linuxapp-gcc + arm64-xgene1-linuxapp-gcc + i686-native-linuxapp-gcc + i686-native-linuxapp-icc + ppc_64-power8-linuxapp-gcc + x86_64-native-bsdapp-clang + x86_64-native-bsdapp-gcc + x86_64-native-linuxapp-clang + x86_64-native-linuxapp-gcc + x86_64-native-linuxapp-icc + x86_x32-native-linuxapp-gcc + +To compile a PMD for Linux x86_64 gcc target, run the following "make" command: + +.. code-block:: console + + make install T=x86_64-native-linuxapp-gcc + +Use ARM (ThunderX, DPAA, X-Gene) or PowerPC target for respective platform. + +For more information, refer to the :ref:`Getting Started Guide for Linux ` +or :ref:`Getting Started Guide for FreeBSD ` 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: + + Hugepage memory should be reserved as per application requirement. Check + hugepage size configured in the system and calculate the number of pages + required. + + To reserve 1024 pages of 2MB: + + .. code-block:: console + + echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages + + .. note:: + + Check ``/proc/meminfo`` to find system hugepage size: + + .. code-block:: console + + grep "Hugepagesize:" /proc/meminfo + + Example output: + + .. code-block:: console + + Hugepagesize: 2048 kB + +#. 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 ` for a list + of available commands. diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst index 3305e80..3c7722f 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 ark avp bnx2x 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