Add documentation for OVS plugin

Change-Id: I741d2f9dae18e0d294f87bea52b5638430eb30ce
Co-Authored-By: Stephen Finucane <sfinucan@redhat.com>

doc/source/index.rst

@@ -1,18 +1,25 @@
-Welcome to os-vif's documentation!
+======
-========================================================
+os-vif
-
+======
-Contents:
 
 .. toctree::
    :maxdepth: 2
 
    vif_types
    host_info
+   plugins/ovs
    glossary
 
-Indices and tables
+`os-vif` is a library for plugging and unplugging virtual interfaces (VIFs) in
-==================
+OpenStack. It provides:
 
-* :ref:`genindex`
+- Versioned objects that represent various types of virtual interfaces and
-* :ref:`search`
+  their components
 
+- Base VIF plugin class that supplies a ``plug()`` and ``unplug()`` interface
+
+- Plugins for two networking backends - Open vSwitch and Linux Bridge
+
+`os-vif` is intended to define a common model for representing VIF types in
+OpenStack. With the exception of the two included plugins, all plugins for
+other networking backends are maintained in separate code repositories.

doc/source/plugins/ovs.rst

@@ -0,0 +1,38 @@
+============
+Open vSwitch
+============
+
+The Open vSwitch plugin, `vif_plug_ovs`, is an `os-vif` VIF plugin for the Open
+vSwitch network backend. It is one of two plugins provided as part of `os-vif`
+itself, the other being `linux-bridge`.
+
+Supported VIF Types
+-------------------
+
+The Open vSwitch plugin provides support for the following VIF types:
+
+`VIFOpenVSwitch`
+
+  Configuration where a guest is directly connected an Open vSwitch bridge.
+
+  Refer to :ref:`vif-openvswitch` for more information.
+
+`VIFBridge`
+
+  Configuration where a guest is connected to a Linux bridge via a TAP device,
+  and that bridge is connected to the Open vSwitch bridge. This allows for the
+  use of ``iptables`` rules for filtering traffic.
+
+  Refer to :ref:`vif-bridge` for more information.
+
+`VIFVHostUser`
+
+  Configuration where a guest exposes a UNIX socket for its control plane. This
+  configuration is used with the `DPDK datapath of Open vSwitch`__.
+
+  Refer to :ref:`vif-vhostuser` for more information.
+
+For information on the VIF type objects, refer to :doc:`../vif_types`. Note
+that only the above VIF types are supported by this plugin.
+
+__ http://docs.openvswitch.org/en/latest/howto/dpdk/

doc/source/vif_types.rst

@@ -15,6 +15,8 @@ os-vif, subclassed from `os_vif.objects.VIFBase`. The `VIFBase` class defines
 some fields that are common to all types of VIF, and provides an association to
 a versioned object describing the network the VIF is plugged into.
 
+.. _vif-generic:
+
 VIFGeneric
 ----------
 
@@ -23,6 +25,8 @@ simply associated with an arbitrary TAP device (or equivalent).  The way the
 TAP device is connected to the host network stack is explicitly left undefined
 and entirely up to the plugin to decide.
 
+.. _vif-bridge:
+
 VIFBridge
 ---------
 
@@ -30,12 +34,16 @@ This class provides a configuration where the guest is connected directly to an
 explicit host bridge device. This provides ethernet layer bridging, typically
 to the LAN.
 
+.. _vif-openvswitch:
+
 VIFOpenVSwitch
 --------------
 
 This class provides a configuration where the guest is connected to an Open
 vSwitch port.
 
+.. _vif-direct:
+
 VIFDirect
 ---------
 
@@ -48,6 +56,8 @@ network device which needs to have a MAC address or VLAN configuration. For
 passthrough of network devices without MAC/VLAN configuration, the
 `VIFHostDevice` should be used instead.
 
+.. _vif-vhostuser:
+
 VIFVHostUser
 ------------
 
@@ -57,6 +67,8 @@ userspace service to provide the backend data plane via a mapped memory region.
 The process must implement the :term:`virtio-net` vhost protocol on this socket
 in whatever means is most suitable.
 
+.. _vif-hostdevice:
+
 VIFHostDevice
 -------------