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 June 4, 2021
  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 When RSS is enabled, each Tx/Rx queue pair is bound to a corresponding
  75 CPU core and its NUMA domain.
  76 The order of those bindings is based on the RSS bucket mapping.
  77 For builds with RSS support disabled, the
  78 CPU and NUMA management is left to the kernel.
  79 .Pp
  80 The
  81 .Nm
  82 driver supports industry standard TCP/IP offload features such
  83 as checksum offload and TCP transmit segmentation offload (TSO).
  84 Receive-side scaling (RSS) is supported for multi-core scaling.
  85 .Pp
  86 The
  87 .Nm
  88 driver and its corresponding devices implement health
  89 monitoring mechanisms such as watchdog, enabling the device and driver
  90 to recover in a manner transparent to the application, as well as
  91 debug logs.
  92 .Pp
  93 Some of the ENA devices support a working mode called Low-latency
  94 Queue (LLQ), which saves several more microseconds.
  95 .Pp
  96 Support for the
  97 .Xr netmap 4
  98 framework is provided by the
  99 .Nm
 100 driver.
 101 Kernel must be built with the DEV_NETMAP option to be able to use this feature.
 102 .Sh HARDWARE
 103 Supported PCI vendor ID/device IDs:
 104 .Pp
 105 .Bl -bullet -compact
 106 .It
 107 1d0f:0ec2 - ENA PF
 108 .It
 109 1d0f:1ec2 - ENA PF with LLQ support
 110 .It
 111 1d0f:ec20 - ENA VF
 112 .It
 113 1d0f:ec21 - ENA VF with LLQ support
 114 .El
 115 .Sh LOADER TUNABLES
 116 The
 117 .Nm
 118 driver's behavior can be changed using run-time or boot-time sysctl
 119 arguments.
 120 The boot-time arguments can be set at the
 121 .Xr loader 8
 122 prompt before booting the kernel, or stored in the
 123 .Xr loader.conf 5 .
 124 The run-time arguments can be set using the
 125 .Xr sysctl 8
 126 command.
 127 .Pp
 128 Boot-time tunables:
 129 .Bl -tag -width indent
 130 .It Va hw.ena.enable_9k_mbufs
 131 Use 9k mbufs for the Rx descriptors.
 132 The default is 0.
 133 If the node value is set to 1, 9k mbufs will be used for the Rx buffers.
 134 If set to 0, page size mbufs will be used instead.
 135 .Pp
 136 Using 9k buffers for Rx can improve Rx throughput, but in low memory conditions
 137 it might increase allocation time, as the system has to look for 3 contiguous
 138 pages.
 139 This can further lead to OS instability, together with ENA driver reset and NVMe
 140 timeouts.
 141 If network performance is critical and memory capacity is sufficient, the 9k
 142 mbufs can be used.
 143 .It Va hw.ena.force_large_llq_headers
 144 Force the driver to use large LLQ headers (224 bytes).
 145 The default is 0.
 146 If the node value is set to 0, the regular size LLQ header will be used, which
 147 is 96B.
 148 In some cases, the packet header can be bigger than this (for example -
 149 IPv6 with multiple extensions).
 150 In such a situation, the large LLQ headers should be used by setting this node
 151 value to 1.
 152 This will take effect only if the device supports both LLQ and large LLQ
 153 headers.
 154 Otherwise, it will fallback to the no LLQ mode or regular header size.
 155 .Pp
 156 Increasing LLQ header size reduces the size of the Tx queue by half, so it may
 157 affect the number of dropped Tx packets.
 158 .El
 159 .Pp
 160 Run-time tunables:
 161 .Bl -tag -width indent
 162 .It Va hw.ena.log_level
 163 Controls extra logging verbosity of the driver.
 164 The default is 2.
 165 The higher the logging level, the more logs will be printed out. 0 means all
 166 extra logs are disabled and only error logs will be printed out.
 167 Default value (2) reports errors, warnings and is verbose about driver
 168 operation.
 169 .Pp
 170 The possible flags are:
 171 .Pp
 172 .Bl -bullet -compact
 173 .It
 174 0 - ENA_ERR  - Enable driver error messages and ena_com error logs.
 175 .It
 176 1 - ENA_WARN - Enable logs for non-critical errors.
 177 .It
 178 2 - ENA_INFO - Make the driver more verbose about its actions.
 179 .It
 180 3 - ENA_DBG  - Enable debug logs.
 181 .El
 182 .Pp
 183 NOTE: In order to enable logging on the Tx/Rx data path, driver must be compiled
 184 with ENA_LOG_IO_ENABLE compilation flag.
 185 .Pp
 186 Example:
 187 To enable logs for errors and warnings, the following command should be used:
 188 .Bd -literal -offset indent
 189 sysctl hw.ena.log_level=1
 190 .Ed
 191 .It Va dev.ena.X.io_queues_nb
 192 Number of the currently allocated and used IO queues.
 193 The default is max_num_io_queues.
 194 Controls the number of IO queue pairs (Tx/Rx). As this call has to reallocate
 195 the queues, it will reset the interface and restart all the queues - this means
 196 that everything, which was currently held in the queue, will be lost, leading to
 197 potential packet drops.
 198 .Pp
 199 This call can fail if the system isn't able to provide the driver with enough
 200 resources.
 201 In that situation, the driver will try to revert the previous number of the IO
 202 queues.
 203 If this also fails, the device reset will be triggered.
 204 .Pp
 205 Example:
 206 To use only 2 Tx and Rx queues for the device ena1, the following command should
 207 be used:
 208 .Bd -literal -offset indent
 209 sysctl dev.ena.1.io_queues_nb=2
 210 .Ed
 211 .It Va dev.ena.X.rx_queue_size
 212 Size of the Rx queue.
 213 The default is 1024.
 214 Controls the number of IO descriptors for each Rx queue.
 215 The user may want to increase the Rx queue size if they observe a high number of
 216 Rx drops in the driver's statistics.
 217 For performance reasons, the Rx queue size must be a power of 2.
 218 .Pp
 219 This call can fail if the system isn't able to provide the driver with enough
 220 resources.
 221 In that situation, the driver will try to revert to the previous number of the
 222 descriptors.
 223 If this also fails, the device reset will be triggered.
 224 .Pp
 225 Example:
 226 To increase Rx ring size to 8K descriptors for the device ena0, the following
 227 command should be used:
 228 .Bd -literal -offset indent
 229 sysctl dev.ena.0.rx_queue_size=8192
 230 .Ed
 231 .It Va dev.ena.X.buf_ring_size
 232 Size of the Tx buffer ring (drbr).
 233 The default is 4096.
 234 Input must be a power of 2.
 235 Controls the number of mbufs that can be held in the Tx buffer ring.
 236 The drbr is used as a multiple-producer, single-consumer lockless ring for
 237 buffering extra mbufs coming from the stack in case the Tx procedure is busy
 238 sending the packets, or the Tx ring is full.
 239 Increasing the size of the buffer ring may reduce the number of Tx packets being
 240 dropped in case of a big Tx burst, which cannot be handled by the IO queue
 241 immediately.
 242 Each Tx queue has its own drbr.
 243 .Pp
 244 It is recommended to keep the drbr with at least the default value, but in case
 245 the system lacks the resources, it can be reduced.
 246 This call can fail if the system is not able to provide the driver with enough
 247 resources.
 248 In that situation, the driver will try to revert to the previous number of the
 249 drbr and trigger the device reset.
 250 .Pp
 251 Example:
 252 To set drbr size for interface ena0 to 2048, the following command should
 253 be used:
 254 .Bd -literal -offset indent
 255 sysctl dev.ena.0.buf_ring_size=2048
 256 .Ed
 257 .It Va dev.ena.X.eni_metrics.sample_interval
 258 Interval in seconds for updating ENI metrics.
 259 The default is 0.
 260 Determines how often (if ever) the ENI metrics should be updated.
 261 The ENI metrics are being updated asynchronously in a timer service in order to
 262 avoid admin queue overload by sysctl node reading.
 263 The value in this node controls the interval between issuing admin commands to
 264 the device, which will update the ENI metrics values.
 265 .Pp
 266 If some application is periodically monitoring the eni_metrics, then the ENI
 267 metrics interval can be adjusted accordingly.
 268 Value 0 turns off the update completely.
 269 Value 1 is the minimum interval and is equal to 1 second.
 270 The maximum allowed update interval is 1 hour.
 271 .Pp
 272 Example:
 273 To update ENI metrics for the device ena1 every 10 seconds, the following
 274 command should be used:
 275 .Bd -literal -offset indent
 276 sysctl dev.ena.1.eni_metrics.sample_interval=10
 277 .Ed
 278 .It Va dev.ena.X.rss.indir_table_size
 279 RSS indirection table size.
 280 The default is 128.
 281 Returns the number of entries in the RSS indirection table.
 282 .Pp
 283 Example:
 284 To read the RSS indirection table size, the following command should be used:
 285 .Bd -literal -offset indent
 286 sysctl dev.ena.0.rss.indir_table_size
 287 .Ed
 288 .It Va dev.ena.X.rss.indir_table
 289 RSS indirection table mapping.
 290 The default is x:y key-pairs of indir_table_size length.
 291 Updates selected indices of the RSS indirection table.
 292 .Pp
 293 The entry string consists of one or more x:y keypairs, where x stands for
 294 the table index and y for its new value.
 295 Table indices that don't need to be
 296 updated can be omitted from the string and will retain their existing values.
 297 .Pp
 298 If an index is entered more than once, the last value is used.
 299 .Pp
 300 Example:
 301 To update two selected indices in the RSS indirection table, e.g. setting index
 302 0 to queue 5 and then index 5 to queue 0, the following command should be used:
 303 .Bd -literal -offset indent
 304 sysctl dev.ena.0.rss.indir_table="0:5 5:0"
 305 .Ed
 306 .It Va dev.ena.X.rss.key
 307 RSS hash key.
 308 The default is 40 bytes long randomly generated hash key.
 309 Controls the RSS Toeplitz hash algorithm key value.
 310 .Pp
 311 Only available when driver compiled without the kernel side RSS support.
 312 .Pp
 313 Example:
 314 To change the RSS hash key value to
 315 .Pp
 316 0x6d, 0x5a, 0x56, 0xda, 0x25, 0x5b, 0x0e, 0xc2,
 317 .br
 318 0x41, 0x67, 0x25, 0x3d, 0x43, 0xa3, 0x8f, 0xb0,
 319 .br
 320 0xd0, 0xca, 0x2b, 0xcb, 0xae, 0x7b, 0x30, 0xb4,
 321 .br
 322 0x77, 0xcb, 0x2d, 0xa3, 0x80, 0x30, 0xf2, 0x0c,
 323 .br
 324 0x6a, 0x42, 0xb7, 0x3b, 0xbe, 0xac, 0x01, 0xfa
 325 .Pp
 326 the following command should be used:
 327 .Bd -literal -offset indent
 328 sysctl dev.ena.0.rss.key=6d5a56da255b0ec24167253d43a38fb0d0ca2bcbae7b30b477cb2da38030f20c6a42b73bbeac01fa
 329 .Ed
 330 .El
 331 .Sh DIAGNOSTICS
 332 .Ss Device initialization phase
 333 .Bl -diag
 334 .It ena%d: failed to init mmio read less
 335 .Pp
 336 Error occurred during initialization of the mmio register read request.
 337 .It ena%d: Can not reset device
 338 .Pp
 339 Device could not be reset.
 340 .br
 341 Device may not be responding or is already during reset.
 342 .It ena%d: device version is too low
 343 .Pp
 344 Version of the controller is too old and it is not supported by the driver.
 345 .It ena%d: Invalid dma width value %d
 346 .Pp
 347 The controller is unable to request dma transaction width.
 348 .br
 349 Device stopped responding or it demanded invalid value.
 350 .It ena%d: Can not initialize ena admin queue with device
 351 .Pp
 352 Initialization of the Admin Queue failed.
 353 .br
 354 Device may not be responding or there was a problem with initialization of
 355 the resources.
 356 .It ena%d: Cannot get attribute for ena device rc: %d
 357 .Pp
 358 Failed to get attributes of the device from the controller.
 359 .It ena%d: Cannot configure aenq groups rc: %d
 360 .Pp
 361 Errors occurred when trying to configure AENQ groups.
 362 .El
 363 .Ss Driver initialization/shutdown phase
 364 .Bl -diag
 365 .It ena%d: PCI resource allocation failed!
 366 .It ena%d: failed to pmap registers bar
 367 .It ena%d: can not allocate ifnet structure
 368 .It ena%d: Error with network interface setup
 369 .It ena%d: Failed to enable and set the admin interrupts
 370 .It ena%d: Error, MSI-X is already enabled
 371 .It ena%d: Failed to enable MSIX, vectors %d rc %d
 372 .It ena%d: Not enough number of MSI-X allocated: %d
 373 .It ena%d: Error with MSI-X enablement
 374 .It ena%d: could not allocate irq vector: %d
 375 .It ena%d: unable to allocate bus resource: registers!
 376 .It ena%d: unable to allocate bus resource: msix!
 377 .Pp
 378 Resource allocation failed when initializing the device.
 379 .br
 380 Driver will not be attached.
 381 .It ena%d: ENA device init failed (err: %d)
 382 .It ena%d: Cannot initialize device
 383 .Pp
 384 Device initialization failed.
 385 .br
 386 Driver will not be attached.
 387 .It ena%d: failed to register interrupt handler for irq %ju: %d
 388 .Pp
 389 Error occurred when trying to register Admin Queue interrupt handler.
 390 .It ena%d: Cannot setup mgmnt queue intr
 391 .Pp
 392 Error occurred during configuration of the Admin Queue interrupts.
 393 .It ena%d: Enable MSI-X failed
 394 .Pp
 395 Configuration of the MSI-X for Admin Queue failed.
 396 .br
 397 There could be lack of resources or interrupts could not have been configured.
 398 .br
 399 Driver will not be attached.
 400 .It ena%d: VLAN is in use, detach first
 401 .Pp
 402 VLANs are being used when trying to detach the driver.
 403 .br
 404 VLANs must be detached first and then detach routine have to be called again.
 405 .It ena%d: Unmapped RX DMA tag associations
 406 .It ena%d: Unmapped TX DMA tag associations
 407 .Pp
 408 Error occurred when trying to destroy RX/TX DMA tag.
 409 .It ena%d: Cannot init indirect table
 410 .It ena%d: Cannot fill indirect table
 411 .It ena%d: Cannot fill hash function
 412 .It ena%d: Cannot fill hash control
 413 .It ena%d: WARNING: RSS was not properly initialized, it will affect bandwidth
 414 .Pp
 415 Error occurred during initialization of one of RSS resources.
 416 .br
 417 The device will work with reduced performance because all RX packets will be
 418 passed to queue 0 and there will be no hash information.
 419 .It ena%d: LLQ is not supported. Fallback to host mode policy.
 420 .It ena%d: Failed to configure the device mode. Fallback to host mode policy.
 421 .It ena%d: unable to allocate LLQ bar resource. Fallback to host mode policy.
 422 .Pp
 423 Error occurred during Low-latency Queue mode setup.
 424 .br
 425 The device will work, but without the LLQ performance gain.
 426 .It ena%d: failed to enable write combining.
 427 .Pp
 428 Error occurred while setting the Write Combining mode, required for the LLQ.
 429 .It ena%d: failed to tear down irq: %d
 430 .It ena%d: dev has no parent while releasing res for irq: %d
 431 Release of the interrupts failed.
 432 .El
 433 .Ss Additional diagnostic
 434 .Bl -diag
 435 .It ena%d: Invalid MTU setting. new_mtu: %d max_mtu: %d min mtu: %d
 436 .Pp
 437 Requested MTU value is not supported and will not be set.
 438 .It ena%d: Failed to set MTU to %d
 439 .Pp
 440 This message appears when either MTU change feature is not supported, or device
 441 communication error has occurred.
 442 .It ena%d: Keep alive watchdog timeout.
 443 .Pp
 444 Device stopped responding and will be reset.
 445 .It ena%d: Found a Tx that wasn't completed on time, qid %d, index %d.
 446 .Pp
 447 Packet was pushed to the NIC but not sent within given time limit.
 448 .br
 449 It may be caused by hang of the IO queue.
 450 .It ena%d: The number of lost tx completion is above the threshold (%d > %d). Reset the device
 451 .Pp
 452 If too many Tx weren't completed on time the device is going to be reset.
 453 .br
 454 It may be caused by hanged queue or device.
 455 .It ena%d: Trigger reset is on
 456 .Pp
 457 Device will be reset.
 458 .br
 459 Reset is triggered either by watchdog or if too many TX packets were not
 460 completed on time.
 461 .It ena%d: device reset scheduled but trigger_reset is off
 462 .Pp
 463 Reset task has been triggered, but the driver did not request it.
 464 .br
 465 Device reset will not be performed.
 466 .It ena%d: Device reset failed
 467 .Pp
 468 Error occurred while trying to reset the device.
 469 .It ena%d: Cannot initialize device
 470 .It ena%d: Error, mac address are different
 471 .It ena%d: Error, device max mtu is smaller than ifp MTU
 472 .It ena%d: Validation of device parameters failed
 473 .It ena%d: Enable MSI-X failed
 474 .It ena%d: Failed to create I/O queues
 475 .It ena%d: Reset attempt failed. Can not reset the device
 476 .Pp
 477 Error occurred while trying to restore the device after reset.
 478 .It ena%d: Device reset completed successfully, Driver info: %s
 479 .Pp
 480 Device has been correctly restored after reset and is ready to use.
 481 .It ena%d: Allocation for Tx Queue %u failed
 482 .It ena%d: Allocation for Rx Queue %u failed
 483 .It ena%d: Unable to create Rx DMA map for buffer %d
 484 .It ena%d: Failed to create io TX queue #%d rc: %d
 485 .It ena%d: Failed to get TX queue handlers. TX queue num %d rc: %d
 486 .It ena%d: Failed to create io RX queue[%d] rc: %d
 487 .It ena%d: Failed to get RX queue handlers. RX queue num %d rc: %d
 488 .It ena%d: could not allocate irq vector: %d
 489 .It ena%d: failed to register interrupt handler for irq %ju: %d
 490 .Pp
 491 IO resources initialization failed.
 492 .br
 493 Interface will not be brought up.
 494 .It ena%d: LRO[%d] Initialization failed!
 495 .Pp
 496 Initialization of the LRO for the RX ring failed.
 497 .It ena%d: failed to alloc buffer for rx queue
 498 .It ena%d: failed to add buffer for rx queue %d
 499 .It ena%d: refilled rx qid %d with only %d mbufs (from %d)
 500 .Pp
 501 Allocation of resources used on RX path failed.
 502 .br
 503 If happened during initialization of the IO queue, the interface will not be
 504 brought up.
 505 .It ena%d: NULL mbuf in rx_info
 506 .Pp
 507 Error occurred while assembling mbuf from descriptors.
 508 .It ena%d: tx_info doesn't have valid mbuf
 509 .It ena%d: Invalid req_id: %hu
 510 .It ena%d: failed to prepare tx bufs
 511 .Pp
 512 Error occurred while preparing a packet for transmission.
 513 .It ena%d: ioctl promisc/allmulti
 514 .Pp
 515 IOCTL request for the device to work in promiscuous/allmulti mode.
 516 .br
 517 See
 518 .Xr ifconfig 8
 519 for more details.
 520 .El
 521 .Sh SUPPORT
 522 If an issue is identified with the released source code with a supported
 523 adapter, please email the specific information related to the issue to
 524 .Aq Mt mk@semihalf.com ,
 525 .Aq Mt dgr@semihalf.com
 526 and
 527 .Aq Mt mw@semihalf.com .
 528 .Sh SEE ALSO
 529 .Xr netmap 4 ,
 530 .Xr vlan 4 ,
 531 .Xr ifconfig 8
 532 .Sh HISTORY
 533 The
 534 .Nm
 535 driver first appeared in
 536 .Fx 11.1 .
 537 .Sh AUTHORS
 538 The
 539 .Nm
 540 driver was written by
 541 .An Semihalf .