Initial commit of Sphinx docs

Change-Id: I9fca8fb98502dffc2555f9de7f507b6f006e0e77
Signed-off-by: John DeNisco <jdenisco@cisco.com>

8 files changed, 514 insertions, 0 deletions

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 @@
+<domain type='kvm' id='54'>
+  <name>iperf-server</name>
+  <memory unit='KiB'>1048576</memory>
+  <currentMemory unit='KiB'>1048576</currentMemory>
+  <memoryBacking>
+    <hugepages>
+      <page size='2048' unit='KiB'/>
+    </hugepages>
+  </memoryBacking>
+  <vcpu placement='static'>1</vcpu>
+  <resource>
+    <partition>/machine</partition>
+  </resource>
+  <os>
+    <type arch='x86_64' machine='pc-i440fx-xenial'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <features>
+    <acpi/>
+    <apic/>
+  </features>
+  <cpu mode='host-model'>
+    <model fallback='allow'></model>
+    <numa>
+      <cell id='0' cpus='0' memory='262144' unit='KiB' memAccess='shared'/>
+    </numa>
+  </cpu>
+  <clock offset='utc'>
+    <timer name='rtc' tickpolicy='catchup'/>
+    <timer name='pit' tickpolicy='delay'/>
+    <timer name='hpet' present='no'/>
+  </clock>
+  <on_poweroff>destroy</on_poweroff>
+  <on_reboot>restart</on_reboot>
+  <on_crash>restart</on_crash>
+  <pm>
+    <suspend-to-mem enabled='no'/>
+    <suspend-to-disk enabled='no'/>
+  </pm>
+  <devices>
+    <emulator>/usr/bin/kvm</emulator>
+    <disk type='file' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <source file='/tmp/xenial-mod.img'/>
+      <backingStore/>
+      <target dev='vda' bus='virtio'/>
+      <alias name='virtio-disk0'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
+    </disk>
+    <disk type='file' device='cdrom'>
+      <driver name='qemu' type='raw'/>
+      <source file='/scratch/jdenisco/sae/configs/cloud-config.iso'/>
+      <backingStore/>
+      <target dev='hda' bus='ide'/>
+      <readonly/>
+      <alias name='ide0-0-0'/>
+      <address type='drive' controller='0' bus='0' target='0' unit='0'/>
+    </disk>
+    <controller type='usb' index='0' model='ich9-ehci1'>
+      <alias name='usb'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x06' function='0x7'/>
+    </controller>
+    <controller type='pci' index='0' model='pci-root'>
+      <alias name='pci.0'/>
+    </controller>
+    <controller type='ide' index='0'>
+      <alias name='ide'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x1'/>
+    </controller>
+    <controller type='virtio-serial' index='0'>
+      <alias name='virtio-serial0'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x05' function='0x0'/>
+    </controller>
+    <interface type='vhostuser'>
+      <mac address='52:54:00:4c:47:f2'/>
+      <source type='unix' path='/tmp//vm00.sock' mode='server'/>
+      <model type='virtio'/>
+      <alias name='net1'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/>
+    </interface>
+    <serial type='pty'>
+      <source path='/dev/pts/2'/>
+      <target port='0'/>
+      <alias name='serial0'/>
+    </serial>
+    <console type='pty' tty='/dev/pts/2'>
+      <source path='/dev/pts/2'/>
+      <target type='serial' port='0'/>
+      <alias name='serial0'/>
+    </console>
+    <input type='mouse' bus='ps2'/>
+    <input type='keyboard' bus='ps2'/>
+    <graphics type='vnc' port='5900' autoport='yes' listen='127.0.0.1'>
+      <listen type='address' address='127.0.0.1'/>
+    </graphics>
+    <memballoon model='virtio'>
+      <alias name='balloon0'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x08' function='0x0'/>
+    </memballoon>
+  </devices>
+  <seclabel type='dynamic' model='apparmor' relabel='yes'>
+    <label>libvirt-2c4c9317-c7a5-4b37-b789-386ccda7348a</label>
+    <imagelabel>libvirt-2c4c9317-c7a5-4b37-b789-386ccda7348a</imagelabel>
+  </seclabel>
+</domain>
+
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 <https://linux.die.net/man/1/virsh>`_.
+
+The image that we use is based on an Ubuntu cloud image downloaded from:
+`Ubuntu Cloud Images <https://cloud-images.ubuntu.com/xenial/current>`_.
+
+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
+
+    <interface type='vhostuser'>
+      <mac address='52:54:00:4c:47:f2'/>
+      <source type='unix' path='/tmp//vm00.sock' mode='server'/>
+      <model type='virtio'/>
+      <alias name='net1'/>
+      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/>
+    </interface>
+
+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
+    <domain type='kvm' id='65'>
+      <name>iperf-server3</name>
+      <uuid>e23d37c1-10c3-4a6e-ae99-f315a4165641</uuid>
+      <memory unit='KiB'>262144</memory>
+    .....
+
+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 <https://docs.fd.io/csit/rls1804/report/vpp_performance_tests/packet_throughput_graphs/vm_vhost.html>`_.
+
+
+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
+