share/man/man4/ena.4

   1 .\" Copyright (c) 2015-2017 Amazon.com, Inc. or its affiliates.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\"
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\"
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  17 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  18 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  19 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  20 .\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  26 .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: head/share/man/man4/ena.4 322683 2017-08-19 00:51:45Z emaste $
  29 .\"
  30 .Dd July 22, 2018
  31 .Dt ENA 4
  32 .Os
  33 .Sh NAME
  34 .Nm ena
  35 .Nd "DragonFly kernel driver for the Elastic Network Adapter (ENA) family"
  36 .Sh SYNOPSIS
  37 To compile this driver into the kernel,
  38 place the following line in your
  39 kernel configuration file:
  40 .Bd -ragged -offset indent
  41 .Cd "device ena"
  42 .Ed
  43 .Pp
  44 Alternatively, to load the driver as a
  45 module at boot time, place the following line in
  46 .Xr loader.conf 5 :
  47 .Bd -literal -offset indent
  48 if_ena_load="YES"
  49 .Ed
  50 .Sh DESCRIPTION
  51 The ENA is a networking interface designed to make good use of modern CPU
  52 features and system architectures.
  53 .Pp
  54 The ENA device exposes a lightweight management interface with a
  55 minimal set of memory mapped registers and extendable command set
  56 through an Admin Queue.
  57 .Pp
  58 The driver supports a range of ENA devices, is link-speed independent
  59 (i.e., the same driver is used for 10GbE, 25GbE, 40GbE, etc.), and has
  60 a negotiated and extendable feature set.
  61 .Pp
  62 Some ENA devices support SR-IOV. This driver is used for both the
  63 SR-IOV Physical Function (PF) and Virtual Function (VF) devices.
  64 .Pp
  65 The ENA devices enable high speed and low overhead network traffic
  66 processing by providing multiple Tx/Rx queue pairs (the maximum number
  67 is advertised by the device via the Admin Queue), a dedicated MSI-X
  68 interrupt vector per Tx/Rx queue pair, and CPU cacheline optimized
  69 data placement.
  70 .Pp
  71 The
  72 .Nm
  73 driver supports industry standard TCP/IP offload features such
  74 as checksum offload and TCP transmit segmentation offload (TSO).
  75 Receive-side scaling (RSS) is supported for multi-core scaling.
  76 .Pp
  77 The
  78 .Nm
  79 driver and its corresponding devices implement health
  80 monitoring mechanisms such as watchdog, enabling the device and driver
  81 to recover in a manner transparent to the application, as well as
  82 debug logs.
  83 .Pp
  84 Some of the ENA devices support a working mode called Low-latency
  85 Queue (LLQ), which saves several more microseconds. This feature will
  86 be implemented for driver in future releases.
  87 .Sh HARDWARE
  88 Supported PCI vendor ID/device IDs:
  89 .Pp
  90 .Bl -bullet -compact
  91 .It
  92 1d0f:0ec2 - ENA PF
  93 .It
  94 1d0f:1ec2 - ENA PF with LLQ support
  95 .It
  96 1d0f:ec20 - ENA VF
  97 .It
  98 1d0f:ec21 - ENA VF with LLQ support
  99 .El
 100 .Sh DIAGNOSTICS
 101 .Ss Device initialization phase:
 102 .Bl -diag
 103 .It ena%d: failed to init mmio read less
 104 .Pp
 105 Error occurred during initialization of the mmio register read request.
 106 .It ena%d: Can not reset device
 107 .Pp
 108 Device could not be reset; device may not be responding or is already
 109 during reset.
 110 .It ena%d: device version is too low
 111 .Pp
 112 Version of the controller is too low and it is not supported by the driver.
 113 .It ena%d: Invalid dma width value %d
 114 .Pp
 115 The controller is able to request dma transaction width. Device stopped
 116 responding or it demanded invalid value.
 117 .It ena%d: Can not initialize ena admin queue with device
 118 .Pp
 119 Initialization of the Admin Queue failed; device may not be responding or there
 120 was a problem with initialization of the resources.
 121 .It ena%d: Cannot get attribute for ena device rc: %d
 122 .Pp
 123 Failed to get attributes of the device from the controller.
 124 .It ena%d: Cannot configure aenq groups rc: %d
 125 .Pp
 126 Errors occurred when trying to configure AENQ groups.
 127 .El
 128 .Ss Driver initialisation/shutdown phase:
 129 .Bl -diag
 130 .It ena%d: PCI resource allocation failed!
 131 .It ena%d: allocating ena_dev failed
 132 .It ena%d: failed to pmap registers bar
 133 .It ena%d: Error while setting up bufring
 134 .It ena%d: Error with initialization of IO rings
 135 .It ena%d: can not allocate ifnet structure
 136 .It ena%d: Error with network interface setup
 137 .It ena%d: Failed to enable and set the admin interrupts
 138 .It ena%d: Failed to allocate %d, vectors %d
 139 .It ena%d: Failed to enable MSIX, vectors %d rc %d
 140 .It ena%d: Error with MSI-X enablement
 141 .It ena%d: could not allocate irq vector: %d
 142 .It ena%d: Unable to allocate bus resource: registers
 143 .Pp
 144 Resource allocation failed when initializing the device; driver will not
 145 be attached.
 146 .It ena%d: ENA device init failed (err: %d)
 147 .Pp
 148 Device initialization failed; driver will not be attached.
 149 .It ena%d: could not activate irq vector: %d
 150 .Pp
 151 Error occurred when trying to activate interrupt vectors for Admin Queue.
 152 .It ena%d: failed to register interrupt handler for irq %ju: %d
 153 .Pp
 154 Error occurred when trying to register Admin Queue interrupt handler.
 155 .It ena%d: Cannot setup mgmnt queue intr
 156 .Pp
 157 Error occurred during configuration of the Admin Queue interrupts.
 158 .It ena%d: Enable MSI-X failed
 159 .Pp
 160 Configuration of the MSI-X for Admin Queue failed; there could be lack
 161 of resources or interrupts could not have been configured; driver will
 162 not be attached.
 163 .It ena%d: VLAN is in use, detach first
 164 .Pp
 165 VLANs are being used when trying to detach the driver; VLANs should be detached
 166 first and then detach routine should be called again.
 167 .It ena%d: Unmapped RX DMA tag associations
 168 .It ena%d: Unmapped TX DMA tag associations
 169 .Pp
 170 Error occurred when trying to destroy RX/TX DMA tag.
 171 .It ena%d: Cannot init RSS
 172 .It ena%d: Cannot fill indirect table
 173 .It ena%d: Cannot fill indirect table
 174 .It ena%d: Cannot fill hash function
 175 .It ena%d: Cannot fill hash control
 176 .It ena%d: WARNING: RSS was not properly initialized, it will affect bandwidth
 177 .Pp
 178 Error occurred during initialization of one of RSS resources; device is still
 179 going to work but it will affect performance because all RX packets will be
 180 passed to queue 0 and there will be no hash information.
 181 .It ena%d: failed to tear down irq: %d
 182 .It ena%d: dev has no parent while releasing res for irq: %d
 183 Release of the interrupts failed.
 184 .El
 185 .Ss Additional diagnostic:
 186 .Bl -diag
 187 .It ena%d: Cannot get attribute for ena device
 188 .Pp
 189 This message appears when trying to change MTU and driver is unable to get
 190 attributes from the device.
 191 .It ena%d: Invalid MTU setting. new_mtu: %d
 192 .Pp
 193 Requested MTU value is not supported and will not be set.
 194 .It ena%d: keep alive watchdog timeout
 195 .Pp
 196 Device stopped responding and will be reset.
 197 .It ena%d: Found a Tx that wasn't completed on time, qid %d, index %d.
 198 .Pp
 199 Packet was pushed to the NIC but not sent within given time limit; it may
 200 be caused by hang of the IO queue.
 201 .It ena%d: The number of lost tx completion is aboce the threshold (%d > %d). Reset the device
 202 .Pp
 203 If too many Tx wasn't completed on time the device is going to be reset; it may
 204 be caused by hanged queue or device.
 205 .It ena%d: trigger reset is on
 206 .Pp
 207 Device will be reset; reset is triggered either by watchdog or if too many TX
 208 packets were not completed on time.
 209 .It ena%d: invalid value recvd
 210 .Pp
 211 Link status received from the device in the AENQ handler is invalid.
 212 .It ena%d: Allocation for Tx Queue %u failed
 213 .It ena%d: Allocation for Rx Queue %u failed
 214 .It ena%d: Unable to create Rx DMA map for buffer %d
 215 .It ena%d: Failed to create io TX queue #%d rc: %d
 216 .It ena%d: Failed to get TX queue handlers. TX queue num %d rc: %d
 217 .It ena%d: Failed to create io RX queue[%d] rc: %d
 218 .It ena%d: Failed to get RX queue handlers. RX queue num %d rc: %d
 219 .It ena%d: failed to request irq
 220 .It ena%d: could not allocate irq vector: %d
 221 .It ena%d: failed to register interrupt handler for irq %ju: %d
 222 .Pp
 223 IO resources initialization failed. Interface will not be brought up.
 224 .It ena%d: LRO[%d] Initialization failed!
 225 .Pp
 226 Initialization of the LRO for the RX ring failed.
 227 .It ena%d: failed to alloc buffer for rx queue
 228 .It ena%d: failed to add buffer for rx queue %d
 229 .It ena%d: refilled rx queue %d with %d pages only
 230 .Pp
 231 Allocation of resources used on RX path failed; if happened during
 232 initialization of the IO queue, the interface will not be brought up.
 233 .It ena%d: ioctl promisc/allmulti
 234 .Pp
 235 IOCTL request for the device to work in promiscuous/allmulti mode; see
 236 .Xr ifconfig 8
 237 for more details.
 238 .It ena%d: too many fragments. Last fragment: %d!
 239 .Pp
 240 Packet with unsupported number of segments was queued for sending to the
 241 device; packet will be dropped.
 242 .El
 243 .Sh SUPPORT
 244 If an issue is identified with the released source code with a supported adapter
 245 email the specific information related to the issue to
 246 .Aq Mt mk@semihalf.com
 247 and
 248 .Aq Mt mw@semihalf.com .
 249 .Sh SEE ALSO
 250 .Xr vlan 4 ,
 251 .Xr ifconfig 8
 252 .Sh AUTHORS
 253 The
 254 .Nm
 255 driver was written by
 256 .An Semihalf .