From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mogw0503.ocn.ad.jp (mogw0503.ocn.ad.jp [118.23.178.145]) by dpdk.org (Postfix) with ESMTP id 291BD1D903 for ; Fri, 15 Jun 2018 09:06:27 +0200 (CEST) Received: from mf-smf-ucb034c2 (mf-smf-ucb034c2.ocn.ad.jp [153.153.66.228]) by mogw0503.ocn.ad.jp (Postfix) with ESMTP id B74DD47826B; Fri, 15 Jun 2018 16:06:25 +0900 (JST) Received: from ntt.pod01.mv-mta-ucb030 ([153.149.230.164]) by mf-smf-ucb034c2 with ESMTP id TioTfSjm9xryjTioTfZYyw; Fri, 15 Jun 2018 16:06:25 +0900 Received: from smtp.ocn.ne.jp ([153.149.227.165]) by ntt.pod01.mv-mta-ucb030 with id yv6R1x00M3akymp01v6Rtf; Fri, 15 Jun 2018 07:06:25 +0000 Received: from localhost.localdomain (p5164-ipngn8501marunouchi.tokyo.ocn.ne.jp [153.214.228.164]) by smtp.ocn.ne.jp (Postfix) with ESMTPA; Fri, 15 Jun 2018 16:06:25 +0900 (JST) From: ogawa.yasufumi@lab.ntt.co.jp To: ferruh.yigit@intel.com, spp@dpdk.org Cc: Yasufumi Ogawa Date: Fri, 15 Jun 2018 16:06:04 +0900 Message-Id: <20180615070615.15594-5-ogawa.yasufumi@lab.ntt.co.jp> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20180615070615.15594-1-ogawa.yasufumi@lab.ntt.co.jp> References: <20180615070615.15594-1-ogawa.yasufumi@lab.ntt.co.jp> Subject: [spp] [PATCH 04/15] docs: add getting started guide of SPP container X-BeenThere: spp@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Soft Patch Panel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 15 Jun 2018 07:06:28 -0000 From: Yasufumi Ogawa Signed-off-by: Yasufumi Ogawa --- docs/guides/tools/sppc/getting_started.rst | 327 +++++++++++++++++++++ 1 file changed, 327 insertions(+) create mode 100644 docs/guides/tools/sppc/getting_started.rst diff --git a/docs/guides/tools/sppc/getting_started.rst b/docs/guides/tools/sppc/getting_started.rst new file mode 100644 index 0000000..da7d3d9 --- /dev/null +++ b/docs/guides/tools/sppc/getting_started.rst @@ -0,0 +1,327 @@ +.. _spp_container_gs: + +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2017-2018 Nippon Telegraph and Telephone Corporation + + +.. _sppc_gs_gs: + +Getting Started +=============== + +In this section, learn how to use SPP container with a simple +usecase. +You use four of terminals for running SPP processes and applications. + +.. _sppc_gs_setup: + +Setup DPDK and SPP +------------------ + +First of all, you need to clone DPDK and setup hugepages for running +DPDK application as described in +:doc:`../../setup/getting_started` +or DPDK's +`Gettting Started Guide +`_. +You also need to load kernel modules and bind network ports as in +`Linux Drivers +`_. + +Then, as described in +:doc:`../../setup/getting_started` +, clone and compile SPP in any directory. + +.. code-block:: console + + # Terminal 1 + $ git clone http://dpdk.org/git/apps/spp + $ cd spp + + +.. _sppc_gs_build_docker_imgs: + +Build Docker Images +------------------- + +Build tool is a python script for creating a docker image and +currently supporting three types of images for +DPDK sample applications, pktgen-dpdk, or SPP. + +Run build tool for creating three type of docker images. +It starts to download the latest Ubuntu docker image and installation +for the latest DPDK, pktgen or SPP. + +.. code-block:: console + + # Terminal 1 + $ cd /path/to/spp/tools/sppc + $ python build/main.py -t dpdk + $ python build/main.py -t pktgen + $ python build/main.py -t spp + +Of course DPDK is required from pktgen and SPP, and it causes a +problem of compatibility between them sometimes. +At the time writing this document, SPP v18.02 is not compatible with +the latest DPDK v18.05 and it is failed to compile. +In this case, you should build SPP with ``--dpdk-branch`` option to tell +the version of DPDK explicitly. + +.. code-block:: console + + # Terminal 1 + $ python build/main.py -t spp --dpdk-branch v18.02 + +You can find all of options by ``build/main.py -h``. + +Waiting for a minutes, then you are ready to launch app containers. +All of images are referred from ``docker images`` command. + +.. code-block:: console + + $ docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + sppc/spp-ubuntu latest 3ec39adb460f 2 days ago 862MB + sppc/pktgen-ubuntu latest ffe65cc70e65 2 days ago 845MB + sppc/dpdk-ubuntu latest 0d5910d10e3f 2 days ago 1.66GB + d52d2f86a3c0 2 days ago 551MB + ubuntu latest 452a96d81c30 5 weeks ago 79.6MB + +.. note:: + + The Name of containers is defined as a set of target, name and + version of Linux distoribution. + For example, container image targetting dpdk apps on Ubuntu 16.04 + is named as ``sppc/dpdk-ubuntu:16.04``. + + Build script understands which of Dockerfile should be used based + on the given options. + If you run build script with options for dpdk and Ubuntu 16.04 as + below, it finds ``build/ubuntu/dpdk/Dockerfile.16.04`` and runs + ``docker build``. + Options for Linux distribution have default value, ``ubuntu`` and + ``latest``. So, you do not need to specify them if you use default. + + + .. code-block:: console + + # latest DPDK on Ubuntu 16.04 + $ python build/main.py -t dpdk --dist-name ubuntu --dist-ver latest + + # it is also the same + $ python build/main.py -t dpdk + +.. warning:: + + Currently, the latest version of Ubuntu is 18.04 and DPDK is 18.05. + However, SPP is not stable on the latest versions, especially + running on containers. + + It is better to use Ubuntu 16.04 and DPDK 18.02 for SPP containers + until be stabled. + + .. code-block:: console + + $ python build/main.py -t dpdk --dist-ver 16.04 --dpdk-branch v18.02 + $ python build/main.py -t pktgen --dist-ver 16.04 \ + --dpdk-branch v18.02 --pktgen-branch pktgen-3.4.9 + $ python build/main.py -t spp --dist-ver 16.04 --dpdk-branch v18.02 + + +.. _sppc_gs_launch_containers: + +Launch SPP and App Containers +----------------------------- + +Before launch containers, you should set IP address of host machine +as ``SPP_CTRL_IP`` environment variable +for controller to be accessed from inside containers. +It is better to define this variable in ``$HOME/.bashrc``. + +.. code-block:: console + + # Set your host IP address + export SPP_CTRL_IP=[HOST_IPADDR] + + +SPP Controller +~~~~~~~~~~~~~~ + +Launch SPP controller to be ready +before primary and secondary processes. +SPP controller is launched in the terminal 1 in this guide. + +.. note:: + + SPP controller provides ``topo term`` which shows network + topology in a terminal. + + However, there are a new terminal apps supporing this feature. + ``mlterm`` is the most useful and easy to customize. + Refer :doc:`../../commands/experimental` for ``topo`` command. + +.. code-block:: console + + # Terminal 1 + $ cd /path/to/spp + $ python src/spp.py + + +SPP Primary Container +~~~~~~~~~~~~~~~~~~~~~ + +As ``SPP_CTRL_IP`` is activated, you are enalbed to run +``app/spp-primary.py`` with options of EAL and SPP primary +in terminal 2. +In this case, launch spp-primary in background mode using one core +and two ports. + +.. code-block:: console + + # Terminal 2 + $ cd /path/to/spp/tools/sppc + $ python app/spp-primary.py -l 0 -p 0x03 + + +SPP Secondary Container +~~~~~~~~~~~~~~~~~~~~~~~ + +For secondary process, there are two launcher scripts, +``spp-nfv.py`` and ``spp-vm.py``. +There behave as similar to ``spp_nfv`` running on host and +``spp_vm`` on guest VM. +The difference is that both of them are running on containers. + +You use only ``spp_nfv.py`` in this guide. +Launch ``spp_nfv`` in terminal 2 +with options for secondary ID is ``1`` and +core list is ``1-2`` for using 2nd and 3rd cores. + +.. code-block:: console + + # Terminal 2 + $ python app/spp-nfv.py -i 1 -l 1-2 + +If it is succeeded, container is running in background. +You can find it with ``docker -ps`` command. + + +App Container +~~~~~~~~~~~~~ + +Launch DPDK's ``testpmd`` as an example of app container. + +Currently, most of app containers do not support ring PMD. +It means that you should create vhost PMDs from SPP controller +before launching the app container. + +.. code-block:: console + + # Terminal 1 + spp > sec 1;add vhost 1 + spp > sec 1;add vhost 2 + +``spp_nfv`` of ID 1 running inside container creates +``vhost:1`` and ``vhost:2``. +Vhost PMDs are referred as an option ``-d 1,2`` from the +app container launcher. + +.. code-block:: console + + # Terminal 2 + $ cd /path/to/spp/tools/sppc + $ app/testpmd.py -l 3-4 -d 1,2 + sudo docker run -it \ + ... + EAL: Detected 16 lcore(s) + EAL: Auto-detected process type: PRIMARY + EAL: Multi-process socket /var/run/.testpmd1_unix + EAL: Probing VFIO support... + EAL: VFIO support initialized + Interactive-mode selected + Warning: NUMA should be configured manually by using --port-numa-... + testpmd: create a new mbuf pool : n=155456,... + testpmd: preferred mempool ops selected: ring_mp_mc + Configuring Port 0 (socket 0) + Port 0: 32:CB:1D:72:68:B9 + Configuring Port 1 (socket 0) + Port 1: 52:73:C3:5B:94:F1 + Checking link statuses... + Done + testpmd> + + +It launches ``testpmd`` in foreground mode. + + +.. _sppc_gs_run_apps: + +Run Applications +---------------- + +At the end of this getting started guide, configure network paths +as described in +:numref:`figure_sppc_gsg_testpmd` +and start forwarding from testpmd. + +.. _figure_sppc_gsg_testpmd: + +.. figure:: ../../images/tools/sppc/sppc_gsg_testpmd.* + :height: 340em + :width: 340em + + SPP and testpmd on containers + +From terminal 1, add ``ring:0``, connect ``vhost:1`` and ``vhost:2`` +with it. + +.. code-block:: console + + # Terminal 1 + spp > sec 1;add ring 0 + spp > sec 1;patch vhost:1 ring:0 + spp > sec 1;patch ring:0 vhost:2 + spp > sec 1;forward + spp > sec 1;status + status: running + ports: + - 'ring:0 -> vhost:2' + - 'vhost:1 -> ring:0' + - 'vhost:2' + +Start forwarding on port 0 by ``start tx_first``. + +.. code-block:: console + + # Terminal 2 + testpmd> start tx_first + io packet forwarding - ports=2 - cores=1 - streams=2 - NUMA support... + Logical Core 4 (socket 0) forwards packets on 2 streams: + RX P=0/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:01 + RX P=1/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00 + ... + +Finally, stop forwarding to show statistics as the result. +In this case, about 35 million packets are forwarded. + +.. code-block:: console + + # Terminal 2 + testpmd> stop + Telling cores to stop... + Waiting for lcores to finish... + + ---------------------- Forward statistics for port 0 ------------------ + RX-packets: 0 RX-dropped: 0 RX-total: 0 + TX-packets: 35077664 TX-dropped: 0 TX-total: 35077664 + ------------------------------------------------------------------------ + + ---------------------- Forward statistics for port 1 ------------------ + RX-packets: 35077632 RX-dropped: 0 RX-total: 35077632 + TX-packets: 32 TX-dropped: 0 TX-total: 32 + ------------------------------------------------------------------------ + + +++++++++++++++ Accumulated forward statistics for all ports++++++++++++ + RX-packets: 35077632 RX-dropped: 0 RX-total: 35077632 + TX-packets: 35077696 TX-dropped: 0 TX-total: 35077696 + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -- 2.17.1