From 687785cb0e803b63efeb1a737c359700f0dbc6e6 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Mon, 3 Apr 2017 10:37:22 +0100 Subject: [PATCH] doc: Rewrap 'vif_types' document This makes reading the source a lot easier. A small number of `code` symbols are formatted as such. Change-Id: Id9f223f0b424094e9f99d610b5f7b7731259d145 --- doc/source/vif_types.rst | 116 ++++++++++++++++++--------------------- 1 file changed, 54 insertions(+), 62 deletions(-) diff --git a/doc/source/vif_types.rst b/doc/source/vif_types.rst index 24c7fa81..711368ab 100644 --- a/doc/source/vif_types.rst +++ b/doc/source/vif_types.rst @@ -1,127 +1,119 @@ -=========== - VIF Types -=========== +========= +VIF Types +========= -In os-vif, a VIF type refers to a particular approach for configuring -the backend of a guest virtual network interface. There is a small, -finite set of ways that a VIF backend can be configured for any given -hypervisor and a limited amount of metadata is associated with each -approach. +In os-vif, a VIF type refers to a particular approach for configuring the +backend of a guest virtual network interface. There is a small, finite set of +ways that a VIF backend can be configured for any given hypervisor and a +limited amount of metadata is associated with each approach. VIF objects =========== -Each distinct type of VIF configuration is represented by a versioned -object in 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. +Each distinct type of VIF configuration is represented by a versioned object in +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. VIFGeneric ---------- -This class provides a totally generic type of configuration, where the -guest is 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. +This class provides a totally generic type of configuration, where the guest is +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. VIFBridge --------- -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. +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. VIFOpenVSwitch -------------- -This class provides a configuration where the guest is connected to -an openvswitch port. +This class provides a configuration where the guest is connected to an Open +vSwitch port. VIFDirect --------- -This class provides a configuration where the guest is connected to -a physical network device. The connection to the device may operate -in one of a number of different modes, VEPA (either 802.1qbg -802.1qbh), passthrough (exclusive assignment of the host NIC) or -bridge (ethernet layer bridging of traffic). The passthrough mode -would be used when there is a network device which needs to have -a MAC address or vlan conf. For passthrough of network devices -without MAC/vlan configuration, the VIFHostDevice should be used -instead. +This class provides a configuration where the guest is connected to a physical +network device. The connection to the device may operate in one of a number of +different modes, VEPA (either 802.1qbg 802.1qbh), passthrough (exclusive +assignment of the host NIC) or bridge (ethernet layer bridging of traffic). The +passthrough mode would be used when there is a 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. VIFVHostUser ------------ -This class provides another totally generic type of configuration, -where the guest is exposing a UNIX socket for its control plane, -allowing an external userspace service to provide the backend data -plane via a mapped memory region. The process must implement the -virtio-net vhost protocol on this socket in whatever means is most -suitable. +This class provides another totally generic type of configuration, where the +guest is exposing a UNIX socket for its control plane, allowing an external +userspace service to provide the backend data plane via a mapped memory region. +The process must implement the virtio-net vhost protocol on this socket in +whatever means is most suitable. VIFHostDevice ------------- -This class provides a way to pass a physical device to the guest. -Either an entire physical device, or a SR-IOV PCI device virtual -function, are permitted. +This class provides a way to pass a physical device to the guest. Either an +entire physical device, or a SR-IOV PCI device virtual function, are permitted. VIF port profile objects ======================== -Each VIF instance can optionally be associated with a port profile -object. This provides a set of metadata attributes that serve to -identify the guest virtual interface to the host. Different types -of host connectivity will require different port profile object -metadata. Each port profile type is associated wtih a versioned -object, subclassing VIFPortProfileBase +Each VIF instance can optionally be associated with a port profile object. This +provides a set of metadata attributes that serve to identify the guest virtual +interface to the host. Different types of host connectivity will require +different port profile object metadata. Each port profile type is associated +with a versioned object, subclassing `VIFPortProfileBase`. VIFPortProfileOpenVSwitch ------------------------- -This profile provides the metadata required to associate a VIF -with an openvswitch host port. +This profile provides the metadata required to associate a VIF with an Open +vSwitch host port. VIFPortProfile8021Qbg --------------------- -This profile provides the metadata required to associate a VIF -with a VEPA host device supporting the 801.1Qbg spec. +This profile provides the metadata required to associate a VIF with a VEPA host +device supporting the 801.1Qbg spec. VIFPortProfile8021Qbh --------------------- -This profile provides the metadata required to associate a VIF -with a VEPA host device supporting the 801.1Qbg spec. +This profile provides the metadata required to associate a VIF with a VEPA host +device supporting the 801.1Qbg spec. VIFPortProfileFPOpenVSwitch --------------------------- -This profile provides the metadata required to associate a fast path -vhostuser VIF with an openvswitch port. +This profile provides the metadata required to associate a fast path vhost-user +VIF with an Open vSwitch port. VIFPortProfileFPBridge ---------------------- -This profile provides the metadata required to associate a fast path -vhostuser VIF with a linuxbridge port. +This profile provides the metadata required to associate a fast path vhost-user +VIF with a Linux bridge port. VIFPortProfileFPTap ------------------- -This profile provides the metadata required to associate a fast path -vhostuser VIF with a calico port. +This profile provides the metadata required to associate a fast path vhost-user +VIF with a Calico port. VIF network objects =================== -Each VIF instance is associated with a set of objects which -describe the logical network that the guest will be plugged -into. This information is again represented by a set of -versioned objects +Each VIF instance is associated with a set of objects which describe the +logical network that the guest will be plugged into. This information is again +represented by a set of versioned objects TODO :-(