.. _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.