+IOVA Mode Detection
+~~~~~~~~~~~~~~~~~~~
+
+IOVA Mode is selected by considering what the current usable Devices on the
+system require and/or support.
+
+On FreeBSD, RTE_IOVA_PA is always the default. On Linux, the IOVA mode is
+detected based on a 2-step heuristic detailed below.
+
+For the first step, EAL asks each bus its requirement in terms of IOVA mode
+and decides on a preferred IOVA mode.
+
+- if all buses report RTE_IOVA_PA, then the preferred IOVA mode is RTE_IOVA_PA,
+- if all buses report RTE_IOVA_VA, then the preferred IOVA mode is RTE_IOVA_VA,
+- if all buses report RTE_IOVA_DC, no bus expressed a preferrence, then the
+ preferred mode is RTE_IOVA_DC,
+- if the buses disagree (at least one wants RTE_IOVA_PA and at least one wants
+ RTE_IOVA_VA), then the preferred IOVA mode is RTE_IOVA_DC (see below with the
+ check on Physical Addresses availability),
+
+If the buses have expressed no preference on which IOVA mode to pick, then a
+default is selected using the following logic:
+
+- if physical addresses are not available, RTE_IOVA_VA mode is used
+- if /sys/kernel/iommu_groups is not empty, RTE_IOVA_VA mode is used
+- otherwise, RTE_IOVA_PA mode is used
+
+In the case when the buses had disagreed on their preferred IOVA mode, part of
+the buses won't work because of this decision.
+
+The second step checks if the preferred mode complies with the Physical
+Addresses availability since those are only available to root user in recent
+kernels. Namely, if the preferred mode is RTE_IOVA_PA but there is no access to
+Physical Addresses, then EAL init fails early, since later probing of the
+devices would fail anyway.
+
+.. note::
+
+ The RTE_IOVA_VA mode is preferred as the default in most cases for the
+ following reasons:
+
+ - All drivers are expected to work in RTE_IOVA_VA mode, irrespective of
+ physical address availability.
+ - By default, the mempool, first asks for IOVA-contiguous memory using
+ ``RTE_MEMZONE_IOVA_CONTIG``. This is slow in RTE_IOVA_PA mode and it may
+ affect the application boot time.
+ - It is easy to enable large amount of IOVA-contiguous memory use-cases
+ with IOVA in VA mode.
+
+ It is expected that all PCI drivers work in both RTE_IOVA_PA and
+ RTE_IOVA_VA modes.
+
+ If a PCI driver does not support RTE_IOVA_PA mode, the
+ ``RTE_PCI_DRV_NEED_IOVA_AS_VA`` flag is used to dictate that this PCI
+ driver can only work in RTE_IOVA_VA mode.
+
+ When the KNI kernel module is detected, RTE_IOVA_PA mode is preferred as a
+ performance penalty is expected in RTE_IOVA_VA mode.
+