Initial commit of Sphinx docs

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

16 files changed, 1162 insertions, 0 deletions

diff --git a/docs/reference/cmdreference/index.rst b/docs/reference/cmdreference/index.rst
new file mode 100644
index 00000000000..5c8effa3310
--- /dev/null
+++ b/docs/reference/cmdreference/index.rst
@@ -0,0 +1,55 @@
+.. _cmdreference:
+
+Command Line Reference
+======================
+
+This is a reference guide for the vpp debug commands that are referenced in the within these documents. This is **NOT** a complete list. For a complete list refer to the Debug CLI section of the 
+`Source Code Documents <https://docs.fd.io/vpp/18.07/clicmd.html>`_.
+
+The debug CLI can be executed from a su shell using the vppctl command.
+
+.. code-block:: console
+
+    # sudo bash
+    # vppctl show interface
+                  Name               Idx       State          Counter          Count     
+    TenGigabitEthernet86/0/0          1         up       rx packets               6569213
+                                                         rx bytes              9928352943
+                                                         tx packets                 50384
+                                                         tx bytes                 3329279
+    TenGigabitEthernet86/0/1          2        down      
+    VirtualEthernet0/0/0              3         up       rx packets                 50384
+                                                         rx bytes                 3329279
+                                                         tx packets               6569213
+                                                         tx bytes              9928352943
+                                                         drops                       1498
+    local0                            0        down      
+
+Commands can also be executed from the vppct shell.
+
+.. code-block:: console
+
+    # vppctl
+        _______    _        _   _____  ___ 
+     __/ __/ _ \  (_)__    | | / / _ \/ _ \
+     _/ _// // / / / _ \   | |/ / ___/ ___/
+     /_/ /____(_)_/\___/   |___/_/  /_/    
+    
+    vpp# show interface 
+                  Name               Idx       State          Counter          Count     
+    TenGigabitEthernet86/0/0          1         up       rx packets               6569213
+                                                         rx bytes              9928352943
+                                                         tx packets                 50384
+                                                         tx bytes                 3329279
+    TenGigabitEthernet86/0/1          2        down      
+    VirtualEthernet0/0/0              3         up       rx packets                 50384
+                                                         rx bytes                 3329279
+                                                         tx packets               6569213
+                                                         tx bytes              9928352943
+                                                         drops                       1498
+    local0                            0        down      
+
+.. toctree::
+
+   interface/index.rst
+   vhost/index.rst
diff --git a/docs/reference/cmdreference/interface/hardware.rst b/docs/reference/cmdreference/interface/hardware.rst
new file mode 100644
index 00000000000..f4d334fd935
--- /dev/null
+++ b/docs/reference/cmdreference/interface/hardware.rst
@@ -0,0 +1,109 @@
+.. _hardwarecommands:
+
+.. toctree::
+
+Show Hardware-Interfaces
+========================
+Display more detailed information about all or a list of given
+interfaces. The verboseness of the output can be controlled by the
+following optional parameters:
+
+-  brief: Only show name, index and state (default for bonded
+   interfaces).
+-  verbose: Also display additional attributes (default for all other
+   interfaces).
+-  detail: Also display all remaining attributes and extended
+   statistics.
+
+**To limit the output of the command to bonded interfaces and their
+slave interfaces, use the '*bond*' optional parameter.**
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    show hardware-interfaces [brief|verbose|detail] [bond] [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]].
+
+Examples
+--------
+Example of how to display default data for all interfaces:
+
+.. code-block:: console
+
+    vpp# show hardware-interfaces
+                  Name                Idx   Link  Hardware
+    GigabitEthernet7/0/0               1     up   GigabitEthernet7/0/0
+      Ethernet address ec:f4:bb:c0:bc:fc
+      Intel e1000
+        carrier up full duplex speed 1000 mtu 9216
+        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
+        cpu socket 0
+    GigabitEthernet7/0/1               2     up   GigabitEthernet7/0/1
+      Ethernet address ec:f4:bb:c0:bc:fd
+      Intel e1000
+        carrier up full duplex speed 1000 mtu 9216
+        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
+        cpu socket 0
+    VirtualEthernet0/0/0               3     up   VirtualEthernet0/0/0
+      Ethernet address 02:fe:a5:a9:8b:8e
+    VirtualEthernet0/0/1               4     up   VirtualEthernet0/0/1
+      Ethernet address 02:fe:c0:4e:3b:b0
+    VirtualEthernet0/0/2               5     up   VirtualEthernet0/0/2
+      Ethernet address 02:fe:1f:73:92:81
+    VirtualEthernet0/0/3               6     up   VirtualEthernet0/0/3
+      Ethernet address 02:fe:f2:25:c4:68
+    local0                             0    down  local0
+      local
+
+Example of how to display '*verbose*' data for an interface by name and software index (where 2 is the software index):
+
+.. code-block:: console
+
+    vpp# show hardware-interfaces GigabitEthernet7/0/0 2 verbose
+                   Name                Idx   Link  Hardware
+    GigabitEthernet7/0/0               1     up   GigabitEthernet7/0/0
+      Ethernet address ec:f4:bb:c0:bc:fc
+      Intel e1000
+        carrier up full duplex speed 1000 mtu 9216
+        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
+        cpu socket 0
+    GigabitEthernet7/0/1               2    down  GigabitEthernet7/0/1
+      Ethernet address ec:f4:bb:c0:bc:fd
+      Intel e1000
+        carrier up full duplex speed 1000 mtu 9216
+        rx queues 1, rx desc 1024, tx queues 3, tx desc 1024
+        cpu socket 0
+
+Clear Hardware-Interfaces
+=========================
+
+Clear the extended statistics for all or a list of given interfaces
+(statistics associated with the '*show hardware-interfaces*' command).
+
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    clear hardware-interfaces [<interface> [<interface> [..]]] [<sw_idx> [<sw_idx> [..]]].
+                
+
+Examples
+--------
+
+Example of how to clear the extended statistics for all interfaces:
+
+
+.. code-block:: console
+
+        vpp# clear hardware-interfaces
+
+Example of how to clear the extended statistics for an interface by name and software index (where 2 is the software index): 
+
+.. code-block:: console
+
+        vpp# clear hardware-interfaces GigabitEthernet7/0/0 2
+
+
diff --git a/docs/reference/cmdreference/interface/index.rst b/docs/reference/cmdreference/interface/index.rst
new file mode 100644
index 00000000000..db4aa44bba2
--- /dev/null
+++ b/docs/reference/cmdreference/interface/index.rst
@@ -0,0 +1,10 @@
+.. _interfacecommands:
+
+Interface Commands
+==================
+
+.. toctree::
+
+   hardware
+   interface
+   subinterface
diff --git a/docs/reference/cmdreference/interface/interface.rst b/docs/reference/cmdreference/interface/interface.rst
new file mode 100644
index 00000000000..a3429037e8b
--- /dev/null
+++ b/docs/reference/cmdreference/interface/interface.rst
@@ -0,0 +1,165 @@
+.. _intcommands:
+
+Interface Commands
+==================
+
+.. toctree::
+
+.. _showintcommand:
+
+Show Interface
+==============
+Shows software interface information including counters and features
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    show interface [address|addr|features|feat] [<interface> [<interface> [..]]]
+
+Examples
+--------
+
+Example of how to show the interface counters:
+
+.. code-block:: console
+
+    vpp# show int
+                  Name               Idx       State          Counter          Count     
+    TenGigabitEthernet86/0/0          1         up       rx packets               6569213
+                                                         rx bytes              9928352943
+                                                         tx packets                 50384
+                                                         tx bytes                 3329279
+    TenGigabitEthernet86/0/1          2        down      
+    VirtualEthernet0/0/0              3         up       rx packets                 50384
+                                                         rx bytes                 3329279
+                                                         tx packets               6569213
+                                                         tx bytes              9928352943
+                                                         drops                       1498
+    local0                            0        down      
+
+Example of how to display the interface placement:
+
+.. code-block:: console
+
+    vpp# show interface rx-placement
+    Thread 1 (vpp_wk_0):
+      node dpdk-input:
+        GigabitEthernet7/0/0 queue 0 (polling)
+      node vhost-user-input:
+        VirtualEthernet0/0/12 queue 0 (polling)
+        VirtualEthernet0/0/12 queue 2 (polling)
+        VirtualEthernet0/0/13 queue 0 (polling)
+        VirtualEthernet0/0/13 queue 2 (polling)
+    Thread 2 (vpp_wk_1):
+      node dpdk-input:
+        GigabitEthernet7/0/1 queue 0 (polling)
+      node vhost-user-input:
+        VirtualEthernet0/0/12 queue 1 (polling)
+        VirtualEthernet0/0/12 queue 3 (polling)
+        VirtualEthernet0/0/13 queue 1 (polling)
+        VirtualEthernet0/0/13 queue 3 (polling)
+
+Clear Interfaces
+================
+Clear the statistics for all interfaces (statistics associated with the
+'*show interface*' command).
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    clear interfaces
+
+Example
+-------
+Example of how to clear the statistics for all interfaces:
+
+.. code-block:: console
+
+    vpp# clear interfaces
+
+Set Interface Mac Address
+=========================
+The '*set interface mac address* ' command allows to set MAC address of
+given interface. In case of NIC interfaces the one has to support MAC
+address change. A side effect of MAC address change are changes of MAC
+addresses in FIB tables (ipv4 and ipv6).
+
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    set interface mac address <interface> <mac-address>.
+
+Examples
+--------
+
+Examples of how to change MAC Address of interface:
+
+.. code-block:: console
+
+    vpp# set interface mac address GigabitEthernet0/8/0 aa:bb:cc:dd:ee:01
+    vpp# set interface mac address host-vpp0 aa:bb:cc:dd:ee:02
+    vpp# set interface mac address tap-0 aa:bb:cc:dd:ee:03
+    vpp# set interface mac address pg0 aa:bb:cc:dd:ee:04
+
+Set Interface Mtu
+=================
+
+.. toctree::
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    set interface mtu [packet|ip4|ip6|mpls] <value> <interface>.
+
+Set Interface Promiscuous
+=========================
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    set interface promiscuous [on|off] <interface>.
+
+.. _setintstate:
+
+Set Interface State
+===================
+This command is used to change the admin state (up/down) of an
+interface.
+
+If an interface is down, the optional '*punt*' flag can also be set. The
+'*punt*' flag implies the interface is disabled for forwarding but punt
+all traffic to slow-path. Use the '*enable*' flag to clear '*punt*' flag
+(interface is still down).
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    set interface state <interface> [up|down|punt|enable].
+
+Examples
+--------
+
+Example of how to configure the admin state of an interface to **up**:
+
+.. code-block:: console
+
+    vpp# set interface state GigabitEthernet2/0/0 up
+
+Example of how to configure the admin state of an interface to **down**:
+
+.. code-block:: console
+
+    vpp# set interface state GigabitEthernet2/0/0 down
diff --git a/docs/reference/cmdreference/interface/subinterface.rst b/docs/reference/cmdreference/interface/subinterface.rst
new file mode 100644
index 00000000000..24519bc1a26
--- /dev/null
+++ b/docs/reference/cmdreference/interface/subinterface.rst
@@ -0,0 +1,117 @@
+.. _subinterfacecommands:
+
+.. toctree::
+
+Create Sub-Interfaces
+=====================
+This command is used to add VLAN IDs to interfaces, also known as
+subinterfaces. The primary input to this command is the '*interface*'
+and '*subId*' (subinterface Id) parameters. If no additional VLAN ID is
+provide, the VLAN ID is assumed to be the '*subId*'. The VLAN ID and
+'*subId*' can be different, but this is not recommended.
+
+This command has several variations:
+
+-  **create sub-interfaces <interface> <subId>** - Create a subinterface
+   to process packets with a given 802.1q VLAN ID (same value as the
+   '*subId*').
+-  **create sub-interfaces <interface> <subId> default** - Adding the
+   '*default*' parameter indicates that packets with VLAN IDs that do
+   not match any other subinterfaces should be sent to this
+   subinterface.
+-  **create sub-interfaces <interface> <subId> untagged** - Adding the
+   '*untagged*' parameter indicates that packets no VLAN IDs should be
+   sent to this subinterface.
+-  **create sub-interfaces <interface> <subId>-<subId>** - Create a
+   range of subinterfaces to handle a range of VLAN IDs.
+-  **create sub-interfaces <interface> <subId> dot1q|dot1ad <vlanId>|any
+   [exact-match]** - Use this command to specify the outer VLAN ID, to
+   either be explicited or to make the VLAN ID different from the
+   '*subId*'.
+-  **create sub-interfaces <interface> <subId> dot1q|dot1ad <vlanId>|any
+   inner-dot1q <vlanId>|any [exact-match]** - Use this command to
+   specify the outer VLAN ID and the innner VLAN ID.
+
+When '*dot1q*' or '*dot1ad*' is explictly entered, subinterfaces can be
+configured as either exact-match or non-exact match. Non-exact match is
+the CLI default. If '*exact-match*' is specified, packets must have the
+same number of VLAN tags as the configuration. For non-exact-match,
+packets must at least that number of tags. L3 (routed) interfaces must
+be configured as exact-match. L2 interfaces are typically configured as
+non-exact-match. If '*dot1q*' or '*dot1ad*' is NOT entered, then the
+default behavior is exact-match.
+
+Use the '*show interface*' command to display all subinterfaces.
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    create sub-interfaces <interface> {<subId> [default|untagged]} | {<subId>-<subId>} | {<subId> dot1q|dot1ad <vlanId>|any [inner-dot1q <vlanId>|any] [exact-match]}.
+
+Examples
+--------
+
+Example of how to create a VLAN subinterface 11 to process packets on 802.1q VLAN ID 11:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11
+
+The previous example is shorthand and is equivalent to:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 11 exact-match
+
+Example of how to create a subinterface number that is different from the VLAN ID:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100
+
+Examples of how to create q-in-q and q-in-any subinterfaces:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1q 100 inner-dot1q 200
+    vpp# create sub-interfaces GigabitEthernet2/0/0 12 dot1q 100 inner-dot1q any
+
+Examples of how to create dot1ad interfaces:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 11 dot1ad 11
+    vpp# create sub-interfaces GigabitEthernet2/0/0 12 dot1ad 100 inner-dot1q 200
+
+Examples of '*exact-match*' versus non-exact match. A packet with outer VLAN 100 and inner VLAN 200 would match this interface, because the default is non-exact match:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100
+
+However, the same packet would NOT match this interface because '*exact-match*' is specified and only one VLAN is configured, but packet contains two VLANs:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 5 dot1q 100 exact-match
+
+Example of how to created a subinterface to process untagged packets:
+
+.. code-block:: console
+
+   vpp# create sub-interfaces GigabitEthernet2/0/0 5 untagged
+
+Example of how to created a subinterface to process any packet with a VLAN ID that does not match any other subinterface:
+
+.. code-block:: console
+
+    vpp# create sub-interfaces GigabitEthernet2/0/0 7 default
+
+When subinterfaces are created, they are in the down state. Example of how to enable a newly created subinterface:
+
+.. code-block:: console
+
+    vpp# set interface GigabitEthernet2/0/0.7 up
+        
diff --git a/docs/reference/cmdreference/vhost/index.rst b/docs/reference/cmdreference/vhost/index.rst
new file mode 100644
index 00000000000..3e41718af26
--- /dev/null
+++ b/docs/reference/cmdreference/vhost/index.rst
@@ -0,0 +1,8 @@
+.. _vhostcommands:
+
+Vhost User Commands
+===================
+
+.. toctree::
+
+    vhostuser
diff --git a/docs/reference/cmdreference/vhost/vhostuser.rst b/docs/reference/cmdreference/vhost/vhostuser.rst
new file mode 100644
index 00000000000..a21c314404c
--- /dev/null
+++ b/docs/reference/cmdreference/vhost/vhostuser.rst
@@ -0,0 +1,269 @@
+.. _vhostusercommands:
+
+.. toctree::
+
+.. _createvhostuser:
+
+Create Vhost-User
+=================
+
+Create a vHost User interface. Once created, a new virtual interface
+will exist with the name '*VirtualEthernet0/0/x*', where '*x*' is the
+next free index.
+
+There are several parameters associated with a vHost interface:
+
+-  **socket <socket-filename>** - Name of the linux socket used by
+   hypervisor and VPP to manage the vHost interface. If in '*server*'
+   mode, VPP will create the socket if it does not already exist. If in
+   '*client*' mode, hypervisor will create the socket if it does not
+   already exist. The VPP code is indifferent to the file location.
+   However, if SELinux is enabled, then the socket needs to be created
+   in '*/var/run/vpp/*'.
+-  **server** - Optional flag to indicate that VPP should be the server
+   for the linux socket. If not provided, VPP will be the client. In
+   '*server*' mode, the VM can be reset without tearing down the vHost
+   Interface. In '*client*' mode, VPP can be reset without bringing down
+   the VM and tearing down the vHost Interface.
+-  **feature-mask <hex>** - Optional virtio/vhost feature set negotiated
+   at startup. **This is intended for degugging only.** It is
+   recommended that this parameter not be used except by experienced
+   users. By default, all supported features will be advertised.
+   Otherwise, provide the set of features desired.
+
+   -  0x000008000 (15) - VIRTIO_NET_F_MRG_RXBUF
+   -  0x000020000 (17) - VIRTIO_NET_F_CTRL_VQ
+   -  0x000200000 (21) - VIRTIO_NET_F_GUEST_ANNOUNCE
+   -  0x000400000 (22) - VIRTIO_NET_F_MQ
+   -  0x004000000 (26) - VHOST_F_LOG_ALL
+   -  0x008000000 (27) - VIRTIO_F_ANY_LAYOUT
+   -  0x010000000 (28) - VIRTIO_F_INDIRECT_DESC
+   -  0x040000000 (30) - VHOST_USER_F_PROTOCOL_FEATURES
+   -  0x100000000 (32) - VIRTIO_F_VERSION_1
+
+-  **hwaddr <mac-addr>** - Optional ethernet address, can be in either
+   X:X:X:X:X:X unix or X.X.X cisco format.
+-  **renumber <dev_instance>** - Optional parameter which allows the
+   instance in the name to be specified. If instance already exists,
+   name will be used anyway and multiple instances will have the same
+   name. Use with caution.
+
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    create vhost-user socket <socket-filename> [server] [feature-mask <hex>] [hwaddr <mac-addr>] [renumber <dev_instance>]
+
+
+Examples
+--------
+
+    Example of how to create a vhost interface with VPP as the client
+    and all features enabled:
+
+.. code-block:: console
+
+    vpp# create vhost-user socket /var/run/vpp/vhost1.sock
+    VirtualEthernet0/0/0
+
+Example of how to create a vhost interface with VPP as the server
+and with just multiple queues enabled:
+
+.. code-block:: console
+
+    vpp# create vhost-user socket /var/run/vpp/vhost2.sock server feature-mask 0x40400000
+    VirtualEthernet0/0/1
+
+Once the vHost interface is created, enable the interface using:
+
+.. code-block:: console
+
+    vpp# set interface state VirtualEthernet0/0/0 up
+
+.. _showvhost:
+
+Show Vhost-User
+===============
+
+Display the attributes of a single vHost User interface (provide
+interface name), multiple vHost User interfaces (provide a list of
+interface names seperated by spaces) or all Vhost User interfaces (omit
+an interface name to display all vHost interfaces).
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    show vhost-user [<interface> [<interface> [..]]] [descriptors].
+
+Examples
+--------
+Example of how to display a vhost interface:
+
+.. code-block:: console
+
+    vpp# show vhost-user VirtualEthernet0/0/0
+    Virtio vhost-user interfaces
+    Global:
+      coalesce frames 32 time 1e-3
+    Interface: VirtualEthernet0/0/0 (ifindex 1)
+    virtio_net_hdr_sz 12
+     features mask (0xffffffffffffffff):
+     features (0x50408000):
+       VIRTIO_NET_F_MRG_RXBUF (15)
+       VIRTIO_NET_F_MQ (22)
+       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 /var/run/vpp/vhost1.sock type client errno "Success"
+
+    rx placement:
+       thread 1 on vring 1
+       thread 1 on vring 5
+       thread 2 on vring 3
+       thread 2 on vring 7
+     tx placement: spin-lock
+       thread 0 on vring 0
+       thread 1 on vring 2
+       thread 2 on vring 0
+
+    Memory regions (total 2)
+    region fd    guest_phys_addr    memory_size        userspace_addr     mmap_offset        mmap_addr
+    ====== ===== ================== ================== ================== ================== ==================
+      0     60    0x0000000000000000 0x00000000000a0000 0x00002aaaaac00000 0x0000000000000000 0x00002aab2b400000
+      1     61    0x00000000000c0000 0x000000003ff40000 0x00002aaaaacc0000 0x00000000000c0000 0x00002aababcc0000
+
+     Virtqueue 0 (TX)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+      avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
+      kickfd 62 callfd 64 errfd -1
+
+     Virtqueue 1 (RX)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+      avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
+      kickfd 65 callfd 66 errfd -1
+
+     Virtqueue 2 (TX)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+      avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
+      kickfd 63 callfd 70 errfd -1
+
+     Virtqueue 3 (RX)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+      avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
+      kickfd 72 callfd 74 errfd -1
+
+     Virtqueue 4 (TX disabled)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+      avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
+      kickfd 76 callfd 78 errfd -1
+
+     Virtqueue 5 (RX disabled)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+      avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
+      kickfd 80 callfd 82 errfd -1
+
+     Virtqueue 6 (TX disabled)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+     avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
+      kickfd 84 callfd 86 errfd -1
+
+     Virtqueue 7 (RX disabled)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+      avail.flags 1 avail.idx 0 used.flags 1 used.idx 0
+      kickfd 88 callfd 90 errfd -1
+
+The optional '*descriptors*' parameter will display the same output as the
+previous example but will include the descriptor table for each queue. The output is truncated below:
+
+.. code-block:: console
+
+    vpp# show vhost-user VirtualEthernet0/0/0 descriptors
+
+    Virtio vhost-user interfaces
+    Global:
+      coalesce frames 32 time 1e-3
+    Interface: VirtualEthernet0/0/0 (ifindex 1)
+    virtio_net_hdr_sz 12
+     features mask (0xffffffffffffffff):
+     features (0x50408000):
+       VIRTIO_NET_F_MRG_RXBUF (15)
+       VIRTIO_NET_F_MQ (22)
+    :
+     Virtqueue 0 (TX)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+      avail.flags 1 avail.idx 128 used.flags 1 used.idx 0
+      kickfd 62 callfd 64 errfd -1
+
+      descriptor table:
+       id          addr         len  flags  next      user_addr
+      ===== ================== ===== ====== ===== ==================
+      0     0x0000000010b6e974 2060  0x0002 1     0x00002aabbc76e974
+      1     0x0000000010b6e034 2060  0x0002 2     0x00002aabbc76e034
+      2     0x0000000010b6d6f4 2060  0x0002 3     0x00002aabbc76d6f4
+      3     0x0000000010b6cdb4 2060  0x0002 4     0x00002aabbc76cdb4
+      4     0x0000000010b6c474 2060  0x0002 5     0x00002aabbc76c474
+      5     0x0000000010b6bb34 2060  0x0002 6     0x00002aabbc76bb34
+      6     0x0000000010b6b1f4 2060  0x0002 7     0x00002aabbc76b1f4
+      7     0x0000000010b6a8b4 2060  0x0002 8     0x00002aabbc76a8b4
+      8     0x0000000010b69f74 2060  0x0002 9     0x00002aabbc769f74
+      9     0x0000000010b69634 2060  0x0002 10    0x00002aabbc769634
+      10    0x0000000010b68cf4 2060  0x0002 11    0x00002aabbc768cf4
+    :
+      249   0x0000000000000000 0     0x0000 250   0x00002aab2b400000
+      250   0x0000000000000000 0     0x0000 251   0x00002aab2b400000
+      251   0x0000000000000000 0     0x0000 252   0x00002aab2b400000
+      252   0x0000000000000000 0     0x0000 253   0x00002aab2b400000
+      253   0x0000000000000000 0     0x0000 254   0x00002aab2b400000
+      254   0x0000000000000000 0     0x0000 255   0x00002aab2b400000
+      255   0x0000000000000000 0     0x0000 32768 0x00002aab2b400000
+
+     Virtqueue 1 (RX)
+      qsz 256 last_avail_idx 0 last_used_idx 0
+
+ 
+Debug Vhost-User
+================
+Turn on/off debug for vhost
+
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    debug vhost-user <on | off>.
+ 
+Delete Vhost-User
+========================
+Delete a vHost User interface using the interface name or the software
+interface index. Use the '*show interface*' command to determine the
+software interface index. On deletion, the linux socket will not be
+deleted.
+
+Summary/Usage
+-------------
+
+.. code-block:: shell
+
+    delete vhost-user {<interface> | sw_if_index <sw_idx>}.
+
+Examples
+--------
+Example of how to delete a vhost interface by name:
+
+.. code-block:: console
+
+    vpp# delete vhost-user VirtualEthernet0/0/1
+
+Example of how to delete a vhost interface by software interface index:
+
+.. code-block:: console
+
+    vpp# delete vhost-user sw_if_index 1
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
new file mode 100644
index 00000000000..e650ccd5407
--- /dev/null
+++ b/docs/reference/index.rst
@@ -0,0 +1,10 @@
+.. _reference:
+
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   vppvagrant/index.rst
+   cmdreference/index.rst
diff --git a/docs/reference/vppvagrant/VagrantVMSetup.rst b/docs/reference/vppvagrant/VagrantVMSetup.rst
new file mode 100644
index 00000000000..769c6186170
--- /dev/null
+++ b/docs/reference/vppvagrant/VagrantVMSetup.rst
@@ -0,0 +1,56 @@
+.. _VagrantVMSetup:
+
+.. toctree::
+
+Accessing your VM
+^^^^^^^^^^^^^^^^^
+ssh into the newly created box:
+
+.. code-block:: console
+
+    $ vagrant ssh <id>
+
+Sample output looks like:
+
+.. code-block:: console
+
+  $ vagrant ssh c1c
+  Welcome to Ubuntu 16.04 LTS (GNU/Linux 4.4.0-21-generic x86_64)
+
+   * Documentation:  https://help.ubuntu.com/
+  Last login: Mon Jun 25 08:05:38 2018 from 10.0.2.2
+  vagrant@localhost:~$
+
+
+.. note::
+  
+  Type **exit** in the command-line if you want to exit the VM.
+
+Become the root with:
+
+.. code-block:: console
+
+    $ sudo bash
+
+Now *install* VPP in the VM. Keep in mind that VPP is already built (but not yet installed) at this point based on the commands from the provisioned script *build.sh*. 
+
+When you ssh into your Vagrant box you will be placed in the directory */home/vagrant*. Change directories to */vpp/build-root*, and run these commands to install VPP based on your OS and architechture:
+
+For Ubuntu systems:
+
+.. code-block:: console
+    
+    # dpkg -i *.deb
+
+For CentOS systems:
+
+.. code-block:: console
+    
+    # rpm -Uvh *.rpm
+
+
+Since VPP is now installed, you can start running VPP with:
+
+.. code-block:: console
+  
+  # service vpp start 
\ No newline at end of file
diff --git a/docs/reference/vppvagrant/Vagrantfile b/docs/reference/vppvagrant/Vagrantfile
new file mode 100644
index 00000000000..32a13adedd8
--- /dev/null
+++ b/docs/reference/vppvagrant/Vagrantfile
@@ -0,0 +1,115 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+Vagrant.configure(2) do |config|
+
+  # Pick the right distro and bootstrap, default is ubuntu1604
+  distro = ( ENV['VPP_VAGRANT_DISTRO'] || "ubuntu1604")
+  if distro == 'centos7'
+    config.vm.box = "centos/7"
+    config.vm.box_version = "1708.01"
+    config.ssh.insert_key = false
+  elsif distro == 'opensuse'
+    config.vm.box = "opensuse/openSUSE-42.3-x86_64"
+    config.vm.box_version = "1.0.4.20170726"
+  else
+    config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
+  end
+  config.vm.box_check_update = false
+
+  config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"update.sh")
+  config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"build.sh"), :args => "/vpp vagrant"
+
+  post_build = ( ENV['VPP_VAGRANT_POST_BUILD'] )
+  if post_build == "test"
+    config.vm.provision "shell", inline: "echo Testing VPP; cd /vpp; make test"
+  elsif post_build == "install"
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"install.sh"), :args => "/vpp"
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"clearinterfaces.sh")
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"run.sh")
+  end
+
+  # Add .gnupg dir in so folks can sign patches
+  # Note, as gnupg puts socket files in that dir, we have
+  # to be cautious and make sure we are dealing with a plain file
+  homedir = File.expand_path("~/")
+  Dir["#{homedir}/.gnupg/**/*"].each do |fname|
+    if File.file?(fname)
+      destname = fname.sub(Regexp.escape("#{homedir}/"),'')
+      config.vm.provision "file", source: fname, destination: destname
+    end
+  end
+
+  # Copy in the .gitconfig if it exists
+  if File.file?(File.expand_path("~/.gitconfig"))
+    config.vm.provision  "file", source: "~/.gitconfig", destination: ".gitconfig"
+  end
+
+  # vagrant-cachier caches apt/yum etc to speed subsequent
+  # vagrant up
+  # to enable, run
+  # vagrant plugin install vagrant-cachier
+  #
+  if Vagrant.has_plugin?("vagrant-cachier")
+    config.cache.scope = :box
+  end
+
+  # Define some physical ports for your VMs to be used by DPDK
+  nics = (ENV['VPP_VAGRANT_NICS'] || "2").to_i(10)
+  for i in 1..nics
+    config.vm.network "private_network", type: "dhcp"
+  end
+
+  # use http proxy if avaiable
+  if ENV['http_proxy'] && Vagrant.has_plugin?("vagrant-proxyconf")
+   config.proxy.http     = ENV['http_proxy']
+   config.proxy.https    = ENV['https_proxy']
+   config.proxy.no_proxy = "localhost,127.0.0.1"
+  end
+
+  vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
+  vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
+
+  config.ssh.forward_agent = true
+  config.ssh.forward_x11 = true
+
+  config.vm.provider "virtualbox" do |vb|
+      vb.customize ["modifyvm", :id, "--ioapic", "on"]
+      vb.memory = "#{vmram}"
+      vb.cpus = "#{vmcpu}"
+
+      # rsync the vpp directory if provision hasn't happened yet
+      unless File.exist? (".vagrant/machines/default/virtualbox/action_provision")
+        config.vm.synced_folder "../../", "/vpp", type: "rsync",
+         rsync__auto: false,
+         rsync__exclude: [
+          "build-root/build*/",
+          "build-root/install*/",
+          "build-root/images*/",
+          "build-root/*.deb",
+          "build-root/*.rpm",
+          "build-root/*.changes",
+          "build-root/python",
+          "build-root/deb/debian/*.dkms",
+          "build-root/deb/debian/*.install",
+          "build-root/deb/debian/changes",
+          "build-root/tools"]
+      end
+
+      #support for the SSE4.x instruction is required in some versions of VB.
+      vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.1", "1"]
+      vb.customize ["setextradata", :id, "VBoxInternal/CPUM/SSE4.2", "1"]
+  end
+  config.vm.provider "vmware_fusion" do |fusion,override|
+    fusion.vmx["memsize"] = "#{vmram}"
+    fusion.vmx["numvcpus"] = "#{vmcpu}"
+  end
+  config.vm.provider "libvirt" do |lv|
+    lv.memory = "#{vmram}"
+    lv.cpus = "#{vmcpu}"
+  end
+  config.vm.provider "vmware_workstation" do |vws,override|
+    vws.vmx["memsize"] = "#{vmram}"
+    vws.vmx["numvcpus"] = "#{vmcpu}"
+  end
+end
\ No newline at end of file
diff --git a/docs/reference/vppvagrant/boxSetup.rst b/docs/reference/vppvagrant/boxSetup.rst
new file mode 100644
index 00000000000..d23033da856
--- /dev/null
+++ b/docs/reference/vppvagrant/boxSetup.rst
@@ -0,0 +1,125 @@
+.. _boxSetup:
+
+.. toctree::
+
+
+Vagrantfiles
+============
+
+A `Vagrantfile <https://www.vagrantup.com/docs/vagrantfile/>`_ contains the box and provision configuration settings for your VM. The syntax of Vagrantfiles is Ruby (Ruby experience is not necessary).
+
+The command **vagrant up** creates a *Vagrant Box* based on your Vagrantfile. A Vagrant box is one of the motivations for using Vagrant - its a "development-ready box" that can be copied to other machines to recreate the same environment. 
+
+It's common for people to think that a Vagrant box *is* the VM. But rather, the VM is *inside* a Vagrant box, with the box containing additional configuration options you can set, such as VM options, scripts to run on boot, etc.
+
+This `Vagrant website for boxes <https://app.vagrantup.com/boxes/search>`_  shows you how to configure a basic Vagrantfile for your specific OS and VM software.
+
+
+Box configuration 
+_________________
+
+
+Looking at the :ref:`vppVagrantfile`, we can see that the default OS is Ubuntu 16.04 (since the variable *distro* equals *ubuntu1604* if there is no VPP_VAGRANT_DISTRO variable set - thus the **else** case is executed.)
+
+.. code-block:: ruby
+
+    # -*- mode: ruby -*-
+    # vi: set ft=ruby :
+
+    Vagrant.configure(2) do |config|
+
+      # Pick the right distro and bootstrap, default is ubuntu1604
+      distro = ( ENV['VPP_VAGRANT_DISTRO'] || "ubuntu1604")
+      if distro == 'centos7'
+        config.vm.box = "centos/7"
+        config.vm.box_version = "1708.01"
+        config.ssh.insert_key = false
+      elsif distro == 'opensuse'
+        config.vm.box = "opensuse/openSUSE-42.3-x86_64"
+        config.vm.box_version = "1.0.4.20170726"
+      else
+        config.vm.box = "puppetlabs/ubuntu-16.04-64-nocm"
+
+As mentioned in the previous page, you can specify which OS and VM provider you want for your Vagrant box from the `Vagrant boxes page <https://app.vagrantup.com/boxes/search>`_, and setting your ENV variable appropriately in *env.sh*.
+
+Next in the Vagrantfile, you see some *config.vm.provision* commands. As paraphrased from `Basic usage of Provisioners <https://www.vagrantup.com/docs/provisioning/basic_usage.html>`_, by default these are only run *once* - during the first boot of the box.
+
+.. code-block:: ruby
+
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"update.sh")
+    config.vm.provision :shell, :path => File.join(File.dirname(__FILE__),"build.sh"), :args => "/vpp vagrant"
+
+The two lines above set the VM to run two scripts during its first bootup: an update script *update.sh* that does basic updating and installation of some useful tools, as well as *build.sh* that builds (but does **not** install) VPP in the VM. You can view these scripts on your own for more detail on the commands used.
+
+
+Looking further in the :ref:`vppVagrantfile`, you can see more Ruby variables being set to ENV's or to a default value:
+
+.. code-block:: ruby
+
+    # Define some physical ports for your VMs to be used by DPDK
+    nics = (ENV['VPP_VAGRANT_NICS'] || "2").to_i(10)
+    for i in 1..nics
+      config.vm.network "private_network", type: "dhcp"
+    end
+
+    # use http proxy if avaiable
+    if ENV['http_proxy'] && Vagrant.has_plugin?("vagrant-proxyconf")
+     config.proxy.http     = ENV['http_proxy']
+     config.proxy.https    = ENV['https_proxy']
+     config.proxy.no_proxy = "localhost,127.0.0.1"
+    end
+
+    vmcpu=(ENV['VPP_VAGRANT_VMCPU'] || 2)
+    vmram=(ENV['VPP_VAGRANT_VMRAM'] || 4096)
+
+
+You can see how the box or VM is configured, such as the amount of NICs (defaults to 3 NICs: 1 x NAT - host access and 2 x VPP DPDK enabled), CPUs (defaults to 2), and RAM (defaults to 4096 MB).
+
+
+Box bootup
+__________
+
+
+Once you're satisfied with your *Vagrantfile*, boot the box with:
+
+.. code-block:: console
+
+    $ vagrant up
+
+Doing this above command will take quite some time, since you are installing a VM and building VPP. Take a break and get some scooby snacks while you wait.
+
+To confirm it is up, show the status and information of Vagrant boxes with: 
+
+.. code-block:: console
+
+  $ vagrant global-status
+  id       name    provider   state    directory                                           
+  -----------------------------------------------------------------------------------------
+  d90a17b  default virtualbox poweroff /home/centos/andrew-vpp/vppsb/vpp-userdemo          
+  77b085e  default virtualbox poweroff /home/centos/andrew-vpp/vppsb2/vpp-userdemo         
+  c1c8952  default virtualbox poweroff /home/centos/andrew-vpp/testingVPPSB/extras/vagrant 
+  c199140  default virtualbox running  /home/centos/andrew-vpp/vppsb3/vpp-userdemo 
+
+  You will have only one machine running, but I have multiple as shown above.
+
+.. note::
+
+  To poweroff your VM, type:
+
+  .. code-block:: console
+
+     $ vagrant halt <id>
+
+  To resume your VM, type:
+
+  .. code-block:: console
+
+     $ vagrant resume <id>
+     
+  To destroy your VM, type:
+
+  .. code-block:: console
+
+     $ vagrant destroy <id>
+
+  Note that "destroying" a VM does not erase the box, but rather destroys all resources allocated for that VM. For other Vagrant commands, such as destroying a box, refer to the `Vagrant CLI Page <https://www.vagrantup.com/docs/cli/>`_.
\ No newline at end of file
diff --git a/docs/reference/vppvagrant/index.rst b/docs/reference/vppvagrant/index.rst
new file mode 100644
index 00000000000..7852cb88514
--- /dev/null
+++ b/docs/reference/vppvagrant/index.rst
@@ -0,0 +1,17 @@
+.. _vppcontainers:
+
+VM's with Vagrant
+=================
+
+This reference guide will cover using Vagrant to boot a VM (virtual machine).
+
+.. toctree::
+
+    vagrantOverview
+    installingVboxVagrant
+    settingENV
+    boxSetup
+    VagrantVMSetup
+    vppVagrantfile
+
+
diff --git a/docs/reference/vppvagrant/installingVboxVagrant.rst b/docs/reference/vppvagrant/installingVboxVagrant.rst
new file mode 100644
index 00000000000..1bd4ba076d7
--- /dev/null
+++ b/docs/reference/vppvagrant/installingVboxVagrant.rst
@@ -0,0 +1,38 @@
+.. _installingVboxVagrant:
+
+.. toctree::
+
+Installing Vbox and Vagrant
+===========================
+
+Installing VirtualBox
+_____________________
+
+First download VirtualBox, which is virtualization software for creating VM's.
+
+If you're on CentOS, follow the `steps here <https://wiki.centos.org/HowTos/Virtualization/VirtualBox>`_.
+
+
+If you're on Ubuntu, perform:
+
+.. code-block:: console
+
+   $ sudo apt-get install virtualbox 
+
+Installing Vagrant
+__________________
+
+Here we are on a 64-bit version of CentOS, downloading and installing Vagrant 2.1.2:
+
+.. code-block:: console
+
+   $ yum -y install https://releases.hashicorp.com/vagrant/2.1.2/vagrant_2.1.2_x86_64.rpm
+
+This is a similar command, but on a 64-bit version of Debian:
+
+.. code-block:: console
+
+   $ sudo apt-get install https://releases.hashicorp.com/vagrant/2.1.2/vagrant_2.1.2_x86_64.deb
+
+
+If you want to download a newer version of Vagrant or one specific to your OS and architecture, go to the Vagrant `download page <https://www.vagrantup.com/downloads.html>`_, right-click and copy the link address for your specified version, and replace the above install command for your respective OS and architechure.
\ No newline at end of file
diff --git a/docs/reference/vppvagrant/settingENV.rst b/docs/reference/vppvagrant/settingENV.rst
new file mode 100644
index 00000000000..269b36bda84
--- /dev/null
+++ b/docs/reference/vppvagrant/settingENV.rst
@@ -0,0 +1,29 @@
+.. _settingENV:
+
+.. toctree::
+
+
+Setting your ENV Variables
+==========================
+
+
+The :ref:`vppVagrantfile` used in the VPP repo sets the configuration options based on your ENV (environment) variables, or to default the configuration at specified values if your ENV variables are not initialized (if you did not run the *env.sh* script found below). 
+
+This is the *env.sh* script found in *vpp/extras/vagrant*. When run, the script sets ENV variables using the **export** command.
+
+.. code-block:: bash
+
+    export VPP_VAGRANT_DISTRO="ubuntu1604"
+    export VPP_VAGRANT_NICS=2
+    export VPP_VAGRANT_VMCPU=4
+    export VPP_VAGRANT_VMRAM=4096 
+
+In the :ref:`vppVagrantfile`, you can see these same ENV variables used (discussed on the next page).
+
+Adding your own ENV variables is easy. For example, if you wanted to setup proxies for your VM, you would add to this file the **export** commands found in the :ref:`building VPP commands section <building>`. Note that this only works if the ENV variable is defined in the :ref:`vppVagrantfile`.
+
+Once you're finished with *env.sh* script, and you are in the directory containing *env.sh*, run the script to set the ENV variables with:
+
+.. code-block:: console
+   
+   $ source ./env.sh
diff --git a/docs/reference/vppvagrant/vagrantOverview.rst b/docs/reference/vppvagrant/vagrantOverview.rst
new file mode 100644
index 00000000000..882b8a68cfd
--- /dev/null
+++ b/docs/reference/vppvagrant/vagrantOverview.rst
@@ -0,0 +1,25 @@
+.. _vagrantOverview:
+
+.. toctree::
+
+Overview
+^^^^^^^^
+
+This guide shows how the VPP :ref:`vppVagrantfile` interacts with shell scripts to configure a `Vagrant box <https://www.vagrantup.com/docs/boxes.html>`_ that boots a VM with VPP. 
+
+.. _prereqlabel:
+
+Prerequisites
+_____________
+
+You have the `FD.io VPP repo <https://github.com/FDio/vpp>`_ cloned locally on your machine. 
+
+
+This guide will refer to the following files from that repo: *Vagrantfile, build.sh, env.sh, and update.sh*.
+
+
+
+
+
+
+
diff --git a/docs/reference/vppvagrant/vppVagrantfile.rst b/docs/reference/vppvagrant/vppVagrantfile.rst
new file mode 100644
index 00000000000..d3c705542bd
--- /dev/null
+++ b/docs/reference/vppvagrant/vppVagrantfile.rst
@@ -0,0 +1,14 @@
+.. _vppVagrantfile:
+
+Vagrant File
+============
+
+This is the Vagrantfile provided in the `Git VPP repo <https://github.com/FDio/vpp/blob/master/extras/vagrant/Vagrantfile>`_.
+
+.. literalinclude:: Vagrantfile
+   :language: Ruby
+   :emphasize-lines: 4-17, 20-21, 57-71
+
+
+
+.. toctree::