devtools: add cocci script to rename mbuf offload flags
[dpdk.git] / doc / guides / nics / ena.rst
index bbf27f2..92b1858 100644 (file)
@@ -1,5 +1,5 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright (c) 2015-2019 Amazon.com, Inc. or its affiliates.
+    Copyright (c) 2015-2020 Amazon.com, Inc. or its affiliates.
     All rights reserved.
 
 ENA Poll Mode Driver
@@ -79,21 +79,13 @@ The driver supports multi-queue for both Tx and Rx.
 Configuration information
 -------------------------
 
-**DPDK Configuration Parameters**
+**Runtime Configuration Parameters**
 
-  The following configuration options are available for the ENA PMD:
+   * **large_llq_hdr** (default 0)
 
-   * **CONFIG_RTE_LIBRTE_ENA_PMD** (default y): Enables or disables inclusion
-     of the ENA PMD driver in the DPDK compilation.
-
-   * **CONFIG_RTE_LIBRTE_ENA_DEBUG_RX** (default n): Enables or disables debug
-     logging of RX logic within the ENA PMD driver.
-
-   * **CONFIG_RTE_LIBRTE_ENA_DEBUG_TX** (default n): Enables or disables debug
-     logging of TX logic within the ENA PMD driver.
-
-   * **CONFIG_RTE_LIBRTE_ENA_COM_DEBUG** (default n): Enables or disables debug
-     logging of low level tx/rx logic in ena_com(base) within the ENA PMD driver.
+     Enables or disables usage of large LLQ headers. This option will have
+     effect only if the device also supports large LLQ headers. Otherwise, the
+     default value will be used.
 
 **ENA Configuration Parameters**
 
@@ -126,7 +118,7 @@ Supported ENA adapters
 Current ENA PMD supports the following ENA adapters including:
 
 * ``1d0f:ec20`` - ENA VF
-* ``1d0f:ec21`` - ENA VF with LLQ support
+* ``1d0f:ec21`` - ENA VF RSERV0
 
 Supported Operating Systems
 ---------------------------
@@ -149,6 +141,7 @@ Supported features
 * LSC event notification
 * Watchdog (requires handling of timers in the application)
 * Device reset upon failure
+* Rx interrupts
 
 Prerequisites
 -------------
@@ -161,8 +154,8 @@ Prerequisites
    (*) ENAv2 hardware supports Low Latency Queue v2 (LLQv2). This feature
    reduces the latency of the packets by pushing the header directly through
    the PCI to the device, before the DMA is even triggered. For proper work
-   kernel PCI driver must support write combining (WC). In mainline version of
-   ``igb_uio`` (in DPDK repo) it must be enabled by loading module with
+   kernel PCI driver must support write combining (WC).
+   In DPDK ``igb_uio`` it must be enabled by loading module with
    ``wc_activate=1`` flag (example below). However, mainline's vfio-pci
    driver in kernel doesn't have WC support yet (planed to be added).
    If vfio-pci used user should be either turn off ENAv2 (to avoid performance
@@ -179,18 +172,73 @@ Prerequisites
 
      echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
 
-#. Bind the intended ENA device to ``vfio-pci`` or ``igb_uio`` module.
+   To use ``noiommu`` mode, the ``vfio-pci`` must be built with flag
+   ``CONFIG_VFIO_NOIOMMU``.
 
+#. Bind the intended ENA device to ``vfio-pci`` or ``igb_uio`` module.
 
 At this point the system should be ready to run DPDK applications. Once the
-application runs to completion, the ENA can be detached from igb_uio if necessary.
+application runs to completion, the ENA can be detached from attached module if
+necessary.
+
+**Rx interrupts support**
+
+ENA PMD supports Rx interrupts, which can be used to wake up lcores waiting for
+input. Please note that it won't work with ``igb_uio``, so to use this feature,
+the ``vfio-pci`` should be used.
+
+ENA handles admin interrupts and AENQ notifications on separate interrupt.
+There is possibility that there won't be enough event file descriptors to
+handle both admin and Rx interrupts. In that situation the Rx interrupt request
+will fail.
+
+**Note about usage on \*.metal instances**
+
+On AWS, the metal instances are supporting IOMMU for both arm64 and x86_64
+hosts.
+
+* x86_64 (e.g. c5.metal, i3.metal):
+   IOMMU should be disabled by default. In that situation, the ``igb_uio`` can
+   be used as it is but ``vfio-pci`` should be working in no-IOMMU mode (please
+   see above).
+
+   When IOMMU is enabled, ``igb_uio`` cannot be used as it's not supporting this
+   feature, while ``vfio-pci`` should work without any changes.
+   To enable IOMMU on those hosts, please update ``GRUB_CMDLINE_LINUX`` in file
+   ``/etc/default/grub`` with the below extra boot arguments::
+
+    iommu=1 intel_iommu=on
+
+   Then, make the changes live by executing as a root::
+
+    # grub2-mkconfig > /boot/grub2/grub.cfg
+
+   Finally, reboot should result in IOMMU being enabled.
+
+* arm64 (a1.metal):
+   IOMMU should be enabled by default. Unfortunately, ``vfio-pci`` isn't
+   supporting SMMU, which is implementation of IOMMU for arm64 architecture and
+   ``igb_uio`` isn't supporting IOMMU at all, so to use DPDK with ENA on those
+   hosts, one must disable IOMMU. This can be done by updating
+   ``GRUB_CMDLINE_LINUX`` in file ``/etc/default/grub`` with the extra boot
+   argument::
+
+    iommu.passthrough=1
+
+   Then, make the changes live by executing as a root::
+
+    # grub2-mkconfig > /boot/grub2/grub.cfg
+
+   Finally, reboot should result in IOMMU being disabled.
+   Without IOMMU, ``igb_uio`` can be used as it is but ``vfio-pci`` should be
+   working in no-IOMMU mode (please see above).
 
 Usage example
 -------------
 
 Follow instructions available in the document
 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to launch
-**testpmd** with Amazon ENA devices managed by librte_pmd_ena.
+**testpmd** with Amazon ENA devices managed by librte_net_ena.
 
 Example output:
 
@@ -198,7 +246,7 @@ Example output:
 
    [...]
    EAL: PCI device 0000:00:06.0 on NUMA socket -1
-   EAL:   Invalid NUMA socket, default to 0
+   EAL: Device 0000:00:06.0 is not NUMA-aware, defaulting socket to 0
    EAL:   probe driver: 1d0f:ec20 net_ena
 
    Interactive-mode selected