doc/guides/nics/ena.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright (c) 2015-2020 Amazon.com, Inc. or its affiliates.
   3     All rights reserved.
   4
   5 ENA Poll Mode Driver
   6 ====================
   7
   8 The ENA PMD is a DPDK poll-mode driver for the Amazon Elastic
   9 Network Adapter (ENA) family.
  10
  11 Overview
  12 --------
  13
  14 The ENA driver exposes a lightweight management interface with a
  15 minimal set of memory mapped registers and an extendable command set
  16 through an Admin Queue.
  17
  18 The driver supports a wide range of ENA adapters, is link-speed
  19 independent (i.e., the same driver is used for 10GbE, 25GbE, 40GbE,
  20 etc.), and it negotiates and supports an extendable feature set.
  21
  22 ENA adapters allow high speed and low overhead Ethernet traffic
  23 processing by providing a dedicated Tx/Rx queue pair per CPU core.
  24
  25 The ENA driver supports industry standard TCP/IP offload features such
  26 as checksum offload and TCP transmit segmentation offload (TSO).
  27
  28 Receive-side scaling (RSS) is supported for multi-core scaling.
  29
  30 Some of the ENA devices support a working mode called Low-latency
  31 Queue (LLQ), which saves several more microseconds.
  32
  33 Management Interface
  34 --------------------
  35
  36 ENA management interface is exposed by means of:
  37
  38 * Device Registers
  39 * Admin Queue (AQ) and Admin Completion Queue (ACQ)
  40
  41 ENA device memory-mapped PCIe space for registers (MMIO registers)
  42 are accessed only during driver initialization and are not involved
  43 in further normal device operation.
  44
  45 AQ is used for submitting management commands, and the
  46 results/responses are reported asynchronously through ACQ.
  47
  48 ENA introduces a very small set of management commands with room for
  49 vendor-specific extensions. Most of the management operations are
  50 framed in a generic Get/Set feature command.
  51
  52 The following admin queue commands are supported:
  53
  54 * Create I/O submission queue
  55 * Create I/O completion queue
  56 * Destroy I/O submission queue
  57 * Destroy I/O completion queue
  58 * Get feature
  59 * Set feature
  60 * Get statistics
  61
  62 Refer to ``ena_admin_defs.h`` for the list of supported Get/Set Feature
  63 properties.
  64
  65 Data Path Interface
  66 -------------------
  67
  68 I/O operations are based on Tx and Rx Submission Queues (Tx SQ and Rx
  69 SQ correspondingly). Each SQ has a completion queue (CQ) associated
  70 with it.
  71
  72 The SQs and CQs are implemented as descriptor rings in contiguous
  73 physical memory.
  74
  75 Refer to ``ena_eth_io_defs.h`` for the detailed structure of the descriptor
  76
  77 The driver supports multi-queue for both Tx and Rx.
  78
  79 Configuration information
  80 -------------------------
  81
  82 **Runtime Configuration Parameters**
  83
  84    * **large_llq_hdr** (default 0)
  85
  86      Enables or disables usage of large LLQ headers. This option will have
  87      effect only if the device also supports large LLQ headers. Otherwise, the
  88      default value will be used.
  89
  90 **ENA Configuration Parameters**
  91
  92    * **Number of Queues**
  93
  94      This is the requested number of queues upon initialization, however, the actual
  95      number of receive and transmit queues to be created will be the minimum between
  96      the maximal number supported by the device and number of queues requested.
  97
  98    * **Size of Queues**
  99
 100      This is the requested size of receive/transmit queues, while the actual size
 101      will be the minimum between the requested size and the maximal receive/transmit
 102      supported by the device.
 103
 104 Building DPDK
 105 -------------
 106
 107 See the :ref:`DPDK Getting Started Guide for Linux <linux_gsg>` for
 108 instructions on how to build DPDK.
 109
 110 By default the ENA PMD library will be built into the DPDK library.
 111
 112 For configuring and using UIO and VFIO frameworks, please also refer :ref:`the
 113 documentation that comes with DPDK suite <linux_gsg>`.
 114
 115 Supported ENA adapters
 116 ----------------------
 117
 118 Current ENA PMD supports the following ENA adapters including:
 119
 120 * ``1d0f:ec20`` - ENA VF
 121 * ``1d0f:ec21`` - ENA VF RSERV0
 122
 123 Supported Operating Systems
 124 ---------------------------
 125
 126 Any Linux distribution fulfilling the conditions described in ``System Requirements``
 127 section of :ref:`the DPDK documentation <linux_gsg>` or refer to *DPDK Release Notes*.
 128
 129 Supported features
 130 ------------------
 131
 132 * MTU configuration
 133 * Jumbo frames up to 9K
 134 * IPv4/TCP/UDP checksum offload
 135 * TSO offload
 136 * Multiple receive and transmit queues
 137 * RSS hash
 138 * RSS indirection table configuration
 139 * Low Latency Queue for Tx
 140 * Basic and extended statistics
 141 * LSC event notification
 142 * Watchdog (requires handling of timers in the application)
 143 * Device reset upon failure
 144 * Rx interrupts
 145
 146 Prerequisites
 147 -------------
 148
 149 #. Prepare the system as recommended by DPDK suite.  This includes environment
 150    variables, hugepages configuration, tool-chains and configuration.
 151
 152 #. ENA PMD can operate with ``vfio-pci``(*) or ``igb_uio`` driver.
 153
 154    (*) ENAv2 hardware supports Low Latency Queue v2 (LLQv2). This feature
 155    reduces the latency of the packets by pushing the header directly through
 156    the PCI to the device, before the DMA is even triggered. For proper work
 157    kernel PCI driver must support write combining (WC).
 158    In DPDK ``igb_uio`` it must be enabled by loading module with
 159    ``wc_activate=1`` flag (example below). However, mainline's vfio-pci
 160    driver in kernel doesn't have WC support yet (planed to be added).
 161    If vfio-pci is used user should follow `AWS ENA PMD documentation
 162    <https://github.com/amzn/amzn-drivers/tree/master/userspace/dpdk/README.md>`_.
 163
 164 #. Insert ``vfio-pci`` or ``igb_uio`` kernel module using the command
 165    ``modprobe vfio-pci`` or ``modprobe uio; insmod igb_uio.ko wc_activate=1``
 166    respectively.
 167
 168 #. For ``vfio-pci`` users only:
 169    Please make sure that ``IOMMU`` is enabled in your system,
 170    or use ``vfio`` driver in ``noiommu`` mode::
 171
 172      echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
 173
 174    To use ``noiommu`` mode, the ``vfio-pci`` must be built with flag
 175    ``CONFIG_VFIO_NOIOMMU``.
 176
 177 #. Bind the intended ENA device to ``vfio-pci`` or ``igb_uio`` module.
 178
 179 At this point the system should be ready to run DPDK applications. Once the
 180 application runs to completion, the ENA can be detached from attached module if
 181 necessary.
 182
 183 **Rx interrupts support**
 184
 185 ENA PMD supports Rx interrupts, which can be used to wake up lcores waiting for
 186 input. Please note that it won't work with ``igb_uio``, so to use this feature,
 187 the ``vfio-pci`` should be used.
 188
 189 ENA handles admin interrupts and AENQ notifications on separate interrupt.
 190 There is possibility that there won't be enough event file descriptors to
 191 handle both admin and Rx interrupts. In that situation the Rx interrupt request
 192 will fail.
 193
 194 **Note about usage on \*.metal instances**
 195
 196 On AWS, the metal instances are supporting IOMMU for both arm64 and x86_64
 197 hosts.
 198
 199 * x86_64 (e.g. c5.metal, i3.metal):
 200    IOMMU should be disabled by default. In that situation, the ``igb_uio`` can
 201    be used as it is but ``vfio-pci`` should be working in no-IOMMU mode (please
 202    see above).
 203
 204    When IOMMU is enabled, ``igb_uio`` cannot be used as it's not supporting this
 205    feature, while ``vfio-pci`` should work without any changes.
 206    To enable IOMMU on those hosts, please update ``GRUB_CMDLINE_LINUX`` in file
 207    ``/etc/default/grub`` with the below extra boot arguments::
 208
 209     iommu=1 intel_iommu=on
 210
 211    Then, make the changes live by executing as a root::
 212
 213     # grub2-mkconfig > /boot/grub2/grub.cfg
 214
 215    Finally, reboot should result in IOMMU being enabled.
 216
 217 * arm64 (a1.metal):
 218    IOMMU should be enabled by default. Unfortunately, ``vfio-pci`` isn't
 219    supporting SMMU, which is implementation of IOMMU for arm64 architecture and
 220    ``igb_uio`` isn't supporting IOMMU at all, so to use DPDK with ENA on those
 221    hosts, one must disable IOMMU. This can be done by updating
 222    ``GRUB_CMDLINE_LINUX`` in file ``/etc/default/grub`` with the extra boot
 223    argument::
 224
 225     iommu.passthrough=1
 226
 227    Then, make the changes live by executing as a root::
 228
 229     # grub2-mkconfig > /boot/grub2/grub.cfg
 230
 231    Finally, reboot should result in IOMMU being disabled.
 232    Without IOMMU, ``igb_uio`` can be used as it is but ``vfio-pci`` should be
 233    working in no-IOMMU mode (please see above).
 234
 235 Usage example
 236 -------------
 237
 238 Follow instructions available in the document
 239 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to launch
 240 **testpmd** with Amazon ENA devices managed by librte_net_ena.
 241
 242 Example output:
 243
 244 .. code-block:: console
 245
 246    [...]
 247    EAL: PCI device 0000:00:06.0 on NUMA socket -1
 248    EAL: Device 0000:00:06.0 is not NUMA-aware, defaulting socket to 0
 249    EAL:   probe driver: 1d0f:ec20 net_ena
 250
 251    Interactive-mode selected
 252    testpmd: create a new mbuf pool <mbuf_pool_socket_0>: n=171456, size=2176, socket=0
 253    testpmd: preferred mempool ops selected: ring_mp_mc
 254    Warning! port-topology=paired and odd forward ports number, the last port will pair with itself.
 255    Configuring Port 0 (socket 0)
 256    Port 0: 00:00:00:11:00:01
 257    Checking link statuses...
 258
 259    Done
 260    testpmd>