From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-pa0-f50.google.com (mail-pa0-f50.google.com [209.85.220.50]) by dpdk.org (Postfix) with ESMTP id 38066C37A for ; Mon, 6 Apr 2015 20:58:50 +0200 (CEST) Received: by patj18 with SMTP id j18so52589017pat.2 for ; Mon, 06 Apr 2015 11:58:49 -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=uX1mIYGFBbH3aT0SzA52vLTaZ7XLKq1UkbHBbom7lGk=; b=HCc1vSYv0kMNJgaoYN/FSgDYQok7H8yCEeg+aPj/FxW1eslHJJ7Bb7gYHTZ6fuUqnZ THnhhkA5+WhRPZTtPy864niNpJ83tsw9GLm1bFHHxrFtOluMg0yARcJaVPCeHYk23rwF 3gRXvz9u3sDn05b5vN9jMlSraHUMGXpBEwx08cKwwwE8c4OhPxgcFUoAVrieOHOMiAvv Dwifr6OkMsSpVK4xyvj1zmMHPLg+Eh5o5srfEZXipiD/VAZ3L+oaZZnupNuTNKF4jVPc oKsgI0hdWit8Aa3d8aA+jO5OS63aDMlXBQ+slbYBoG5CB55H1sm3Eo7oNGAjvX37FFBg iGLw== X-Gm-Message-State: ALoCoQnUT4fbTFSuJt9sXrpMc+3SzPMcl+EoGRr1tAV3Gx9fcwndCxSapIe2f5LApZG8dWiLSV+t X-Received: by 10.70.14.33 with SMTP id m1mr29632172pdc.123.1428346729449; Mon, 06 Apr 2015 11:58:49 -0700 (PDT) Received: from localhost (7c295ef2.i-revonet.jp. [124.41.94.242]) by mx.google.com with ESMTPSA id e4sm5469515pdi.64.2015.04.06.11.58.48 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 06 Apr 2015 11:58:48 -0700 (PDT) From: Takuya ASADA To: dev@dpdk.org Date: Tue, 7 Apr 2015 03:58:11 +0900 Message-Id: <1428346691-14894-8-git-send-email-syuu@cloudius-systems.com> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1428346691-14894-1-git-send-email-syuu@cloudius-systems.com> References: <1428346691-14894-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 PATCHv3 7/7] 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: Mon, 06 Apr 2015 18:58:50 -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 | 282 ++++++++++++++++++++++++++ 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, 410 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 44e8432..3b45ca3 100644 --- a/doc/guides/index.rst +++ b/doc/guides/index.rst @@ -40,6 +40,7 @@ Contents: linux_gsg/index freebsd_gsg/index xen/index + osv_gsg/index prog_guide/index nics/index sample_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..4eadb68 --- /dev/null +++ b/doc/guides/osv_gsg/build_dpdk.rst @@ -0,0 +1,282 @@ +.. 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.19 + 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: --maxnic=0 /l2fwd --no-shconf -c 3 -n 2 --log-level 8 -m 768 -- -p 3 + + build: ./GET + +.. note:: + + To control OSv instance via REST API, you'll need to specify '--maxnic=1' + on cmdline, then attach one more NIC on virt-install. + eth0 will exclusively use for REST server, DPDK uses other NICs. + +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.19 + 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