Documentation/networking/device_drivers/ethernet/amazon/ena.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ============================================================
   4 Linux kernel driver for Elastic Network Adapter (ENA) family
   5 ============================================================
   6
   7 Overview
   8 ========
   9
  10 ENA is a networking interface designed to make good use of modern CPU
  11 features and system architectures.
  12
  13 The ENA device exposes a lightweight management interface with a
  14 minimal set of memory mapped registers and extendible command set
  15 through an Admin Queue.
  16
  17 The driver supports a range of ENA devices, is link-speed independent
  18 (i.e., the same driver is used for 10GbE, 25GbE, 40GbE, etc), and has
  19 a negotiated and extendible feature set.
  20
  21 Some ENA devices support SR-IOV. This driver is used for both the
  22 SR-IOV Physical Function (PF) and Virtual Function (VF) devices.
  23
  24 ENA devices enable high speed and low overhead network traffic
  25 processing by providing multiple Tx/Rx queue pairs (the maximum number
  26 is advertised by the device via the Admin Queue), a dedicated MSI-X
  27 interrupt vector per Tx/Rx queue pair, adaptive interrupt moderation,
  28 and CPU cacheline optimized data placement.
  29
  30 The ENA driver supports industry standard TCP/IP offload features such as
  31 checksum offload. Receive-side scaling (RSS) is supported for multi-core
  32 scaling.
  33
  34 The ENA driver and its corresponding devices implement health
  35 monitoring mechanisms such as watchdog, enabling the device and driver
  36 to recover in a manner transparent to the application, as well as
  37 debug logs.
  38
  39 Some of the ENA devices support a working mode called Low-latency
  40 Queue (LLQ), which saves several more microseconds.
  41
  42 ENA Source Code Directory Structure
  43 ===================================
  44
  45 =================   ======================================================
  46 ena_com.[ch]        Management communication layer. This layer is
  47                     responsible for the handling all the management
  48                     (admin) communication between the device and the
  49                     driver.
  50 ena_eth_com.[ch]    Tx/Rx data path.
  51 ena_admin_defs.h    Definition of ENA management interface.
  52 ena_eth_io_defs.h   Definition of ENA data path interface.
  53 ena_common_defs.h   Common definitions for ena_com layer.
  54 ena_regs_defs.h     Definition of ENA PCI memory-mapped (MMIO) registers.
  55 ena_netdev.[ch]     Main Linux kernel driver.
  56 ena_ethtool.c       ethtool callbacks.
  57 ena_xdp.[ch]        XDP files
  58 ena_pci_id_tbl.h    Supported device IDs.
  59 =================   ======================================================
  60
  61 Management Interface:
  62 =====================
  63
  64 ENA management interface is exposed by means of:
  65
  66 - PCIe Configuration Space
  67 - Device Registers
  68 - Admin Queue (AQ) and Admin Completion Queue (ACQ)
  69 - Asynchronous Event Notification Queue (AENQ)
  70
  71 ENA device MMIO Registers are accessed only during driver
  72 initialization and are not used during further normal device
  73 operation.
  74
  75 AQ is used for submitting management commands, and the
  76 results/responses are reported asynchronously through ACQ.
  77
  78 ENA introduces a small set of management commands with room for
  79 vendor-specific extensions. Most of the management operations are
  80 framed in a generic Get/Set feature command.
  81
  82 The following admin queue commands are supported:
  83
  84 - Create I/O submission queue
  85 - Create I/O completion queue
  86 - Destroy I/O submission queue
  87 - Destroy I/O completion queue
  88 - Get feature
  89 - Set feature
  90 - Configure AENQ
  91 - Get statistics
  92
  93 Refer to ena_admin_defs.h for the list of supported Get/Set Feature
  94 properties.
  95
  96 The Asynchronous Event Notification Queue (AENQ) is a uni-directional
  97 queue used by the ENA device to send to the driver events that cannot
  98 be reported using ACQ. AENQ events are subdivided into groups. Each
  99 group may have multiple syndromes, as shown below
 100
 101 The events are:
 102
 103 ====================    ===============
 104 Group                   Syndrome
 105 ====================    ===============
 106 Link state change       **X**
 107 Fatal error             **X**
 108 Notification            Suspend traffic
 109 Notification            Resume traffic
 110 Keep-Alive              **X**
 111 ====================    ===============
 112
 113 ACQ and AENQ share the same MSI-X vector.
 114
 115 Keep-Alive is a special mechanism that allows monitoring the device's health.
 116 A Keep-Alive event is delivered by the device every second.
 117 The driver maintains a watchdog (WD) handler which logs the current state and
 118 statistics. If the keep-alive events aren't delivered as expected the WD resets
 119 the device and the driver.
 120
 121 Data Path Interface
 122 ===================
 123
 124 I/O operations are based on Tx and Rx Submission Queues (Tx SQ and Rx
 125 SQ correspondingly). Each SQ has a completion queue (CQ) associated
 126 with it.
 127
 128 The SQs and CQs are implemented as descriptor rings in contiguous
 129 physical memory.
 130
 131 The ENA driver supports two Queue Operation modes for Tx SQs:
 132
 133 - **Regular mode:**
 134   In this mode the Tx SQs reside in the host's memory. The ENA
 135   device fetches the ENA Tx descriptors and packet data from host
 136   memory.
 137
 138 - **Low Latency Queue (LLQ) mode or "push-mode":**
 139   In this mode the driver pushes the transmit descriptors and the
 140   first 96 bytes of the packet directly to the ENA device memory
 141   space. The rest of the packet payload is fetched by the
 142   device. For this operation mode, the driver uses a dedicated PCI
 143   device memory BAR, which is mapped with write-combine capability.
 144
 145   **Note that** not all ENA devices support LLQ, and this feature is negotiated
 146   with the device upon initialization. If the ENA device does not
 147   support LLQ mode, the driver falls back to the regular mode.
 148
 149 The Rx SQs support only the regular mode.
 150
 151 The driver supports multi-queue for both Tx and Rx. This has various
 152 benefits:
 153
 154 - Reduced CPU/thread/process contention on a given Ethernet interface.
 155 - Cache miss rate on completion is reduced, particularly for data
 156   cache lines that hold the sk_buff structures.
 157 - Increased process-level parallelism when handling received packets.
 158 - Increased data cache hit rate, by steering kernel processing of
 159   packets to the CPU, where the application thread consuming the
 160   packet is running.
 161 - In hardware interrupt re-direction.
 162
 163 Interrupt Modes
 164 ===============
 165
 166 The driver assigns a single MSI-X vector per queue pair (for both Tx
 167 and Rx directions). The driver assigns an additional dedicated MSI-X vector
 168 for management (for ACQ and AENQ).
 169
 170 Management interrupt registration is performed when the Linux kernel
 171 probes the adapter, and it is de-registered when the adapter is
 172 removed. I/O queue interrupt registration is performed when the Linux
 173 interface of the adapter is opened, and it is de-registered when the
 174 interface is closed.
 175
 176 The management interrupt is named::
 177
 178    ena-mgmnt@pci:<PCI domain:bus:slot.function>
 179
 180 and for each queue pair, an interrupt is named::
 181
 182    <interface name>-Tx-Rx-<queue index>
 183
 184 The ENA device operates in auto-mask and auto-clear interrupt
 185 modes. That is, once MSI-X is delivered to the host, its Cause bit is
 186 automatically cleared and the interrupt is masked. The interrupt is
 187 unmasked by the driver after NAPI processing is complete.
 188
 189 Interrupt Moderation
 190 ====================
 191
 192 ENA driver and device can operate in conventional or adaptive interrupt
 193 moderation mode.
 194
 195 **In conventional mode** the driver instructs device to postpone interrupt
 196 posting according to static interrupt delay value. The interrupt delay
 197 value can be configured through `ethtool(8)`. The following `ethtool`
 198 parameters are supported by the driver: ``tx-usecs``, ``rx-usecs``
 199
 200 **In adaptive interrupt** moderation mode the interrupt delay value is
 201 updated by the driver dynamically and adjusted every NAPI cycle
 202 according to the traffic nature.
 203
 204 Adaptive coalescing can be switched on/off through `ethtool(8)`'s
 205 :code:`adaptive_rx on|off` parameter.
 206
 207 More information about Adaptive Interrupt Moderation (DIM) can be found in
 208 Documentation/networking/net_dim.rst
 209
 210 .. _`RX copybreak`:
 211
 212 RX copybreak
 213 ============
 214
 215 The rx_copybreak is initialized by default to ENA_DEFAULT_RX_COPYBREAK
 216 and can be configured by the ETHTOOL_STUNABLE command of the
 217 SIOCETHTOOL ioctl.
 218
 219 This option controls the maximum packet length for which the RX
 220 descriptor it was received on would be recycled. When a packet smaller
 221 than RX copybreak bytes is received, it is copied into a new memory
 222 buffer and the RX descriptor is returned to HW.
 223
 224 Statistics
 225 ==========
 226
 227 The user can obtain ENA device and driver statistics using `ethtool`.
 228 The driver can collect regular or extended statistics (including
 229 per-queue stats) from the device.
 230
 231 In addition the driver logs the stats to syslog upon device reset.
 232
 233 MTU
 234 ===
 235
 236 The driver supports an arbitrarily large MTU with a maximum that is
 237 negotiated with the device. The driver configures MTU using the
 238 SetFeature command (ENA_ADMIN_MTU property). The user can change MTU
 239 via `ip(8)` and similar legacy tools.
 240
 241 Stateless Offloads
 242 ==================
 243
 244 The ENA driver supports:
 245
 246 - IPv4 header checksum offload
 247 - TCP/UDP over IPv4/IPv6 checksum offloads
 248
 249 RSS
 250 ===
 251
 252 - The ENA device supports RSS that allows flexible Rx traffic
 253   steering.
 254 - Toeplitz and CRC32 hash functions are supported.
 255 - Different combinations of L2/L3/L4 fields can be configured as
 256   inputs for hash functions.
 257 - The driver configures RSS settings using the AQ SetFeature command
 258   (ENA_ADMIN_RSS_HASH_FUNCTION, ENA_ADMIN_RSS_HASH_INPUT and
 259   ENA_ADMIN_RSS_INDIRECTION_TABLE_CONFIG properties).
 260 - If the NETIF_F_RXHASH flag is set, the 32-bit result of the hash
 261   function delivered in the Rx CQ descriptor is set in the received
 262   SKB.
 263 - The user can provide a hash key, hash function, and configure the
 264   indirection table through `ethtool(8)`.
 265
 266 DATA PATH
 267 =========
 268
 269 Tx
 270 --
 271
 272 :code:`ena_start_xmit()` is called by the stack. This function does the following:
 273
 274 - Maps data buffers (``skb->data`` and frags).
 275 - Populates ``ena_buf`` for the push buffer (if the driver and device are
 276   in push mode).
 277 - Prepares ENA bufs for the remaining frags.
 278 - Allocates a new request ID from the empty ``req_id`` ring. The request
 279   ID is the index of the packet in the Tx info. This is used for
 280   out-of-order Tx completions.
 281 - Adds the packet to the proper place in the Tx ring.
 282 - Calls :code:`ena_com_prepare_tx()`, an ENA communication layer that converts
 283   the ``ena_bufs`` to ENA descriptors (and adds meta ENA descriptors as
 284   needed).
 285
 286   * This function also copies the ENA descriptors and the push buffer
 287     to the Device memory space (if in push mode).
 288
 289 - Writes a doorbell to the ENA device.
 290 - When the ENA device finishes sending the packet, a completion
 291   interrupt is raised.
 292 - The interrupt handler schedules NAPI.
 293 - The :code:`ena_clean_tx_irq()` function is called. This function handles the
 294   completion descriptors generated by the ENA, with a single
 295   completion descriptor per completed packet.
 296
 297   * ``req_id`` is retrieved from the completion descriptor. The ``tx_info`` of
 298     the packet is retrieved via the ``req_id``. The data buffers are
 299     unmapped and ``req_id`` is returned to the empty ``req_id`` ring.
 300   * The function stops when the completion descriptors are completed or
 301     the budget is reached.
 302
 303 Rx
 304 --
 305
 306 - When a packet is received from the ENA device.
 307 - The interrupt handler schedules NAPI.
 308 - The :code:`ena_clean_rx_irq()` function is called. This function calls
 309   :code:`ena_com_rx_pkt()`, an ENA communication layer function, which returns the
 310   number of descriptors used for a new packet, and zero if
 311   no new packet is found.
 312 - :code:`ena_rx_skb()` checks packet length:
 313
 314   * If the packet is small (len < rx_copybreak), the driver allocates
 315     a SKB for the new packet, and copies the packet payload into the
 316     SKB data buffer.
 317
 318     - In this way the original data buffer is not passed to the stack
 319       and is reused for future Rx packets.
 320
 321   * Otherwise the function unmaps the Rx buffer, sets the first
 322     descriptor as `skb`'s linear part and the other descriptors as the
 323     `skb`'s frags.
 324
 325 - The new SKB is updated with the necessary information (protocol,
 326   checksum hw verify result, etc), and then passed to the network
 327   stack, using the NAPI interface function :code:`napi_gro_receive()`.
 328
 329 Dynamic RX Buffers (DRB)
 330 ------------------------
 331
 332 Each RX descriptor in the RX ring is a single memory page (which is either 4KB
 333 or 16KB long depending on system's configurations).
 334 To reduce the memory allocations required when dealing with a high rate of small
 335 packets, the driver tries to reuse the remaining RX descriptor's space if more
 336 than 2KB of this page remain unused.
 337
 338 A simple example of this mechanism is the following sequence of events:
 339
 340 ::
 341
 342         1. Driver allocates page-sized RX buffer and passes it to hardware
 343                 +----------------------+
 344                 |4KB RX Buffer         |
 345                 +----------------------+
 346
 347         2. A 300Bytes packet is received on this buffer
 348
 349         3. The driver increases the ref count on this page and returns it back to
 350            HW as an RX buffer of size 4KB - 300Bytes = 3796 Bytes
 351                +----+--------------------+
 352                |****|3796 Bytes RX Buffer|
 353                +----+--------------------+
 354
 355 This mechanism isn't used when an XDP program is loaded, or when the
 356 RX packet is less than rx_copybreak bytes (in which case the packet is
 357 copied out of the RX buffer into the linear part of a new skb allocated
 358 for it and the RX buffer remains the same size, see `RX copybreak`_).