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 **DPDK Configuration Parameters**
  83
  84   The following configuration options are available for the ENA PMD:
  85
  86    * **CONFIG_RTE_LIBRTE_ENA_PMD** (default y): Enables or disables inclusion
  87      of the ENA PMD driver in the DPDK compilation.
  88
  89    * **CONFIG_RTE_LIBRTE_ENA_DEBUG_RX** (default n): Enables or disables debug
  90      logging of RX logic within the ENA PMD driver.
  91
  92    * **CONFIG_RTE_LIBRTE_ENA_DEBUG_TX** (default n): Enables or disables debug
  93      logging of TX logic within the ENA PMD driver.
  94
  95    * **CONFIG_RTE_LIBRTE_ENA_COM_DEBUG** (default n): Enables or disables debug
  96      logging of low level tx/rx logic in ena_com(base) within the ENA PMD driver.
  97
  98 **Runtime Configuration Parameters**
  99
 100    * **large_llq_hdr** (default 0)
 101
 102      Enables or disables usage of large LLQ headers. This option will have
 103      effect only if the device also supports large LLQ headers. Otherwise, the
 104      default value will be used.
 105
 106 **ENA Configuration Parameters**
 107
 108    * **Number of Queues**
 109
 110      This is the requested number of queues upon initialization, however, the actual
 111      number of receive and transmit queues to be created will be the minimum between
 112      the maximal number supported by the device and number of queues requested.
 113
 114    * **Size of Queues**
 115
 116      This is the requested size of receive/transmit queues, while the actual size
 117      will be the minimum between the requested size and the maximal receive/transmit
 118      supported by the device.
 119
 120 Building DPDK
 121 -------------
 122
 123 See the :ref:`DPDK Getting Started Guide for Linux <linux_gsg>` for
 124 instructions on how to build DPDK.
 125
 126 By default the ENA PMD library will be built into the DPDK library.
 127
 128 For configuring and using UIO and VFIO frameworks, please also refer :ref:`the
 129 documentation that comes with DPDK suite <linux_gsg>`.
 130
 131 Supported ENA adapters
 132 ----------------------
 133
 134 Current ENA PMD supports the following ENA adapters including:
 135
 136 * ``1d0f:ec20`` - ENA VF
 137 * ``1d0f:ec21`` - ENA VF with LLQ support
 138
 139 Supported Operating Systems
 140 ---------------------------
 141
 142 Any Linux distribution fulfilling the conditions described in ``System Requirements``
 143 section of :ref:`the DPDK documentation <linux_gsg>` or refer to *DPDK Release Notes*.
 144
 145 Supported features
 146 ------------------
 147
 148 * MTU configuration
 149 * Jumbo frames up to 9K
 150 * IPv4/TCP/UDP checksum offload
 151 * TSO offload
 152 * Multiple receive and transmit queues
 153 * RSS hash
 154 * RSS indirection table configuration
 155 * Low Latency Queue for Tx
 156 * Basic and extended statistics
 157 * LSC event notification
 158 * Watchdog (requires handling of timers in the application)
 159 * Device reset upon failure
 160
 161 Prerequisites
 162 -------------
 163
 164 #. Prepare the system as recommended by DPDK suite.  This includes environment
 165    variables, hugepages configuration, tool-chains and configuration.
 166
 167 #. ENA PMD can operate with ``vfio-pci``(*) or ``igb_uio`` driver.
 168
 169    (*) ENAv2 hardware supports Low Latency Queue v2 (LLQv2). This feature
 170    reduces the latency of the packets by pushing the header directly through
 171    the PCI to the device, before the DMA is even triggered. For proper work
 172    kernel PCI driver must support write combining (WC). In mainline version of
 173    ``igb_uio`` (in DPDK repo) it must be enabled by loading module with
 174    ``wc_activate=1`` flag (example below). However, mainline's vfio-pci
 175    driver in kernel doesn't have WC support yet (planed to be added).
 176    If vfio-pci used user should be either turn off ENAv2 (to avoid performance
 177    impact) or recompile vfio-pci driver with patch provided in
 178    `amzn-github <https://github.com/amzn/amzn-drivers/tree/master/userspace/dpdk/enav2-vfio-patch>`_.
 179
 180 #. Insert ``vfio-pci`` or ``igb_uio`` kernel module using the command
 181    ``modprobe vfio-pci`` or ``modprobe uio; insmod igb_uio.ko wc_activate=1``
 182    respectively.
 183
 184 #. For ``vfio-pci`` users only:
 185    Please make sure that ``IOMMU`` is enabled in your system,
 186    or use ``vfio`` driver in ``noiommu`` mode::
 187
 188      echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
 189
 190    To use ``noiommu`` mode, the ``vfio-pci`` must be built with flag
 191    ``CONFIG_VFIO_NOIOMMU``.
 192
 193 #. Bind the intended ENA device to ``vfio-pci`` or ``igb_uio`` module.
 194
 195 At this point the system should be ready to run DPDK applications. Once the
 196 application runs to completion, the ENA can be detached from attached module if
 197 necessary.
 198
 199 **Note about usage on \*.metal instances**
 200
 201 On AWS, the metal instances are supporting IOMMU for both arm64 and x86_64
 202 hosts.
 203
 204 * x86_64 (e.g. c5.metal, i3.metal):
 205    IOMMU should be disabled by default. In that situation, the ``igb_uio`` can
 206    be used as it is but ``vfio-pci`` should be working in no-IOMMU mode (please
 207    see above).
 208
 209    When IOMMU is enabled, ``igb_uio`` cannot be used as it's not supporting this
 210    feature, while ``vfio-pci`` should work without any changes.
 211    To enable IOMMU on those hosts, please update ``GRUB_CMDLINE_LINUX`` in file
 212    ``/etc/default/grub`` with the below extra boot arguments::
 213
 214     iommu=1 intel_iommu=on
 215
 216    Then, make the changes live by executing as a root::
 217
 218     # grub2-mkconfig > /boot/grub2/grub.cfg
 219
 220    Finally, reboot should result in IOMMU being enabled.
 221
 222 * arm64 (a1.metal):
 223    IOMMU should be enabled by default. Unfortunately, ``vfio-pci`` isn't
 224    supporting SMMU, which is implementation of IOMMU for arm64 architecture and
 225    ``igb_uio`` isn't supporting IOMMU at all, so to use DPDK with ENA on those
 226    hosts, one must disable IOMMU. This can be done by updating
 227    ``GRUB_CMDLINE_LINUX`` in file ``/etc/default/grub`` with the extra boot
 228    argument::
 229
 230     iommu.passthrough=1
 231
 232    Then, make the changes live by executing as a root::
 233
 234     # grub2-mkconfig > /boot/grub2/grub.cfg
 235
 236    Finally, reboot should result in IOMMU being disabled.
 237    Without IOMMU, ``igb_uio`` can be used as it is but ``vfio-pci`` should be
 238    working in no-IOMMU mode (please see above).
 239
 240 Usage example
 241 -------------
 242
 243 Follow instructions available in the document
 244 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to launch
 245 **testpmd** with Amazon ENA devices managed by librte_pmd_ena.
 246
 247 Example output:
 248
 249 .. code-block:: console
 250
 251    [...]
 252    EAL: PCI device 0000:00:06.0 on NUMA socket -1
 253    EAL:   Invalid NUMA socket, default to 0
 254    EAL:   probe driver: 1d0f:ec20 net_ena
 255
 256    Interactive-mode selected
 257    testpmd: create a new mbuf pool <mbuf_pool_socket_0>: n=171456, size=2176, socket=0
 258    testpmd: preferred mempool ops selected: ring_mp_mc
 259    Warning! port-topology=paired and odd forward ports number, the last port will pair with itself.
 260    Configuring Port 0 (socket 0)
 261    Port 0: 00:00:00:11:00:01
 262    Checking link statuses...
 263
 264    Done
 265    testpmd>