[dpdk-dev,RFC,PATCHv3,7/7] doc: Add Getting Started Guide for OSv

Message ID 1428346691-14894-8-git-send-email-syuu@cloudius-systems.com (mailing list archive)
State Changes Requested, archived
Headers

Commit Message

Takuya ASADA April 6, 2015, 6:58 p.m. UTC
Described how to build DPDK for OSv, using "Capstan".

Signed-off-by: Takuya ASADA <syuu@cloudius-systems.com>
---
 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%)
  

Comments

Mcnamara, John June 18, 2015, 2:09 p.m. UTC | #1
> -----Original Message-----

> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Takuya ASADA

> Sent: Monday, April 6, 2015 7:58 PM

> To: dev@dpdk.org

> Subject: [dpdk-dev] [RFC PATCHv3 7/7] doc: Add Getting Started Guide for

> OSv

> 

> Described how to build DPDK for OSv, using "Capstan".



Hi,

A few minor issues:

* The patch has some whitespace issues.
* The introduction could make it a little clearer what OSv is.
* The introduction mentions a handbook but there isn't a link.
* The OSv guide should follow the FreeBSD guide in the index.rst file.
* "make doc-guides-html" generates the following warnings due to conflict with the FreeBSD docs. Unique labels should be provided.

    WARNING: duplicate label building_from_source
    WARNING: duplicate label compiling_sample_apps

John
  

Patch

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-<version>zip
+    [user@host ~]$ cd DPDK-<version>
+    [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-<version>/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-<version>/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 <domain:bus:devid.func>] [-r NUM] [-v] [--proc-type <primary|secondary|auto>]
+
+.. 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 <domain:bus:devid.func>
+    : 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-<version>/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 <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
 ---------------------