From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-pa0-f51.google.com (mail-pa0-f51.google.com [209.85.220.51]) by dpdk.org (Postfix) with ESMTP id 9F4385AA1 for ; Sat, 21 Mar 2015 04:23:54 +0100 (CET) Received: by pagj4 with SMTP id j4so36273219pag.2 for ; Fri, 20 Mar 2015 20:23:54 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-type:content-transfer-encoding; bh=ylbFqXZdWDNHeWAS7lpKfRAMWXG5kHe1xfRyXhtHOj4=; b=Omv2TJmxyDR4eR7hHXr1cvuavi8RSOCR5m6FWwkiD9NPizhk+2I34yIaNZeWjpQ5C9 6KnJ8C0lKmHdpDSgrtLDPD7C/eYUe0i4V4QAu/xBC63Yjk8EFNgK+PFugiZcrVeQy782 COzE0rAg7p4pdN7X4ObTjwdByv5y5NOdgAX4LjMDofU568JBL8smP1MAakdGM7Xp80cw oP56uVsn1llO+TM4aUiJRIRpqsEssicQLV3OLm7QFm9rD100Wzmo56lxz4W460nWwbgZ 46uccbZ5jBpH19YMizkjjsXmREcjqecksbcRl6soWUmGnth2rm1GOsdrvg/64nPtKn88 iiAw== X-Gm-Message-State: ALoCoQkHxF1W6jndQj7/n3RREKpz5NvQJRU96X8zHzYL3hpClA/TCHmTf8VGmVJLwBUJQSD1hhvN X-Received: by 10.68.166.98 with SMTP id zf2mr1797182pbb.88.1426908233994; Fri, 20 Mar 2015 20:23:53 -0700 (PDT) Received: from localhost (7c295ef2.i-revonet.jp. [124.41.94.242]) by mx.google.com with ESMTPSA id ks6sm453844pbc.68.2015.03.20.20.23.52 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 20 Mar 2015 20:23:53 -0700 (PDT) From: Takuya ASADA To: dev@dpdk.org Date: Sat, 21 Mar 2015 12:23:05 +0900 Message-Id: <1426908185-27940-9-git-send-email-syuu@cloudius-systems.com> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1426908185-27940-1-git-send-email-syuu@cloudius-systems.com> References: <1426194348-4406-1-git-send-email-syuu@cloudius-systems.com> <1426908185-27940-1-git-send-email-syuu@cloudius-systems.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [RFC PATCHv2 8/8] doc: Add Getting Started Guide for OSv X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 21 Mar 2015 03:23:55 -0000 Described how to build DPDK for OSv, using "Capstan". Signed-off-by: Takuya ASADA --- doc/guides/index.rst | 1 + doc/guides/osv_gsg/build_dpdk.rst | 276 ++++++++++++++++++++++++++ doc/guides/osv_gsg/build_sample_apps.rst | 123 ++++++++++++ doc/guides/{freebsd_gsg => osv_gsg}/index.rst | 3 +- doc/guides/{freebsd_gsg => osv_gsg}/intro.rst | 15 +- 5 files changed, 404 insertions(+), 14 deletions(-) create mode 100644 doc/guides/osv_gsg/build_dpdk.rst create mode 100644 doc/guides/osv_gsg/build_sample_apps.rst copy doc/guides/{freebsd_gsg => osv_gsg}/index.rst (96%) copy doc/guides/{freebsd_gsg => osv_gsg}/intro.rst (84%) diff --git a/doc/guides/index.rst b/doc/guides/index.rst index c589a30..66a44f9 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -39,6 +39,7 @@ Contents: linux_gsg/index freebsd_gsg/index + osv_gsg/index prog_guide/index sample_app_ug/index testpmd_app_ug/index diff --git a/doc/guides/osv_gsg/build_dpdk.rst b/doc/guides/osv_gsg/build_dpdk.rst new file mode 100644 index 0000000..e0cbea7 --- /dev/null +++ b/doc/guides/osv_gsg/build_dpdk.rst @@ -0,0 +1,276 @@ +.. BSD LICENSE + Copyright(c) 2010-2014 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. + +.. _building_from_source: + +Compiling the DPDK Target from Source +===================================== + +System Requirements +------------------- + +To building DPDK for OSv, you will need to use Linux/x86_64 with g++ 4.8 or later. + +Install the DPDK and Browse Sources +----------------------------------- + +First, uncompress the archive and move to the DPDK source directory: + +.. code-block:: console + + [user@host ~]$ unzip DPDK-zip + [user@host ~]$ cd DPDK- + [user@host DPDK]$ ls + app/ config/ examples/ lib/ LICENSE.GPL LICENSE.LGPL Makefile mk/ scripts/ tools/ + +The DPDK is composed of several directories: + +* lib: Source code of DPDK libraries + +* app: Source code of DPDK applications (automatic tests) + +* examples: Source code of DPDK applications + +* config, tools, scripts, mk: Framework-related makefiles, scripts and configuration + +Install Capstan +-------------------------------------------- + +Before start building VM image, you need to install Capstan*: + +`http://osv.io/capstan/` + +.. code-block:: console + + [user@host ~]$ curl https://raw.githubusercontent.com/cloudius-systems/capstan/master/scripts/download | bash + +Build DPDK for OSv VM image +-------------------------------------------- + +Build VM image using Capstan: + +.. code-block:: console + + [user@host ~]$ cd DPDK-/lib/librte_eal/osvapp/capstan/ + [user@host capstan]$ capstan build osv-dpdk + Building osv-dpdk... + Downloading cloudius/osv-base/index.yaml... + 145 B / 145 B [======================================================] 100.00 % + Downloading cloudius/osv-base/osv-base.qemu.gz... + 20.09 MB / 20.09 MB [================================================] 100.00 % + Uploading files... + 10 / 10 [============================================================] 100.00 % + +Run DPDK for OSv VM image +-------------------------------------------- + +Run VM image using Capstan: + +.. code-block:: console + + [user@host ~]$ capstan run osv-dpdk + Created instance: osv-dpdk + OSv v0.18 + eth0: 192.168.122.15 + EAL: Detected lcore 0 as core 0 on socket 0 + EAL: Detected lcore 1 as core 1 on socket 0 + EAL: Support maximum 128 logical core(s) by configuration. + EAL: Detected 2 lcore(s) + EAL: bar2 not available + EAL: bar2 not available + EAL: bar2 not available + EAL: bar0 not available + EAL: bar0 not available + EAL: bar0 not available + EAL: bar0 not available + EAL: PCI scan found 7 devices + EAL: Setting up memory... + EAL: Mapped memory segment 0 @ 0xffff80003de00000: physaddr:0x3de00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff80003bc00000: physaddr:0x3bc00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800039a00000: physaddr:0x39a00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800037800000: physaddr:0x37800000, len 33554432 + EAL: TSC frequency is ~438348 KHz + EAL: Master lcore 0 is ready (tid=57f7040;cpuset=[0]) + PMD: ENICPMD trace: rte_enic_pmd_init + EAL: PCI device 0000:00:04.0 on NUMA socket -1 + EAL: probe driver: 1af4:1000 rte_virtio_pmd + APP: HPET is not enabled, using TSC as default timer + RTE>> + +Run another sample applications +-------------------------------------------- + +Delete osv-dpdk instance at first if you already deployed it on Capstan: + +.. code-block:: console + + [user@host ~]$ cd DPDK-/lib/librte_eal/osvapp/capstan/ + [user@host capstan]$ capstan delete osv-dpdk + Deleted instance: osv-dpdk + +Then you need to open Capstanfile on a editor, modify cmdline field: + +.. code-block:: console + + base: cloudius/osv-base + + cmdline: /l2fwd --no-shconf -c 3 -n 2 --log-level 8 -m 768 -- -p 3 + + build: ./GET + +Build VM image again: + +.. code-block:: console + + [user@host capstan]$ capstan build osv-dpdk + Building osv-dpdk... + Downloading cloudius/osv-base/index.yaml... + 145 B / 145 B [======================================================] 100.00 % + Downloading cloudius/osv-base/osv-base.qemu.gz... + 20.09 MB / 20.09 MB [================================================] 100.00 % + Uploading files... + 10 / 10 [============================================================] 100.00 % + +.. note:: + + You can use another name for new VM instance. + On that case, you don't have to delete existing instance. + +Export VM image to libvirt +-------------------------------------------- + +Packet forwarding application(such as l2fwd or l3fwd) requires multiple vNICs with multiple bridges, but Capstan does not have a way to configure such network. + +To do so, you can export VM image to libvirt by using virt-install: + +.. code-block:: console + + [user@host ~]$ sudo virt-install --import --noreboot --name=osv-dpdk --ram=4096 --vcpus=2 --disk path=/home/user/.capstan/repository/osv-dpdk/osv-dpdk.qemu,bus=virtio --os-variant=none --accelerate --network=network:default,model=virtio --network=network:net2,model=virtio --serial pty --cpu host --rng=/dev/random + + WARNING Graphics requested but DISPLAY is not set. Not running virt-viewer. + WARNING No console to launch for the guest, defaulting to --wait -1 + + Starting install... + Creating domain... | 0 B 00:00 + Domain creation completed. You can restart your domain by running: + virsh --connect qemu:///system start osv-dpdk + + [user@host ~]$ sudo virsh start osv-dpdk;sudo virsh console osv-dpdkDomain osv-dpdk started + + Connected to domain osv-dpdk + Escape character is ^] + OSv v0.18 + eth1: 192.168.123.63 + EAL: Detected lcore 0 as core 0 on socket 0 + EAL: Detected lcore 1 as core 1 on socket 0 + EAL: Support maximum 128 logical core(s) by configuration. + EAL: Detected 2 lcore(s) + EAL: bar2 not available + EAL: bar2 not available + EAL: bar2 not available + EAL: bar1 not available + EAL: bar2 not available + EAL: bar1 not available + EAL: bar4 not available + EAL: bar0 not available + EAL: bar1 not available + EAL: bar0 not available + EAL: bar0 not available + EAL: bar0 not available + EAL: bar1 not available + EAL: bar0 not available + EAL: bar0 not available + EAL: bar0 not available + EAL: PCI scan found 16 devices + EAL: Setting up memory... + EAL: Mapped memory segment 0 @ 0xffff80013e000000: physaddr:0x13e000000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff80013be00000: physaddr:0x13be00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800139c00000: physaddr:0x139c00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800137a00000: physaddr:0x137a00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800135800000: physaddr:0x135800000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800133600000: physaddr:0x133600000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800131400000: physaddr:0x131400000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff80012f200000: physaddr:0x12f200000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff80012d000000: physaddr:0x12d000000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff80012ae00000: physaddr:0x12ae00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800128c00000: physaddr:0x128c00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800126a00000: physaddr:0x126a00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800124800000: physaddr:0x124800000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800122600000: physaddr:0x122600000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800120400000: physaddr:0x120400000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff80011e200000: physaddr:0x11e200000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff80011c000000: physaddr:0x11c000000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800119e00000: physaddr:0x119e00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800117c00000: physaddr:0x117c00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800115a00000: physaddr:0x115a00000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800113800000: physaddr:0x113800000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff800111600000: physaddr:0x111600000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff80010f400000: physaddr:0x10f400000, len 33554432 + EAL: Mapped memory segment 0 @ 0xffff8000bde00000: physaddr:0xbde00000, len 33554432 + EAL: TSC frequency is ~1575941 KHz + EAL: Master lcore 0 is ready (tid=4b76040;cpuset=[0]) + PMD: ENICPMD trace: rte_enic_pmd_init + EAL: lcore 1 is ready (tid=52fe040;cpuset=[1]) + EAL: PCI device 0000:00:03.0 on NUMA socket -1 + EAL: probe driver: 1af4:1000 rte_virtio_pmd + EAL: PCI device 0000:00:04.0 on NUMA socket -1 + EAL: probe driver: 1af4:1000 rte_virtio_pmd + Lcore 0: RX port 0 + Lcore 1: RX port 1 + Initializing port 0... done: + Port 0, MAC address: 52:54:00:05:59:A9 + + Initializing port 1... done: + Port 1, MAC address: 52:54:00:38:65:DA + + + Checking link statusdone + Port 0 Link Up - speed 10000 Mbps - full-duplex + Port 1 Link Up - speed 10000 Mbps - full-duplex + L2FWD: entering main loop on lcore 1 + L2FWD: entering main loop on lcore 0 + L2FWD: -- lcoreid=1 portid=1 + L2FWD: -- lcoreid=0 portid=0 + + Port statistics ==================================== + Statistics for port 0 ------------------------------ + Packets sent: 0 + Packets received: 0 + Packets dropped: 0 + Statistics for port 1 ------------------------------ + Packets sent: 0 + Packets received: 0 + Packets dropped: 0 + Aggregate statistics =============================== + Total packets sent: 0 + Total packets received: 0 + Total packets dropped: 0 + ==================================================== + diff --git a/doc/guides/osv_gsg/build_sample_apps.rst b/doc/guides/osv_gsg/build_sample_apps.rst new file mode 100644 index 0000000..3d29a48 --- /dev/null +++ b/doc/guides/osv_gsg/build_sample_apps.rst @@ -0,0 +1,123 @@ +.. BSD LICENSE + Copyright(c) 2010-2014 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. + +.. _compiling_sample_apps: + +Compiling and Running Sample Applications +========================================= + +The chapter describes how to compile and run applications in a DPDK +environment. It also provides a pointer to where sample applications are stored. + +Running a Sample Application +---------------------------- + +The following is the list of options that can be given to the EAL: + +.. code-block:: console + + ./rte-app -c COREMASK -n NUM [-b ] [-r NUM] [-v] [--proc-type ] + +.. note:: + + EAL has a common interface between all operating systems and is based on the + Linux* notation for PCI devices. For example, a FreeBSD* device selector of + pci0:2:0:1 is referred to as 02:00.1 in EAL. + +The EAL options for FreeBSD* are as follows: + +* -c COREMASK + : A hexadecimal bit mask of the cores to run on. Note that core numbering + can change between platforms and should be determined beforehand. + +* -n NUM + : Number of memory channels per processor socket. + +* -b + : blacklisting of ports; prevent EAL from using specified PCI device + (multiple -b options are allowed). + +* --use-device + : use the specified ethernet device(s) only. Use comma-separate + <[domain:]bus:devid.func> values. Cannot be used with -b option. + +* -r NUM + : Number of memory ranks. + +* -v + : Display version information on startup. + +* --proc-type + : The type of process instance. + +Other options, specific to Linux* and are not supported under FreeBSD* are as follows: + +* socket-mem + : Memory to allocate from hugepages on specific sockets. + +* --huge-dir + : The directory where hugetlbfs is mounted. + +* --file-prefix + : The prefix text used for hugepage filenames. + +* -m MB + : Memory to allocate from hugepages, regardless of processor socket. + It is recommended that --socket-mem be used instead of this option. + +The -c and the -n options are mandatory; the others are optional. + +Edit cmdline on Capstanfile, then rebuild and run VM instance as follows +(assuming the platform has four memory channels, and that cores 0-3 +are present and are to be used for running the application): + +.. code-block:: console + + [user@host ~]$ cd DPDK-/lib/librte_eal/osvapp/capstan/ + [user@host ~]$ vi Capstanfile # edit cmdline + [user@host capstan]$ capstan delete osv-dpdk + Deleted instance: osv-dpdk + [user@host capstan]$ capstan build osv-dpdk + Building osv-dpdk... + Downloading cloudius/osv-base/index.yaml... + 145 B / 145 B [======================================================] 100.00 % + Downloading cloudius/osv-base/osv-base.qemu.gz... + 20.09 MB / 20.09 MB [================================================] 100.00 % + Uploading files... + 10 / 10 [============================================================] 100.00 % + [user@host ~]$ capstan run osv-dpdk + +.. note:: + + The --proc-type and --file-prefix EAL options are used for running multiple + DPDK processes. See the “Multi-process Sample Application” chapter + in the *DPDK Sample Applications User Guide and the DPDK + Programmers Guide* for more details. + diff --git a/doc/guides/freebsd_gsg/index.rst b/doc/guides/osv_gsg/index.rst similarity index 96% copy from doc/guides/freebsd_gsg/index.rst copy to doc/guides/osv_gsg/index.rst index 1b4cd3b..46ffb3e 100644 --- a/doc/guides/freebsd_gsg/index.rst +++ b/doc/guides/osv_gsg/index.rst @@ -28,7 +28,7 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -Getting Started Guide for FreeBSD +Getting Started Guide for OSv ================================= |today| @@ -40,6 +40,5 @@ Getting Started Guide for FreeBSD :numbered: intro - install_from_ports build_dpdk build_sample_apps diff --git a/doc/guides/freebsd_gsg/intro.rst b/doc/guides/osv_gsg/intro.rst similarity index 84% copy from doc/guides/freebsd_gsg/intro.rst copy to doc/guides/osv_gsg/intro.rst index 176358a..bc7c3ba 100644 --- a/doc/guides/freebsd_gsg/intro.rst +++ b/doc/guides/osv_gsg/intro.rst @@ -34,20 +34,11 @@ Introduction This document contains instructions for installing and configuring the Data Plane Development Kit (DPDK) software. It is designed to get customers up and running quickly and describes how to compile and run a -DPDK application in a FreeBSD* application (bsdapp) environment, without going +DPDK application in a OSv* application (osvapp) environment, without going deeply into detail. -For a comprehensive guide to installing and using FreeBSD*, the following -handbook is available from the FreeBSD* Documentation Project: - -`http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html `_ - -.. note:: - - The DPDK is now available as part of the FreeBSD ports collection. - Installing via the ports collection infrastructure is now the recommended - way to install the DPDK on FreeBSD, and is documented in the - next chapter, :ref:`install_from_ports`. +For a comprehensive guide to installing and using OSv*, the following +handbook is available from the OSv* Documentation Project: Documentation Roadmap --------------------- -- 2.1.0