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 used user should be either turn off ENAv2 (to avoid performance
 162    impact) or recompile vfio-pci driver with patch provided in
 163    `amzn-github <https://github.com/amzn/amzn-drivers/tree/master/userspace/dpdk/enav2-vfio-patch>`_.
 164
 165 #. Insert ``vfio-pci`` or ``igb_uio`` kernel module using the command
 166    ``modprobe vfio-pci`` or ``modprobe uio; insmod igb_uio.ko wc_activate=1``
 167    respectively.
 168
 169 #. For ``vfio-pci`` users only:
 170    Please make sure that ``IOMMU`` is enabled in your system,
 171    or use ``vfio`` driver in ``noiommu`` mode::
 172
 173      echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
 174
 175    To use ``noiommu`` mode, the ``vfio-pci`` must be built with flag
 176    ``CONFIG_VFIO_NOIOMMU``.
 177
 178 #. Bind the intended ENA device to ``vfio-pci`` or ``igb_uio`` module.
 179
 180 At this point the system should be ready to run DPDK applications. Once the
 181 application runs to completion, the ENA can be detached from attached module if
 182 necessary.
 183
 184 **Rx interrupts support**
 185
 186 ENA PMD supports Rx interrupts, which can be used to wake up lcores waiting for
 187 input. Please note that it won't work with ``igb_uio``, so to use this feature,
 188 the ``vfio-pci`` should be used.
 189
 190 ENA handles admin interrupts and AENQ notifications on separate interrupt.
 191 There is possibility that there won't be enough event file descriptors to
 192 handle both admin and Rx interrupts. In that situation the Rx interrupt request
 193 will fail.
 194
 195 **Note about usage on \*.metal instances**
 196
 197 On AWS, the metal instances are supporting IOMMU for both arm64 and x86_64
 198 hosts.
 199
 200 * x86_64 (e.g. c5.metal, i3.metal):
 201    IOMMU should be disabled by default. In that situation, the ``igb_uio`` can
 202    be used as it is but ``vfio-pci`` should be working in no-IOMMU mode (please
 203    see above).
 204
 205    When IOMMU is enabled, ``igb_uio`` cannot be used as it's not supporting this
 206    feature, while ``vfio-pci`` should work without any changes.
 207    To enable IOMMU on those hosts, please update ``GRUB_CMDLINE_LINUX`` in file
 208    ``/etc/default/grub`` with the below extra boot arguments::
 209
 210     iommu=1 intel_iommu=on
 211
 212    Then, make the changes live by executing as a root::
 213
 214     # grub2-mkconfig > /boot/grub2/grub.cfg
 215
 216    Finally, reboot should result in IOMMU being enabled.
 217
 218 * arm64 (a1.metal):
 219    IOMMU should be enabled by default. Unfortunately, ``vfio-pci`` isn't
 220    supporting SMMU, which is implementation of IOMMU for arm64 architecture and
 221    ``igb_uio`` isn't supporting IOMMU at all, so to use DPDK with ENA on those
 222    hosts, one must disable IOMMU. This can be done by updating
 223    ``GRUB_CMDLINE_LINUX`` in file ``/etc/default/grub`` with the extra boot
 224    argument::
 225
 226     iommu.passthrough=1
 227
 228    Then, make the changes live by executing as a root::
 229
 230     # grub2-mkconfig > /boot/grub2/grub.cfg
 231
 232    Finally, reboot should result in IOMMU being disabled.
 233    Without IOMMU, ``igb_uio`` can be used as it is but ``vfio-pci`` should be
 234    working in no-IOMMU mode (please see above).
 235
 236 Usage example
 237 -------------
 238
 239 Follow instructions available in the document
 240 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to launch
 241 **testpmd** with Amazon ENA devices managed by librte_net_ena.
 242
 243 Example output:
 244
 245 .. code-block:: console
 246
 247    [...]
 248    EAL: PCI device 0000:00:06.0 on NUMA socket -1
 249    EAL:   Invalid NUMA socket, default to 0
 250    EAL:   probe driver: 1d0f:ec20 net_ena
 251
 252    Interactive-mode selected
 253    testpmd: create a new mbuf pool <mbuf_pool_socket_0>: n=171456, size=2176, socket=0
 254    testpmd: preferred mempool ops selected: ring_mp_mc
 255    Warning! port-topology=paired and odd forward ports number, the last port will pair with itself.
 256    Configuring Port 0 (socket 0)
 257    Port 0: 00:00:00:11:00:01
 258    Checking link statuses...
 259
 260    Done
 261    testpmd>