Document PCI IRQ Affinity Agent creation (pick r6)

This commit includes the creation of a doc about how the agent operates
and how to configure OpenStack to operate properly with it.
Fixed minor editorial issues.

Signed-off-by: Elisamara Aoki Goncalves <elisamaraaoki.goncalves@windriver.com>
Change-Id: Ie118b1b2b7924a7f3a94bec089cd315094ebdef2

doc/source/guest_integration/openstack/index-guest-os-17b56b5745b6.rst

@@ -47,3 +47,12 @@ Use Host's PTP Clock
    :maxdepth: 1
 
    configure-kvm-virtual-ptp-driver
+
+----------------
+PCI IRQ Affinity
+----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   pci-irq-affinity-4fed257d094b

doc/source/guest_integration/openstack/pci-irq-affinity-4fed257d094b.rst

@@ -0,0 +1,57 @@
+.. _pci-irq-affinity-4fed257d094b:
+
+================
+PCI IRQ Affinity
+================
+
+While in OpenStack it is possible to enable instances to use |PCI| devices, the
+interrupts generated by these devices may be handled by host CPUs that are
+unrelated to the instance, and this can lead to noisy neighbor issues and lower
+performance, if the device interrupts were handled by the instance's CPUs.
+
+|PCI| |IRQ| Affinity can only be specified for instances with dedicated vCPUs.
+
+|PCI| |IRQ| Affinity assignments are used to achieve higher performance since
+the instance's core(s) will handle the interrupts from |PCI| devices used
+by these instances. Interrupts are thus prevented from consuming cycles on the
+platform cores.
+
+-----------
+Flavor spec
+-----------
+
+A specific flavor spec for |PCI| interrupt affining is used to determine which
+vCPUs assigned to the instance must handle the interrupts from the |PCI|
+devices:
+
+``hw:pci_irq_affinity_mask=<vcpus_cpulist>``
+
+Where ``vcpus_cpulist`` can assume a comma-separated list of values that
+can be expressed as:
+
+- ``int``: the vCPU expressed by ``int`` will be assigned to handle the
+  interruptions from the |PCI| devices
+- ``int1-int2``: the vCPUs between ``int1`` and ``int2`` (inclusive) will
+  be used to handle the interruptions from the |PCI| devices
+- ``^int``: the vCPU expressed by ``int`` will not be assigned to handle the
+  interruptions from the |PCI| devices and shall be used to exclude a vCPU
+  that was included in a previous range
+
+.. note::
+
+    ``int`` must be a value between ``0`` and ``flavor.vcpus - 1``.
+
+For example: ``hw_pci_irq_affinity_mask=1-4,^3,6`` means that vCPUs with
+indexes ``1,2,4 and 6`` from the vCPU list that Nova allocates to the instance
+will be assigned to handle interruptions from the |PCI| devices.
+
+-----------
+Limitations
+-----------
+
+-   No |PCI| |IRQ| CPU affining is supported for instances using shared CPUs
+    (i.e., when using flavor spec ``hw:cpu_policy=shared``).
+
+-   No |PCI| |IRQ| CPU affining will be performed when invalid ranges are
+    specified in the flavor spec; a log error message will be generated
+    indicating the problem.

doc/source/shared/abbrevs.txt

@@ -60,6 +60,7 @@
 .. |IoT| replace:: :abbr:`IoT (Internet of Things)`
 .. |IPMI| replace:: :abbr:`IPMI (Intelligent Platform Management Interface)`
 .. |IOPS| replace:: :abbr:`IOPS (I/O operations per second)`
+.. |IRQ| replace:: :abbr:`IRQ (Interrupt Request)`
 .. |KVM| replace:: :abbr:`KVM (Kernel-based Virtual Machine)`
 .. |LACP| replace:: :abbr:`LACP (Link Aggregation Control Protocol)`
 .. |LAG| replace:: :abbr:`LAG (Link Aggregation)`