share/man/man4/ena.4

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