From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from tama500.ecl.ntt.co.jp (tama500.ecl.ntt.co.jp [129.60.39.148]) by dpdk.org (Postfix) with ESMTP id 4D9135F33 for ; Mon, 18 Feb 2019 12:50:49 +0100 (CET) Received: from vc1.ecl.ntt.co.jp (vc1.ecl.ntt.co.jp [129.60.86.153]) by tama500.ecl.ntt.co.jp (8.13.8/8.13.8) with ESMTP id x1IBonQJ011814; Mon, 18 Feb 2019 20:50:49 +0900 Received: from vc1.ecl.ntt.co.jp (localhost [127.0.0.1]) by vc1.ecl.ntt.co.jp (Postfix) with ESMTP id 1D137EA818D; Mon, 18 Feb 2019 20:50:49 +0900 (JST) Received: from localhost.localdomain (lobster.nslab.ecl.ntt.co.jp [129.60.13.95]) by vc1.ecl.ntt.co.jp (Postfix) with ESMTP id 0C205EA815C; Mon, 18 Feb 2019 20:50:49 +0900 (JST) From: ogawa.yasufumi@lab.ntt.co.jp To: spp@dpdk.org, ferruh.yigit@intel.com, ogawa.yasufumi@lab.ntt.co.jp Date: Mon, 18 Feb 2019 20:48:20 +0900 Message-Id: <1550490511-31683-10-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1550490511-31683-1-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> References: <1550490511-31683-1-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> X-TM-AS-MML: disable Subject: [spp] [PATCH 09/20] docs: update how to use for virsh 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: Mon, 18 Feb 2019 11:50:51 -0000 From: Yasufumi Ogawa This patch is to update how to use section for setting up VMs. Signed-off-by: Yasufumi Ogawa --- docs/guides/gsg/howto_use.rst | 266 +++++++++++++++++++++++----- docs/guides/spp_vf/gsg/howto_use.rst | 197 -------------------- docs/guides/spp_vf/gsg/index.rst | 10 -- docs/guides/spp_vf/index.rst | 1 - docs/guides/spp_vf/use_cases/mirror_vms.rst | 2 +- 5 files changed, 218 insertions(+), 258 deletions(-) delete mode 100644 docs/guides/spp_vf/gsg/howto_use.rst delete mode 100644 docs/guides/spp_vf/gsg/index.rst diff --git a/docs/guides/gsg/howto_use.rst b/docs/guides/gsg/howto_use.rst index d3b0ceb..749f8ba 100644 --- a/docs/guides/gsg/howto_use.rst +++ b/docs/guides/gsg/howto_use.rst @@ -315,17 +315,17 @@ secondary processes. - EAL options: - - -l: core list - - --socket-mem: Memory size on each of NUMA nodes. - - --huge-dir: Path of hugepage dir. - - --proc-type: Process type. - - --base-virtaddr: Specify base virtual address. + - ``-l``: core list + - ``--socket-mem``: Memory size on each of NUMA nodes. + - ``--huge-dir``: Path of hugepage dir. + - ``--proc-type``: Process type. + - ``--base-virtaddr``: Specify base virtual address. - Application options: - - -p: Port mask. - - -n: Number of ring PMD. - - -s: IP address of controller and port prepared for primary. + - ``-p``: Port mask. + - ``-n``: Number of ring PMD. + - ``-s``: IP address of controller and port prepared for primary. .. _spp_gsg_howto_sec: @@ -342,8 +342,8 @@ This section describes about the simplest ``spp_nfv`` which simply forward packets similar to ``l2fwd``. -Launch spp_nfv on Host -~~~~~~~~~~~~~~~~~~~~~~ +spp_nfv +~~~~~~~ Run ``spp_nfv`` with options. @@ -353,26 +353,134 @@ Run ``spp_nfv`` with options. $ cd /path/to/spp $ sudo ./src/nfv/x86_64-native-linuxapp-gcc/spp_nfv \ -l 2-3 -n 4 \ - --proc-type=secondary \ + --proc-type secondary \ -- \ -n 1 \ -s 192.168.1.100:6666 -- EAL options: - - - -l: core list (two cores required) - - --proc-type: process type - -- Application options: +EAL options are the same as primary process. Here is a list of application +options of ``spp_nfv``. - - -n: secondary ID - - -s: IP address of controller and port prepared for secondary +* ``-n``: Secondary ID. +* ``-s``: IP address and secondary port of spp-ctl. +* ``--vhost-client``: Enable vhost-user client mode. Secondary ID is used to identify for sending messages and must be unique among all of secondaries. If you attempt to launch a secondary process with the same ID, it is failed. +If ``--vhost-client`` option is specified, then ``vhost-user`` act as +the client, otherwise the server. +For reconnect feature from SPP to VM, ``--vhost-client`` option can be +used. This reconnect features requires QEMU 2.7 (or later). +See also `Vhost Sample Application +`_. + + +spp_vf +~~~~~~ + +``spp_vf`` is a kind of secondary process. + +.. code-block:: console + + $ sudo ./src/vf/x86_64-native-linuxapp-gcc/spp_vf \ + -l 0,2-13 -n 4 \ + --proc-type secondary \ + -- \ + --client-id 1 \ + -s 192.168.1.100:6666 \ + --vhost-client + +EAL options are the same as primary process. Here is a list of application +options of ``spp_vf``. + +* ``--client-id``: Client ID unique among secondary processes. +* ``-s``: IPv4 address and secondary port of spp-ctl. +* ``--vhost-client``: Enable vhost-user client mode. + + +spp_mirror +~~~~~~~~~~ + +``spp_mirror`` is a kind of secondary process, and options are same as +``spp_vf``. + +.. code-block:: console + + $ sudo ./src/mirror/x86_64-native-linuxapp-gcc/spp_mirror \ + -l 1,2 -n 4 \ + --proc-type secondary \ + -- \ + --client-id 1 \ + -s 192.168.1.100:6666 \ + -vhost-client + +EAL options are the same as primary process. Here is a list of application +options of ``spp_mirror``. + +* ``--client-id``: Client ID unique among secondary processes. +* ``-s``: IPv4 address and secondary port of spp-ctl. +* ``--vhost-client``: Enable vhost-user client mode. + + +.. _spp_vf_gsg_howto_use_spp_pcap: + +spp_pcap +~~~~~~~~ + +``spp_pcap`` is a kind of secondary process. + +.. code-block:: console + + $ sudo ./src/pcap/x86_64-native-linuxapp-gcc/spp_pcap \ + -l 0-3 -n 4 \ + --proc-type secondary \ + -- \ + --client-id 1 \ + -s 192.168.1.100:6666 \ + -c phy:0 \ + --out-dir /path/to/dir \ + --fsize 107374182 + +EAL options are the same as primary process. Here is a list of application +options of ``spp_pcap``. + +* ``--client-id``: Client ID unique among secondary processes. +* ``-s``: IPv4 address and secondary port of spp-ctl. +* ``-c``: Captured port, e.g. ``phy:0``, ``ring:1`` or so. +* ``--out-dir``: Optional. Path of dir for captured file. Default is ``/tmp``. +* ``--fsize``: Optional. Maximum size of a capture file. Default is ``1GiB``. + +Captured file of LZ4 is generated in ``/tmp`` by default. +The name of file is consists of timestamp, resource ID of captured port, +ID of ``writer`` threads and sequential number. +Timestamp is decided when capturing is started and formatted as +``YYYYMMDDhhmmss``. +Both of ``writer`` thread ID and sequential number are started from ``1``. +Sequential number is required for the case if the size of +captured file is reached to the maximum and another file is generated to +continue capturing. + +This is an example of captured file. It consists of timestamp, +``20190214154925``, port ``phy0``, thread ID ``1`` and sequential number +``1``. + +.. code-block:: none + + /tmp/spp_pcap.20190214154925.phy0.1.1.pcap.lz4 + +``spp_pcap`` also generates temporary files which are owned by each of +``writer`` threads until capturing is finished or the size of captured file +is reached to the maximum. +This temporary file has additional extension ``tmp`` at the end of file +name. + +.. code-block:: none + + /tmp/spp_pcap.20190214154925.phy0.1.1.pcap.lz4.tmp + Launch from SPP CLI ~~~~~~~~~~~~~~~~~~~ @@ -589,44 +697,55 @@ Usecases of network configuration are explained in the next chapter. Using virsh ~~~~~~~~~~~ -First of all, please check version of qemu-kvm. +First of all, please check version of qemu. .. code-block:: console $ qemu-system-x86_64 --version -If your system does not have qemu-kvm or the version of qemu is less than 2.7, -then please install qemu following -the instruction of https://wiki.qemu.org/index.php/Hosts/Linux -to install qemu 2.7. -You may need to install libvirt-bin, -virtinst, bridge-utils packages via ``apt-get`` install to run -``virt-install``. - +You should install qemu 2.7 or higher for using vhost-user client mode. +Refer `instruction +`_ +to install. ``virsh`` is a command line interface that can be used to create, destroy, -stop start and edit VMs and configure. After create an image file, -you can setup it with ``virt-install``. -``--location`` is a URL of installer and it should be -``http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/`` -for amd64. +stop start and edit VMs and configure. + +You also need to install following packages to run ``virt-install``. + +* libvirt-bin +* virtinst +* bridge-utils + +virt-install +^^^^^^^^^^^^ + +Install OS image with ``virt-install`` command. +``--location`` is a URL of installer. Use Ubuntu 16.04 for amd64 in this +case. + +.. code-block:: none + + http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/ + +This is an example of ``virt-install``. .. code-block:: console virt-install \ - --name [VM_NAME] \ + --name VM_NAME \ --ram 4096 \ - --disk path=/var/lib/libvirt/images/[VM_NAME].img,size=30 \ + --disk path=/var/lib/libvirt/images/VM_NAME.img,size=30 \ --vcpus 4 \ --os-type linux \ --os-variant ubuntu16.04 \ --network network=default \ --graphics none \ --console pty,target_type=serial \ - --location '[LOCATION]' \ + --location 'http://archive.ubuntu.com/ubuntu/dists/xenial/main/...' --extra-args 'console=ttyS0,115200n8 serial' -You may need type the following commands through ssh to activate console. +You might need to enable serial console as following. .. code-block:: console @@ -634,26 +753,44 @@ You may need type the following commands through ssh to activate console. $sudo systemctl start serial-getty@ttyS0.service -Edit VM configuration with virsh. +Edit Config +^^^^^^^^^^^ + +Edit configuration of VM with virsh command. The name of VMs are found from +``virsh list``. .. code-block:: console - $ virsh edit [VM_NAME] + # Find the name of VM + $ sudo virsh list --all + + $ sudo virsh edit VM_NAME + +You need to define namespace ``qemu`` to use tags such as +````. + +.. code-block:: none + + xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0' + +In addition, you need to add attributes for specific resources for DPDK and SPP. + +* ```` +* ```` + +Take care about the index numbers of devices should be the same value such as +``chr0`` or ``sock0``. It is referred as ID of vhost port from SPP. -You need to add ``xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'`` -into the domain tag because of adding ```` tag. -In addition, you need to add the tag enclosed by ```` and -````, ```` and ```` -because SPP uses vhost-user as interface with VM. -Note that number used in those tags should be the same value -(e.g. chr0,sock0,vhost-net0) and these values should correspond -to "add vhost N" (in this example 0). MAC address used in -```` can be specified when registering MAC address to classifier using Secondary command. - The following is an example of modified xml file: +.. code-block:: none + + + + +Here is an example of XML config for using with SPP. .. code-block:: xml @@ -745,3 +882,34 @@ using Secondary command. + + +Launch VM +^^^^^^^^^ + +After updating XML configuration, launch VM with ``virsh start``. + +.. code-block:: console + + $ virsh start VM_NAME + +It is required to add network configurations for processes running on the VMs. +If this configuration is skipped, processes cannot communicate with others +via SPP. + +On the VMs, add an interface and disable offload. + +.. code-block:: console + + # Add interface + $ sudo ifconfig IF_NAME inet IPADDR netmask NETMASK up + + # Disable offload + $ sudo ethtool -K IF_NAME tx off + +On host machine, it is also required to disable offload. + +.. code-block:: console + + # Disable offload for VM + $ sudo ethtool -K IF_NAME tx off diff --git a/docs/guides/spp_vf/gsg/howto_use.rst b/docs/guides/spp_vf/gsg/howto_use.rst deleted file mode 100644 index 260527e..0000000 --- a/docs/guides/spp_vf/gsg/howto_use.rst +++ /dev/null @@ -1,197 +0,0 @@ -.. SPDX-License-Identifier: BSD-3-Clause - Copyright(c) 2019 Nippon Telegraph and Telephone Corporation - -.. _spp_vf_gsg_howto_use: - -How to Use -========== - -SPP Controller --------------- - -Go to the SPP's directory first. - -.. code-block:: console - - $ cd /path/to/spp - -Launch ``spp-ctl`` before launching SPP primary and secondary processes. -You also need to launch ``spp.py`` if you use ``spp_vf`` from CLI. -``-b`` option is for binding IP address to communicate other SPP processes, -but no need to give it explicitly if ``127.0.0.1`` or ``localhost`` although -doing explicitly in this example to be more understandable. - -.. code-block:: console - - # Launch spp-ctl and spp.py - $ python3 ./src/spp-ctl/spp-ctl -b 192.168.1.100 - $ python ./src/spp.py -b 192.168.1.100 - - -SPP Primary ------------ - -SPP primary allocates and manages resources for secondary processes. -You need to run SPP primary before secondary processes. - -SPP primary has two kinds of options for DPDK and spp. -Before ``--`` are for DPDK is, and after it are for spp. - -See `Running a Sample Application -`_ -in DPDK documentation for options. - -Application specific options of spp primary. - - * ``-p``: Port mask. - * ``-n``: Number of rings. - * ``-s``: IPv4 address and port for spp primary. - -This is an example of launching ``spp_primary``. - -.. code-block:: console - - $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \ - -l 0 -n 4 --socket-mem 512,512 \ - --huge-dir /run/hugepages/kvm \ - --proc-type primary \ - -- \ - -p 0x03 -n 10 \ - -s 192.168.1.100:5555 - - -.. _spp_vf_gsg_howto_use_spp_vf: - -spp_vf ------- - -``spp_vf`` is a kind of secondary process, so it takes both of EAL options and -application specific options. Here is a list of application specific options. - - * ``--client-id``: Client ID unique among secondary processes. - * ``-s``: IPv4 address and secondary port of spp-ctl. - * ``--vhost-client``: Enable vhost-user client mode. - -This is an example of launching ``spp_vf``. - -.. code-block:: console - - $ sudo ./src/vf/x86_64-native-linuxapp-gcc/spp_vf \ - -l 0,2-13 -n 4 \ - --proc-type=secondary \ - -- \ - --client-id 1 \ - -s 192.168.1.100:6666 \ - --vhost-client - -If ``--vhost-client`` option is specified, then ``vhost-user`` act as -the client, otherwise the server. -For reconnect feature from SPP to VM, ``--vhost-client`` option can be -used. This reconnect features requires QEMU 2.7 (or later). -See also `Vhost Sample Application -`_. - - -.. _spp_vf_gsg_howto_use_spp_mirror: - -spp_mirror ----------- - -``spp_mirror`` is a kind of secondary process, and options are same as -``spp_vf``. - -.. code-block:: console - - $ sudo ./src/mirror/x86_64-native-linuxapp-gcc/spp_mirror \ - -l 1,2 -n 4 \ - --proc-type=secondary \ - -- \ - --client-id 1 \ - -s 192.168.1.100:6666 \ - -vhost-client - - -.. _spp_vf_gsg_howto_use_spp_pcap: - -spp_pcap --------- - -``spp_pcap`` is a kind of secondary process, so it takes both of EAL options -and application specific options. - -.. code-block:: console - - $ sudo ./src/pcap/x86_64-native-linuxapp-gcc/spp_pcap \ - -l 0-3 -n 4 \ - --proc-type=secondary \ - -- \ - --client-id 1 \ - -s 192.168.1.100:6666 \ - -c phy:0 \ - --out-dir /path/to/dir \ - --fsize 107374182 - -Here is a list of ``spp_pcap`` specific options. - - * ``-c``: Captured port, e.g. ``phy:0``, ``ring:1`` or so. - * ``--out-dir``: Optional. Path of dir for captured file. Default is ``/tmp``. - * ``--fsize``: Optional. Maximum size of a capture file. Default is ``1GiB``. - -Captured file of LZ4 is generated in ``/tmp`` by default. -The name of file is consists of timestamp, resource ID of captured port, -ID of ``writer`` threads and sequential number. -Timestamp is decided when capturing is started and formatted as -``YYYYMMDDhhmmss``. -Both of ``writer`` thread ID and sequential number are started from ``1``. -Sequential number is required for the case if the size of -captured file is reached to the maximum and another file is generated to -continue capturing. - -This is an example of captured file. It consists of timestamp, -``20190214154925``, port ``phy0``, thread ID ``1`` and sequential number -``1``. - -.. code-block:: none - - /tmp/spp_pcap.20190214154925.phy0.1.1.pcap.lz4 - -``spp_pcap`` also generates temporary files which are owned by each of -``writer`` threads until capturing is finished or the size of captured file -is reached to the maximum. -This temporary file has additional extension ``tmp`` at the end of file -name. - -.. code-block:: none - - /tmp/spp_pcap.20190214154925.phy0.1.1.pcap.lz4.tmp - - -Using VM with virsh -------------------- - -In this section, VM is launched with ``virsh`` command. - -.. code-block:: console - - $ virsh start [VM] - -It is required to add network configuration for processes running on the VMs. -If this configuration is skipped, processes cannot communicate with others -via SPP. - -On the VMs, add an interface and disable offload. - -.. code-block:: console - - # Add interface - $ sudo ifconfig [IF_NAME] inet [IP_ADDR] netmask [NETMASK] up - - # Disable offload - $ sudo ethtool -K [IF_NAME] tx off - -On host machine, it is also required to disable offload. - -.. code-block:: console - - # Disable offload for VM - $ sudo ethtool -K [IF_NAME] tx off diff --git a/docs/guides/spp_vf/gsg/index.rst b/docs/guides/spp_vf/gsg/index.rst deleted file mode 100644 index 623495f..0000000 --- a/docs/guides/spp_vf/gsg/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. SPDX-License-Identifier: BSD-3-Clause - Copyright(c) 2010-2014 Intel Corporation - -Getting Started -=============== - -.. toctree:: - :maxdepth: 2 - - howto_use diff --git a/docs/guides/spp_vf/index.rst b/docs/guides/spp_vf/index.rst index e5b79ba..412952c 100644 --- a/docs/guides/spp_vf/index.rst +++ b/docs/guides/spp_vf/index.rst @@ -8,6 +8,5 @@ SPP VF :maxdepth: 2 :numbered: - gsg/index use_cases/index explain/index diff --git a/docs/guides/spp_vf/use_cases/mirror_vms.rst b/docs/guides/spp_vf/use_cases/mirror_vms.rst index 39b8ca6..70311f8 100644 --- a/docs/guides/spp_vf/use_cases/mirror_vms.rst +++ b/docs/guides/spp_vf/use_cases/mirror_vms.rst @@ -73,7 +73,7 @@ with ``-n 16`` for giving enough number of rings. Launch spp_vf ~~~~~~~~~~~~~ -Launch ``VM1`` as described in :ref:`spp_vf_use_cases_usecase1_setup_vm`, +Launch ``VM1`` and launch ``spp_vf`` with core list ``-l 0,2-14`` in this usecase. .. code-block:: console -- 2.7.4