From 8609f8a8034a60cc9b49b3723ff81ba7f19ea5e0 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 21 Feb 2019 11:35:05 +0000 Subject: [PATCH] docs: Use sphinx.ext.autodoc for VIF types This lets us keep all our docs in code where we can see them. Change-Id: Ibac3e94aa3d5018afbc331982e245951dc0ccd4b --- doc/source/reference/glossary.rst | 16 +++-- doc/source/user/plugins/linux-bridge.rst | 4 +- doc/source/user/plugins/noop.rst | 4 +- doc/source/user/plugins/ovs.rst | 20 ++---- doc/source/user/vif-types.rst | 82 ++++-------------------- os_vif/objects/vif.py | 51 +++++++++++---- 6 files changed, 70 insertions(+), 107 deletions(-) diff --git a/doc/source/reference/glossary.rst b/doc/source/reference/glossary.rst index 749098a0..da1af644 100644 --- a/doc/source/reference/glossary.rst +++ b/doc/source/reference/glossary.rst @@ -85,15 +85,21 @@ Glossary vhost - An alternative to :term:`virtio` that allows a userspace process to share - *virtqueues* directly with the kernel, preventing the QEMU process from - becoming a bottleneck. + An alternative to :term:`virtio` that allows userspace guest processes to + share *virtqueues* directly with the kernel (or, more specifically, a + kernel module) preventing the QEMU process from becoming a bottleneck. vhost-user A variation of :term:`vhost` that operates entirely in userspace. This - allows processes operating in userspace, such as virtual switches, to - avoid the kernel entirely and maximize performance. + allows userspace guest processes to share *virtqueues* with other processes + operating in userspace, such as virtual switches, avoiding the kernel + entirely and maximize performance. + + When used, a guest exposes a UNIX socket for its control plane, allowing + the external userspace service to provide the backend data plane via a + mapped memory region. This process must implement the corresponding virtio + vhost protocol, such as :term:`virtio-net` for networking, on this socket. Refer to the `QEMU documentation`__ for more information. diff --git a/doc/source/user/plugins/linux-bridge.rst b/doc/source/user/plugins/linux-bridge.rst index 01f29d13..d812a19d 100644 --- a/doc/source/user/plugins/linux-bridge.rst +++ b/doc/source/user/plugins/linux-bridge.rst @@ -11,11 +11,9 @@ Supported VIF Types The Linux Bridge plugin provides support for the following VIF types: -``VIFBridge`` +:mod:`~os_vif.objects.VIFBridge` Configuration where a guest is connected to a Linux bridge via a TAP device. This is the only supported configuration for this plugin. - Refer to :ref:`vif-bridge` for more information. - For information on the VIF type objects, refer to :doc:`/user/vif-types`. Note that only the above VIF types are supported by this plugin. diff --git a/doc/source/user/plugins/noop.rst b/doc/source/user/plugins/noop.rst index bc224c5c..39ddc160 100644 --- a/doc/source/user/plugins/noop.rst +++ b/doc/source/user/plugins/noop.rst @@ -12,11 +12,9 @@ Supported VIF Types The no-op plugin provides support for the following VIF types: -``VIFVHostUser`` +:mod:`~os_vif.objects.VIFVHostUser` Configuration where a guest exposes a UNIX socket for its control plane. This configuration is used with a userspace dataplane such as VPP or Snabb switch. - Refer to :ref:`vif-vhostuser` for more information. - For information on the VIF type objects, refer to :doc:`/user/vif-types`. Note that only the above VIF types are supported by this plugin. diff --git a/doc/source/user/plugins/ovs.rst b/doc/source/user/plugins/ovs.rst index 59ff4fdd..be2c029e 100644 --- a/doc/source/user/plugins/ovs.rst +++ b/doc/source/user/plugins/ovs.rst @@ -11,28 +11,24 @@ Supported VIF Types The Open vSwitch plugin provides support for the following VIF types: -``VIFOpenVSwitch`` +:mod:`~os_vif.objects.VIFOpenVSwitch` Configuration where a guest is directly connected an Open vSwitch bridge. - Refer to :ref:`vif-openvswitch` for more information. - -``VIFBridge`` +:mod:`~os_vif.objects.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`` +:mod:`~os_vif.objects.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. + __ http://docs.openvswitch.org/en/latest/howto/dpdk/ -``VIFHostDevice`` +:mod:`~os_vif.objects.VIFHostDevice` Configuration where an :term:`SR-IOV` PCI device :term:`VF` is passed through to a guest. The ``hw-tc-offload`` feature should be enabled on the SR-IOV - :term:`PF` using ``ethtool``: + :term:`PF` using :command:`ethtool`: .. code-block:: shell @@ -48,11 +44,7 @@ The Open vSwitch plugin provides support for the following VIF types: 2.8. These add support for :term:`tc`-based hardware offloads for SR-IOV VFs and offloading of OVS datapath rules using tc, respectively. - Refer to :ref:`vif-hostdevice` for more information. - .. versionadded:: 1.5.0 For information on the VIF type objects, refer to :doc:`/user/vif-types`. Note that only the above VIF types are supported by this plugin. - -__ http://docs.openvswitch.org/en/latest/howto/dpdk/ diff --git a/doc/source/user/vif-types.rst b/doc/source/user/vif-types.rst index d8e9ffab..c693d589 100644 --- a/doc/source/user/vif-types.rst +++ b/doc/source/user/vif-types.rst @@ -2,90 +2,36 @@ VIF Types ========= -In os-vif, a VIF type refers to a particular approach for configuring the +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. + +.. py:module:: os_vif.objects.vif + 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, +subclassing :class:`VIFBase`. -.. _vif-generic: +.. autoclass:: VIFBase -VIFGeneric ----------- +.. autoclass:: 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. +.. autoclass:: VIFBridge -.. _vif-bridge: +.. autoclass:: VIFOpenVSwitch -VIFBridge ---------- +.. autoclass:: VIFDirect -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. +.. autoclass:: VIFVHostUser -.. _vif-openvswitch: +.. autoclass:: VIFDirect -VIFOpenVSwitch --------------- +.. autoclass:: VIFNestedDPDK -This class provides a configuration where the guest is connected to an Open -vSwitch port. - -.. _vif-direct: - -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, :term:`VEPA` (either :term:`802.1Qbg` or :term:`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. - -.. _vif-vhostuser: - -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 :term:`virtio-net` vhost protocol on this socket -in whatever means is most suitable. - -.. _vif-hostdevice: - -VIFHostDevice -------------- - -This class provides a way to pass a physical device to the guest. Either an -entire physical device, or an SR-IOV PCI device virtual function, are -permitted. - -.. _vif-nesteddpdk: - -VIFNestedDPDK -------------- - -This class provides a configuration, where kuryr-kuberentes is used to provide -accelerated DPDK datapath for nested Kubernetes pods running inside the VM. -Port is first attached to the virtual machine, bound to the userspace driver -(e.g. uio_pci_generic, igb_uio or vfio-pci) and then consumed by Kubernetes -pod via kuryr-kubernetes CNI plugin. VIF port profile objects ======================== diff --git a/os_vif/objects/vif.py b/os_vif/objects/vif.py index b39c9315..0aa8c2b1 100644 --- a/os_vif/objects/vif.py +++ b/os_vif/objects/vif.py @@ -22,7 +22,12 @@ from os_vif.objects import fields as osv_fields @base.VersionedObjectRegistry.register class VIFBase(osv_base.VersionedObject, base.ComparableVersionedObject): - """Represents a virtual network interface.""" + """Represents a virtual network interface. + + The base VIF defines fields that are common to all types of VIF and + provides an association to the network the VIF is plugged into. It should + not be instantiated itself - use a subclass instead. + """ # Version 1.0: Initial release VERSION = '1.0' @@ -60,7 +65,8 @@ class VIFGeneric(VIFBase): """A generic-style VIF. Generic-style VIFs are unbound, floating TUN/TAP devices that should be - setup by the plugin, not the hypervisor. + setup by the plugin, not the hypervisor. The way the TAP device is + connected to the host network stack is explicitly left undefined. For libvirt drivers, this maps to type="ethernet" which just implies a bare TAP device with all setup delegated to the plugin. @@ -79,8 +85,9 @@ class VIFGeneric(VIFBase): class VIFBridge(VIFBase): """A bridge-style VIF. - Bridge-style VIFs are bound to a linux bridge by the hypervisor. Other - devices may be bound to the same L2 virtual bridge. + Bridge-style VIFs are bound to a Linux host bridge by the hypervisor. This + provides Ethernet layer bridging, typically to the LAN. Other devices may + be bound to the same L2 virtual bridge. For libvirt drivers, this maps to type='bridge'. """ @@ -130,6 +137,15 @@ class VIFDirect(VIFBase): :class:`~os_vif.objects.vif.VIFHostDevice`, which allows the guest to directly connect to the VF. + The connection to the device may operate in one of a number of different + modes, :term:`VEPA` (either :term:`802.1Qbg` or :term:`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, :class:`~os_vif.objects.vif.VIFHostDevice` should be used + instead. + For libvirt drivers, this maps to type='direct' """ @@ -155,11 +171,11 @@ class VIFDirect(VIFBase): class VIFVHostUser(VIFBase): """A vhostuser-style VIF. - vhostuser-style VIFs utilize a userspace vhost backend, which allows - traffic to traverse between the guest and a host userspace application - (commonly a virtual switch), bypassing the kernel network stack. Contrast - this with :class:`~os_vif.objects.vif.VIFBridge`, where all packets must be - handled by the hypervisor. + vhostuser-style VIFs utilize a :term:`userspace vhost ` + backend, which allows traffic to traverse between the guest and a host + userspace application (commonly a virtual switch), bypassing the kernel + network stack. Contrast this with :class:`~os_vif.objects.vif.VIFBridge`, + where all packets must be handled by the hypervisor. For libvirt drivers, this maps to type='vhostuser' """ @@ -190,9 +206,10 @@ class VIFVHostUser(VIFBase): class VIFHostDevice(VIFBase): """A hostdev-style VIF. - Hostdev-style VIFs provide a guest with direct access to an SR-IOV Virtual - Function (VF). Contrast this with :class:`~ovs_vif.objects.vif.VIFDirect`, - which includes a software layer between the VF and the guest. + Hostdev-style VIFs provide a guest with direct access to an :term:`SR-IOV` + :term:`Virtual Function` (VF) or an entire :term:`Physical Function` (PF). + Contrast this with :class:`~ovs_vif.objects.vif.VIFDirect`, which includes + a software layer between the interface and the guest. For libvirt drivers, this maps to type='hostdev' """ @@ -216,9 +233,15 @@ class VIFHostDevice(VIFBase): @base.VersionedObjectRegistry.register class VIFNestedDPDK(VIFBase): - """TODO. + """A nested DPDK-style VIF. - For kuryr-kubernetes nested DPDK interfaces. + Nested DPDK-style VIFs are used by Kuryr-Kubernetes to provide accelerated + DPDK datapath for nested Kubernetes pods running inside the VM. The port + is first attached to the virtual machine, bound to the userspace driver + (e.g. ``uio_pci_generic``, ``igb_uio`` or ``vfio-pci``) and then consumed + by Kubernetes pod via the kuryr-kubernetes CNI plugin. + + This does not apply to libvirt drivers. """ # Version 1.0: Initial release