ENA(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 ENA(4) — the FreeBSD kernel driver for the Elastic Network Adapter (ENA) family 💖

okay bestie, sit down, hydrate, and let me tell you about ena — the FreeBSD kernel driver for the Elastic Network Adapter (ENA) family. it's giving networking royalty, fr fr. 👑

✨ SYNOPSIS ✨

want this baby baked straight into your kernel? drop this line into your kernel config file:

device ena

or, if you'd rather load it as a module at boot time (so valid, so flexible 🫶), put this in loader.conf(5):

if_ena_load="YES"

🌸 DESCRIPTION 🌸

The ENA is a networking interface designed to make good use of modern CPU features and system architectures. like, it knows your CPU is hot and it wants to use every bit of it. 💅

The ENA device exposes a lightweight management interface with a minimal set of memory mapped registers and extendable command set through an Admin Queue. lowkey elegant, ngl.

The driver supports a range of ENA devices, is link-speed independent (i.e., the same driver is used for 10GbE, 25GbE, 40GbE, etc.), and has a negotiated and extendable feature set. one driver, many speeds — it's giving versatility, periodt.

Some ENA devices support SR-IOV. This driver is used for both the SR-IOV Physical Function (PF) and Virtual Function (VF) devices. yes, it does both jobs. main character energy. 👑

The ENA devices enable high speed and low overhead network traffic processing by providing multiple Tx/Rx queue pairs (the maximum number is advertised by the device via the Admin Queue), a dedicated MSI-X interrupt vector per Tx/Rx queue pair, and CPU cacheline optimized data placement. the way it places data in cacheline-optimized spots... obsessed. 🔥

The ena driver supports industry standard TCP/IP offload features such as checksum offload and TCP transmit segmentation offload (TSO). Receive-side scaling (RSS) is supported for multi-core scaling. multi-core girlies, this one's for you. 🌈

The ena driver and its corresponding devices implement health monitoring mechanisms such as watchdog, enabling the device and driver to recover in a manner transparent to the application, as well as debug logs. it heals itself and you don't even notice. iconic.

Some of the ENA devices support a working mode called Low-latency Queue (LLQ), which saves several more microseconds. This feature will be implemented for driver in future releases. so... not yet, bestie. it's coming. ⭐

🦋 HARDWARE 🦋

Supported PCI vendor ID/device IDs:

  • 1d0f:0ec2 — ENA PF
  • 1d0f:1ec2 — ENA PF with LLQ support
  • 1d0f:ec20 — ENA VF
  • 1d0f:ec21 — ENA VF with LLQ support

💀 DIAGNOSTICS 💀

this is the part where things get real. every one of these messages is the driver telling you what's up. no skipping, bestie — we read them all.

🔧 Device initialization phase:

  • ena%d: failed to init mmio read less

Error occurred during initialization of the mmio register read request.

  • ena%d: Can not reset device

Device could not be reset. Device may not be responding or is already during reset.

  • ena%d: device version is too low

Version of the controller is too old and it is not supported by the driver.

  • ena%d: Invalid dma width value %d

The controller is able to request dma transaction width. Device stopped responding or it demanded invalid value.

  • ena%d: Can not initialize ena admin queue with device

Initialization of the Admin Queue failed. Device may not be responding or there was a problem with initialization of the resources.

  • ena%d: Cannot get attribute for ena device rc: %d

Failed to get attributes of the device from the controller.

  • ena%d: Cannot configure aenq groups rc: %d

Errors occurred when trying to configure AENQ groups.

🔧 Driver initialisation/shutdown phase:

  • ena%d: PCI resource allocation failed!
  • ena%d: allocating ena_dev failed
  • ena%d: failed to pmap registers bar
  • ena%d: Error while setting up bufring
  • ena%d: Error with initialization of IO rings
  • ena%d: can not allocate ifnet structure
  • ena%d: Error with network interface setup
  • ena%d: Failed to enable and set the admin interrupts
  • ena%d: Failed to allocate %d, vectors %d
  • ena%d: Failed to enable MSIX, vectors %d rc %d
  • ena%d: Error with MSI-X enablement
  • ena%d: could not allocate irq vector: %d
  • ena%d: Unable to allocate bus resource: registers

Resource allocation failed when initializing the device. Driver will not be attached.

  • ena%d: ENA device init failed (err: %d)

Device initialization failed. Driver will not be attached.

  • ena%d: could not activate irq vector: %d

Error occurred when trying to activate interrupt vectors for Admin Queue.

  • ena%d: failed to register interrupt handler for irq %ju: %d

Error occurred when trying to register Admin Queue interrupt handler.

  • ena%d: Cannot setup mgmnt queue intr

Error occurred during configuration of the Admin Queue interrupts.

  • ena%d: Enable MSI-X failed

Configuration of the MSI-X for Admin Queue failed. There could be lack of resources or interrupts could not have been configured. Driver will not be attached.

  • ena%d: VLAN is in use, detach first

VLANs are being used when trying to detach the driver. VLANs must be detached first and then detach routine have to be called again.

  • ena%d: Unmapped RX DMA tag associations
  • ena%d: Unmapped TX DMA tag associations

Error occurred when trying to destroy RX/TX DMA tag.

  • ena%d: Cannot init RSS
  • ena%d: Cannot fill indirect table
  • ena%d: Cannot fill indirect table
  • ena%d: Cannot fill hash function
  • ena%d: Cannot fill hash control
  • ena%d: WARNING: RSS was not properly initialized, it will affect bandwidth

Error occurred during initialization of one of RSS resources. The device will work with reduced performance because all RX packets will be passed to queue 0 and there will be no hash information.

  • ena%d: failed to tear down irq: %d
  • ena%d: dev has no parent while releasing res for irq: %d

Release of the interrupts failed.

🔍 Additional diagnostic:

  • ena%d: Cannot get attribute for ena device

This message appears when trying to change MTU and driver is unable to get attributes from the device.

  • ena%d: Invalid MTU setting. new_mtu: %d

Requested MTU value is not supported and will not be set.

  • ena%d: keep alive watchdog timeout

Device stopped responding and will be reset.

  • ena%d: Found a Tx that wasn't completed on time, qid %d, index %d.

Packet was pushed to the NIC but not sent within given time limit. It may be caused by hang of the IO queue.

  • ena%d: The number of lost tx completion is aboce the threshold (%d > %d). Reset the device

If too many Tx wasn't completed on time the device is going to be reset. It may be caused by hanged queue or device.

  • ena%d: trigger reset is on

Device will be reset. Reset is triggered either by watchdog or if too many TX packets were not completed on time.

  • ena%d: invalid value recvd

Link status received from the device in the AENQ handler is invalid.

  • ena%d: Allocation for Tx Queue %u failed
  • ena%d: Allocation for Rx Queue %u failed
  • ena%d: Unable to create Rx DMA map for buffer %d
  • ena%d: Failed to create io TX queue #%d rc: %d
  • ena%d: Failed to get TX queue handlers. TX queue num %d rc: %d
  • ena%d: Failed to create io RX queue[%d] rc: %d
  • ena%d: Failed to get RX queue handlers. RX queue num %d rc: %d
  • ena%d: failed to request irq
  • ena%d: could not allocate irq vector: %d
  • ena%d: failed to register interrupt handler for irq %ju: %d

IO resources initialization failed. Interface will not be brought up.

  • ena%d: LRO[%d] Initialization failed!

Initialization of the LRO for the RX ring failed.

  • ena%d: failed to alloc buffer for rx queue
  • ena%d: failed to add buffer for rx queue %d
  • ena%d: refilled rx queue %d with %d pages only

Allocation of resources used on RX path failed. If happened during initialization of the IO queue, the interface will not be brought up.

  • ena%d: ioctl promisc/allmulti

IOCTL request for the device to work in promiscuous/allmulti mode. See ifconfig(8) for more details.

  • ena%d: too many fragments. Last fragment: %d!

Packet with unsupported number of segments was queued for sending to the device. Packet will be dropped.

🫶 SUPPORT 🫶

If an issue is identified with the released source code with a supported adapter, please email the specific information related to the issue to ⟨mk@semihalf.com⟩ and ⟨mw@semihalf.com⟩. like, actually email them, they wanna help you, bestie. 💜

👀 SEE ALSO 👀

vlan(4), ifconfig(8)

🎀 AUTHORS 🎀

The ena driver was written by Semihalf.

and that's the whole page, babe. this one came from Debian, dated August 16, 2017, and it lives at section 4 of the Kernel Interfaces Manual — ENA(4), forever iconic. go configure your NIC and slay. 💅✨

📦 where this page comes from