From 06dcd45ff81e06bc8cf40ed487c0b2652d346a5a Mon Sep 17 00:00:00 2001 From: John DeNisco Date: Thu, 26 Jul 2018 12:45:10 -0400 Subject: Initial commit of Sphinx docs Change-Id: I9fca8fb98502dffc2555f9de7f507b6f006e0e77 Signed-off-by: John DeNisco --- docs/usecases/vhost/index.rst | 17 ++++++ docs/usecases/vhost/iperf-vm.xml | 106 ++++++++++++++++++++++++++++++++++ docs/usecases/vhost/vhost.rst | 115 +++++++++++++++++++++++++++++++++++++ docs/usecases/vhost/vhost02.rst | 109 +++++++++++++++++++++++++++++++++++ docs/usecases/vhost/vhost03.rst | 88 ++++++++++++++++++++++++++++ docs/usecases/vhost/vhost04.rst | 43 ++++++++++++++ docs/usecases/vhost/vhost05.rst | 25 ++++++++ docs/usecases/vhost/xmlexample.rst | 11 ++++ 8 files changed, 514 insertions(+) create mode 100644 docs/usecases/vhost/index.rst create mode 100644 docs/usecases/vhost/iperf-vm.xml create mode 100644 docs/usecases/vhost/vhost.rst create mode 100644 docs/usecases/vhost/vhost02.rst create mode 100644 docs/usecases/vhost/vhost03.rst create mode 100644 docs/usecases/vhost/vhost04.rst create mode 100644 docs/usecases/vhost/vhost05.rst create mode 100644 docs/usecases/vhost/xmlexample.rst (limited to 'docs/usecases/vhost') diff --git a/docs/usecases/vhost/index.rst b/docs/usecases/vhost/index.rst new file mode 100644 index 00000000000..002ebc17639 --- /dev/null +++ b/docs/usecases/vhost/index.rst @@ -0,0 +1,17 @@ +.. _vhost: + +FD.io VPP with Virtual Machines +=============================== +This chapter will describe how to use FD.io VPP with virtual machines. We describe +how to create Vhost port with VPP and how to connect them to VPP. We will also discuss +some limitations of Vhost. + +.. toctree:: + + vhost + vhost02 + vhost03 + vhost04 + vhost05 + xmlexample + diff --git a/docs/usecases/vhost/iperf-vm.xml b/docs/usecases/vhost/iperf-vm.xml new file mode 100644 index 00000000000..be354c5f977 --- /dev/null +++ b/docs/usecases/vhost/iperf-vm.xml @@ -0,0 +1,106 @@ + + iperf-server + 1048576 + 1048576 + + + + + + 1 + + /machine + + + hvm + + + + + + + + + + + + + + + + + + destroy + restart + restart + + + + + + /usr/bin/kvm + + + + + + +
+ + + + + + + + +
+ + + +
+ + + + + + +
+ + + +
+ + + + + + +
+ + + + + + + + + + + + + + + + + + +
+ + + + + libvirt-2c4c9317-c7a5-4b37-b789-386ccda7348a + + + diff --git a/docs/usecases/vhost/vhost.rst b/docs/usecases/vhost/vhost.rst new file mode 100644 index 00000000000..f62faade306 --- /dev/null +++ b/docs/usecases/vhost/vhost.rst @@ -0,0 +1,115 @@ +.. toctree:: + +.. _vhost01: + +Prerequisites +------------- + +For this use case we will assume FD.io VPP is installed. We will also assume the user can create and start +basic virtual machines. This use case will use the linux virsh commands. For more information on virsh +refer to `virsh man page `_. + +The image that we use is based on an Ubuntu cloud image downloaded from: +`Ubuntu Cloud Images `_. + +All FD.io VPP commands are being run from a su shell. + +.. _vhosttopo: + +Topology +--------- + +In this case we will use 2 systems. One system we will be running standard linux, the other will +be running FD.io VPP. + +.. figure:: /_images/vhost-topo.png + :alt: + + Vhost Use Case Topology + +Creating The Virtual Interface +------------------------------ + +We will start on the system running FD.io VPP and show that no Virtual interfaces have been created. +We do this using the :ref:`showintcommand` command. + +Notice we do not have any virtual interfaces. We do have an interface (TenGigabitEthernet86/0/0) that +is up. This interface is connected to a system running, in our example standard linux. We will use +this system to verify our connectivity to our VM with ping. + +.. code-block:: console + + $ sudo bash + # vppctl + _______ _ _ _____ ___ + __/ __/ _ \ (_)__ | | / / _ \/ _ \ + _/ _// // / / / _ \ | |/ / ___/ ___/ + /_/ /____(_)_/\___/ |___/_/ /_/ + + vpp# clear interfaces + vpp# show int + Name Idx State Counter Count + TenGigabitEthernet86/0/0 1 up + TenGigabitEthernet86/0/1 2 down + local0 0 down + vpp# + +For more information on the interface commands refer to: :ref:`intcommands` + +The next step will be to create the virtual port using the :ref:`createvhostuser` command. +This command will create the virtual port in VPP and create a linux socket that the VM will +use to connect to VPP. + +The port can be created using VPP as the socket server or client. + +Creating the VPP port: + +.. code-block:: console + + vpp# create vhost socket /tmp/vm00.sock + VirtualEthernet0/0/0 + vpp# show int + Name Idx State Counter Count + TenGigabitEthernet86/0/0 1 up + TenGigabitEthernet86/0/1 2 down + VirtualEthernet0/0/0 3 down + local0 0 down + vpp# + +Notice the interface **VirtualEthernet0/0/0**. In this example we created the virtual interface as +a client. + +We can get more detail on the vhost connection with the :ref:`showvhost` command. + +.. code-block:: console + + vpp# show vhost + Virtio vhost-user interfaces + Global: + coalesce frames 32 time 1e-3 + number of rx virtqueues in interrupt mode: 0 + Interface: VirtualEthernet0/0/0 (ifindex 3) + virtio_net_hdr_sz 12 + features mask (0xffffffffffffffff): + features (0x58208000): + VIRTIO_NET_F_MRG_RXBUF (15) + VIRTIO_NET_F_GUEST_ANNOUNCE (21) + VIRTIO_F_ANY_LAYOUT (27) + VIRTIO_F_INDIRECT_DESC (28) + VHOST_USER_F_PROTOCOL_FEATURES (30) + protocol features (0x3) + VHOST_USER_PROTOCOL_F_MQ (0) + VHOST_USER_PROTOCOL_F_LOG_SHMFD (1) + + socket filename /tmp/vm00.sock type client errno "No such file or directory" + + rx placement: + tx placement: spin-lock + thread 0 on vring 0 + thread 1 on vring 0 + + Memory regions (total 0) + +Notice **No such file or directory** and **Memory regions (total 0)**. This is because the +VM has not been created yet. + diff --git a/docs/usecases/vhost/vhost02.rst b/docs/usecases/vhost/vhost02.rst new file mode 100644 index 00000000000..b9d1f5696c9 --- /dev/null +++ b/docs/usecases/vhost/vhost02.rst @@ -0,0 +1,109 @@ +.. _vhost02: + +Creating the Virtual Machine +---------------------------- + +We will now create the virtual machine. We use the "virsh create command". For the complete file we +use refer to :ref:`xmlexample`. + +It is important to note that in the XML file we specify the socket path that is used to connect to +FD.io VPP. + +This is done with a section that looks like this + +.. code-block:: console + + + + + + +
+ + +Notice the **interface type** and the **path** to the socket. + +Now we create the VM. The virsh list command shows the VMs that have been created. We start with no VMs. + +.. code-block:: console + + $ virsh list + Id Name State + ---------------------------------------------------- + +Create the VM with the virsh create command specifying our xml file. + +.. code-block:: console + + $ virsh create ./iperf3-vm.xml + Domain iperf-server3 created from ./iperf3-vm.xml + + $ virsh list + Id Name State + ---------------------------------------------------- + 65 iperf-server3 running + +The VM is now created. + +.. note:: + + After a VM is created an xml file can created with "virsh dumpxml". + +.. code-block:: console + + $ virsh dumpxml iperf-server3 + + iperf-server3 + e23d37c1-10c3-4a6e-ae99-f315a4165641 + 262144 + ..... + +Once the virtual machine is created notice the socket filename shows **Success** and +there are **Memory Regions**. At this point the VM and FD.io VPP are connected. Also +notice **qsz 256**. This system is running an older version of qemu. A queue size of 256 +will affect vhost throughput. The qsz should be 1024. On the web you should be able to +find ways to install a newer version of qemu or change the queue size. + +.. code-block:: console + + vpp# show vhost + Virtio vhost-user interfaces + Global: + coalesce frames 32 time 1e-3 + number of rx virtqueues in interrupt mode: 0 + Interface: VirtualEthernet0/0/0 (ifindex 3) + virtio_net_hdr_sz 12 + features mask (0xffffffffffffffff): + features (0x58208000): + VIRTIO_NET_F_MRG_RXBUF (15) + VIRTIO_NET_F_GUEST_ANNOUNCE (21) + VIRTIO_F_ANY_LAYOUT (27) + VIRTIO_F_INDIRECT_DESC (28) + VHOST_USER_F_PROTOCOL_FEATURES (30) + protocol features (0x3) + VHOST_USER_PROTOCOL_F_MQ (0) + VHOST_USER_PROTOCOL_F_LOG_SHMFD (1) + + socket filename /tmp/vm00.sock type client errno "Success" + + rx placement: + thread 1 on vring 1, polling + tx placement: spin-lock + thread 0 on vring 0 + thread 1 on vring 0 + + Memory regions (total 2) + region fd guest_phys_addr memory_size userspace_addr mmap_offset mmap_addr + ====== ===== ================== ================== ================== ================== =============== === + 0 31 0x0000000000000000 0x00000000000a0000 0x00007f1db9c00000 0x0000000000000000 0x00007f7db0400 000 + 1 32 0x00000000000c0000 0x000000000ff40000 0x00007f1db9cc0000 0x00000000000c0000 0x00007f7d94ec0 000 + + Virtqueue 0 (TX) + qsz 256 last_avail_idx 0 last_used_idx 0 + avail.flags 0 avail.idx 256 used.flags 1 used.idx 0 + kickfd 33 callfd 34 errfd -1 + + Virtqueue 1 (RX) + qsz 256 last_avail_idx 8 last_used_idx 8 + avail.flags 0 avail.idx 8 used.flags 1 used.idx 8 + kickfd 29 callfd 35 errfd -1 diff --git a/docs/usecases/vhost/vhost03.rst b/docs/usecases/vhost/vhost03.rst new file mode 100644 index 00000000000..ed583349bc6 --- /dev/null +++ b/docs/usecases/vhost/vhost03.rst @@ -0,0 +1,88 @@ +.. _vhost03: + +Bridge the Interfaces +--------------------- + +To connect the 2 interfaces we put them on an L2 bridge. + +Use the "set interface l2 bridge" command. + +.. code-block:: console + + vpp# set interface l2 bridge VirtualEthernet0/0/0 100 + vpp# set interface l2 bridge TenGigabitEthernet86/0/0 100 + vpp# show bridge + BD-ID Index BSN Age(min) Learning U-Forwrd UU-Flood Flooding ARP-Term BVI-Intf + 100 1 0 off on on on on off N/A + vpp# show bridge 100 det + BD-ID Index BSN Age(min) Learning U-Forwrd UU-Flood Flooding ARP-Term BVI-Intf + 100 1 0 off on on on on off N/A + + Interface If-idx ISN SHG BVI TxFlood VLAN-Tag-Rewrite + VirtualEthernet0/0/0 3 1 0 - * none + TenGigabitEthernet86/0/0 1 1 0 - * none + vpp# show vhost + +Bring the Interfaces Up +----------------------- + +We can now bring all the pertinent interfaces up. We can then we will then be able to communicate +with the VM from the remote system running Linux. + +Bring the interfaces up with :ref:`setintstate` command. + +.. code-block:: console + + vpp# set interface state VirtualEthernet0/0/0 up + vpp# set interface state TenGigabitEthernet86/0/0 up + vpp# sh int + Name Idx State Counter Count + TenGigabitEthernet86/0/0 1 up rx packets 2 + rx bytes 180 + TenGigabitEthernet86/0/1 2 down + VirtualEthernet0/0/0 3 up tx packets 2 + tx bytes 180 + local0 0 down + +Ping from the VM +---------------- + +The remote Linux system has an ip address of "10.0.0.2" we can now reach it from the VM. + +Use the "virsh console" command to attach to the VM. "ctrl-D" to exit. + +.. code-block:: console + + $ virsh console iperf-server3 + Connected to domain iperf-server3 + Escape character is ^] + + Ubuntu 16.04.3 LTS iperfvm ttyS0 + ..... + + root@iperfvm:~# ping 10.0.0.2 + 64 bytes from 10.0.0.2: icmp_seq=1 ttl=64 time=0.285 ms + 64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=0.154 ms + 64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=0.159 ms + 64 bytes from 10.0.0.2: icmp_seq=4 ttl=64 time=0.208 ms + + +On VPP you can now see the packet counts increasing. The packets from the VM are seen as **rx packets** +on **VirtualEthernet0/0/0**, they are then bridged to **TenGigabitEthernet86/0/0** and are seen leaving the +system as **tx packets**. The reverse is true on the way in. + +.. code-block:: console + + vpp# sh int + Name Idx State Counter Count + TenGigabitEthernet86/0/0 1 up rx packets 16 + rx bytes 1476 + tx packets 14 + tx bytes 1260 + TenGigabitEthernet86/0/1 2 down + VirtualEthernet0/0/0 3 up rx packets 14 + rx bytes 1260 + tx packets 16 + tx bytes 1476 + local0 0 down + vpp# diff --git a/docs/usecases/vhost/vhost04.rst b/docs/usecases/vhost/vhost04.rst new file mode 100644 index 00000000000..256c0b8ffa4 --- /dev/null +++ b/docs/usecases/vhost/vhost04.rst @@ -0,0 +1,43 @@ +.. _vhost04: + +Cleanup +------- + +Destroy the VMs with "virsh destroy" + +.. code-block:: console + + cto@tf-ucs-3:~$ virsh list + Id Name State + ---------------------------------------------------- + 65 iperf-server3 running + + cto@tf-ucs-3:~$ virsh destroy iperf-server3 + Domain iperf-server3 destroyed + + +Delete the Virtual port in FD.io VPP + +.. code-block:: console + + vpp# delete vhost-user VirtualEthernet0/0/0 + vpp# show int + Name Idx State Counter Count + TenGigabitEthernet86/0/0 1 up rx packets 21 + rx bytes 1928 + tx packets 19 + tx bytes 1694 + TenGigabitEthernet86/0/1 2 down + local0 0 down + +Restart FD.io VPP + +.. code-block:: console + + # service vpp restart + # vppctl show int + Name Idx State Counter Count + TenGigabitEthernet86/0/0 1 down + TenGigabitEthernet86/0/1 2 down + local0 0 down + diff --git a/docs/usecases/vhost/vhost05.rst b/docs/usecases/vhost/vhost05.rst new file mode 100644 index 00000000000..4eba6e17101 --- /dev/null +++ b/docs/usecases/vhost/vhost05.rst @@ -0,0 +1,25 @@ +.. _vhost05: + +Limitations +----------- +There are some limitations when using the qemu vhost driver. Some are described in this section. + +Performance +^^^^^^^^^^^ + +VPP performance with vHost is limited by the Qemu vHost driver. FD.io VPP 18.04 CSIT vHost testing +shows with 2 threads, 2 cores and a Queue size of 1024 the maximum NDR throughput was about 7.5 Mpps. +This is about the limit at this time. + +For all the details on the CSIT VM vhost connection refer to the +`CSIT VM vHost performance tests `_. + + +Features +^^^^^^^^ + +These are the features not supported with FD.io VPP vHost. + +* VPP implements vHost in device mode only. VPP is intended to work with Qemu which implements vHost in driver mode, it does not implement vHost driver mode. +* VPP vHost implementation does not support checksum or transmit segmentation offload. +* VPP vHost implementation does not support packet receive filtering feature for controlling receive traffic. diff --git a/docs/usecases/vhost/xmlexample.rst b/docs/usecases/vhost/xmlexample.rst new file mode 100644 index 00000000000..34445da0ccb --- /dev/null +++ b/docs/usecases/vhost/xmlexample.rst @@ -0,0 +1,11 @@ +.. _xmlexample01: + +The XML File +------------ + +An example of a file that could be used with the virsh create command. + +.. literalinclude:: iperf-vm.xml + :language: XML + :emphasize-lines: 42-49, 74-80 + -- cgit 1.2.3-korg