Commit 511c537b authored by Shay Agroskin's avatar Shay Agroskin Committed by David S. Miller

net: ena: fix RST format in ENA documentation file

The documentation file used to be written in markdown format but was
converted to reStructuredText (rst).

The converted file doesn't keep up with rst format requirements which
results in hard-to-read text.

This patch fixes the formatting of the file. The patch also
* Highlights and emphasizes some lines to improve readability
* Rephrases some hard-to-understand text
* Updates outdated function descriptions.
* Removes TSO description which falsely claims the driver supports it
Signed-off-by: default avatarShay Agroskin <shayagr@amazon.com>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent 15efff76
...@@ -11,12 +11,12 @@ ENA is a networking interface designed to make good use of modern CPU ...@@ -11,12 +11,12 @@ ENA is a networking interface designed to make good use of modern CPU
features and system architectures. features and system architectures.
The ENA device exposes a lightweight management interface with a The ENA device exposes a lightweight management interface with a
minimal set of memory mapped registers and extendable command set minimal set of memory mapped registers and extendible command set
through an Admin Queue. through an Admin Queue.
The driver supports a range of ENA devices, is link-speed independent 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 (i.e., the same driver is used for 10GbE, 25GbE, 40GbE, etc), and has
a negotiated and extendable feature set. a negotiated and extendible feature set.
Some ENA devices support SR-IOV. This driver is used for both the Some ENA devices support SR-IOV. This driver is used for both the
SR-IOV Physical Function (PF) and Virtual Function (VF) devices. SR-IOV Physical Function (PF) and Virtual Function (VF) devices.
...@@ -27,9 +27,9 @@ is advertised by the device via the Admin Queue), a dedicated MSI-X ...@@ -27,9 +27,9 @@ is advertised by the device via the Admin Queue), a dedicated MSI-X
interrupt vector per Tx/Rx queue pair, adaptive interrupt moderation, interrupt vector per Tx/Rx queue pair, adaptive interrupt moderation,
and CPU cacheline optimized data placement. and CPU cacheline optimized data placement.
The ENA driver supports industry standard TCP/IP offload features such The ENA driver supports industry standard TCP/IP offload features such as
as checksum offload and TCP transmit segmentation offload (TSO). checksum offload. Receive-side scaling (RSS) is supported for multi-core
Receive-side scaling (RSS) is supported for multi-core scaling. scaling.
The ENA driver and its corresponding devices implement health The ENA driver and its corresponding devices implement health
monitoring mechanisms such as watchdog, enabling the device and driver monitoring mechanisms such as watchdog, enabling the device and driver
...@@ -38,22 +38,20 @@ debug logs. ...@@ -38,22 +38,20 @@ debug logs.
Some of the ENA devices support a working mode called Low-latency Some of the ENA devices support a working mode called Low-latency
Queue (LLQ), which saves several more microseconds. Queue (LLQ), which saves several more microseconds.
ENA Source Code Directory Structure ENA Source Code Directory Structure
=================================== ===================================
================= ====================================================== ================= ======================================================
ena_com.[ch] Management communication layer. This layer is ena_com.[ch] Management communication layer. This layer is
responsible for the handling all the management responsible for the handling all the management
(admin) communication between the device and the (admin) communication between the device and the
driver. driver.
ena_eth_com.[ch] Tx/Rx data path. ena_eth_com.[ch] Tx/Rx data path.
ena_admin_defs.h Definition of ENA management interface. ena_admin_defs.h Definition of ENA management interface.
ena_eth_io_defs.h Definition of ENA data path interface. ena_eth_io_defs.h Definition of ENA data path interface.
ena_common_defs.h Common definitions for ena_com layer. ena_common_defs.h Common definitions for ena_com layer.
ena_regs_defs.h Definition of ENA PCI memory-mapped (MMIO) registers. ena_regs_defs.h Definition of ENA PCI memory-mapped (MMIO) registers.
ena_netdev.[ch] Main Linux kernel driver. ena_netdev.[ch] Main Linux kernel driver.
ena_syfsfs.[ch] Sysfs files.
ena_ethtool.c ethtool callbacks. ena_ethtool.c ethtool callbacks.
ena_pci_id_tbl.h Supported device IDs. ena_pci_id_tbl.h Supported device IDs.
================= ====================================================== ================= ======================================================
...@@ -69,7 +67,7 @@ ENA management interface is exposed by means of: ...@@ -69,7 +67,7 @@ ENA management interface is exposed by means of:
- Asynchronous Event Notification Queue (AENQ) - Asynchronous Event Notification Queue (AENQ)
ENA device MMIO Registers are accessed only during driver ENA device MMIO Registers are accessed only during driver
initialization and are not involved in further normal device initialization and are not used during further normal device
operation. operation.
AQ is used for submitting management commands, and the AQ is used for submitting management commands, and the
...@@ -100,28 +98,27 @@ group may have multiple syndromes, as shown below ...@@ -100,28 +98,27 @@ group may have multiple syndromes, as shown below
The events are: The events are:
==================== =============== ==================== ===============
Group Syndrome Group Syndrome
==================== =============== ==================== ===============
Link state change **X** Link state change **X**
Fatal error **X** Fatal error **X**
Notification Suspend traffic Notification Suspend traffic
Notification Resume traffic Notification Resume traffic
Keep-Alive **X** Keep-Alive **X**
==================== =============== ==================== ===============
ACQ and AENQ share the same MSI-X vector. ACQ and AENQ share the same MSI-X vector.
Keep-Alive is a special mechanism that allows monitoring of the Keep-Alive is a special mechanism that allows monitoring the device's health.
device's health. The driver maintains a watchdog (WD) handler which, A Keep-Alive event is delivered by the device every second.
if fired, logs the current state and statistics then resets and The driver maintains a watchdog (WD) handler which logs the current state and
restarts the ENA device and driver. A Keep-Alive event is delivered by statistics. If the keep-alive events aren't delivered as expected the WD resets
the device every second. The driver re-arms the WD upon reception of a the device and the driver.
Keep-Alive event. A missed Keep-Alive event causes the WD handler to
fire.
Data Path Interface Data Path Interface
=================== ===================
I/O operations are based on Tx and Rx Submission Queues (Tx SQ and Rx I/O operations are based on Tx and Rx Submission Queues (Tx SQ and Rx
SQ correspondingly). Each SQ has a completion queue (CQ) associated SQ correspondingly). Each SQ has a completion queue (CQ) associated
with it. with it.
...@@ -131,26 +128,24 @@ physical memory. ...@@ -131,26 +128,24 @@ physical memory.
The ENA driver supports two Queue Operation modes for Tx SQs: The ENA driver supports two Queue Operation modes for Tx SQs:
- Regular mode - **Regular mode:**
In this mode the Tx SQs reside in the host's memory. The ENA
device fetches the ENA Tx descriptors and packet data from host
memory.
* In this mode the Tx SQs reside in the host's memory. The ENA - **Low Latency Queue (LLQ) mode or "push-mode":**
device fetches the ENA Tx descriptors and packet data from host In this mode the driver pushes the transmit descriptors and the
memory. first 128 bytes of the packet directly to the ENA device memory
space. The rest of the packet payload is fetched by the
device. For this operation mode, the driver uses a dedicated PCI
device memory BAR, which is mapped with write-combine capability.
- Low Latency Queue (LLQ) mode or "push-mode". **Note that** not all ENA devices support LLQ, and this feature is negotiated
with the device upon initialization. If the ENA device does not
* In this mode the driver pushes the transmit descriptors and the support LLQ mode, the driver falls back to the regular mode.
first 128 bytes of the packet directly to the ENA device memory
space. The rest of the packet payload is fetched by the
device. For this operation mode, the driver uses a dedicated PCI
device memory BAR, which is mapped with write-combine capability.
The Rx SQs support only the regular mode. The Rx SQs support only the regular mode.
Note: Not all ENA devices support LLQ, and this feature is negotiated
with the device upon initialization. If the ENA device does not
support LLQ mode, the driver falls back to the regular mode.
The driver supports multi-queue for both Tx and Rx. This has various The driver supports multi-queue for both Tx and Rx. This has various
benefits: benefits:
...@@ -165,6 +160,7 @@ benefits: ...@@ -165,6 +160,7 @@ benefits:
Interrupt Modes Interrupt Modes
=============== ===============
The driver assigns a single MSI-X vector per queue pair (for both Tx The driver assigns a single MSI-X vector per queue pair (for both Tx
and Rx directions). The driver assigns an additional dedicated MSI-X vector and Rx directions). The driver assigns an additional dedicated MSI-X vector
for management (for ACQ and AENQ). for management (for ACQ and AENQ).
...@@ -190,20 +186,21 @@ unmasked by the driver after NAPI processing is complete. ...@@ -190,20 +186,21 @@ unmasked by the driver after NAPI processing is complete.
Interrupt Moderation Interrupt Moderation
==================== ====================
ENA driver and device can operate in conventional or adaptive interrupt ENA driver and device can operate in conventional or adaptive interrupt
moderation mode. moderation mode.
In conventional mode the driver instructs device to postpone interrupt **In conventional mode** the driver instructs device to postpone interrupt
posting according to static interrupt delay value. The interrupt delay posting according to static interrupt delay value. The interrupt delay
value can be configured through ethtool(8). The following ethtool value can be configured through `ethtool(8)`. The following `ethtool`
parameters are supported by the driver: tx-usecs, rx-usecs parameters are supported by the driver: ``tx-usecs``, ``rx-usecs``
In adaptive interrupt moderation mode the interrupt delay value is **In adaptive interrupt** moderation mode the interrupt delay value is
updated by the driver dynamically and adjusted every NAPI cycle updated by the driver dynamically and adjusted every NAPI cycle
according to the traffic nature. according to the traffic nature.
Adaptive coalescing can be switched on/off through ethtool(8) Adaptive coalescing can be switched on/off through `ethtool(8)`'s
adaptive_rx on|off parameter. :code:`adaptive_rx on|off` parameter.
More information about Adaptive Interrupt Moderation (DIM) can be found in More information about Adaptive Interrupt Moderation (DIM) can be found in
Documentation/networking/net_dim.rst Documentation/networking/net_dim.rst
...@@ -214,17 +211,10 @@ The rx_copybreak is initialized by default to ENA_DEFAULT_RX_COPYBREAK ...@@ -214,17 +211,10 @@ The rx_copybreak is initialized by default to ENA_DEFAULT_RX_COPYBREAK
and can be configured by the ETHTOOL_STUNABLE command of the and can be configured by the ETHTOOL_STUNABLE command of the
SIOCETHTOOL ioctl. SIOCETHTOOL ioctl.
SKB
===
The driver-allocated SKB for frames received from Rx handling using
NAPI context. The allocation method depends on the size of the packet.
If the frame length is larger than rx_copybreak, napi_get_frags()
is used, otherwise netdev_alloc_skb_ip_align() is used, the buffer
content is copied (by CPU) to the SKB, and the buffer is recycled.
Statistics Statistics
========== ==========
The user can obtain ENA device and driver statistics using ethtool.
The user can obtain ENA device and driver statistics using `ethtool`.
The driver can collect regular or extended statistics (including The driver can collect regular or extended statistics (including
per-queue stats) from the device. per-queue stats) from the device.
...@@ -232,22 +222,23 @@ In addition the driver logs the stats to syslog upon device reset. ...@@ -232,22 +222,23 @@ In addition the driver logs the stats to syslog upon device reset.
MTU MTU
=== ===
The driver supports an arbitrarily large MTU with a maximum that is The driver supports an arbitrarily large MTU with a maximum that is
negotiated with the device. The driver configures MTU using the negotiated with the device. The driver configures MTU using the
SetFeature command (ENA_ADMIN_MTU property). The user can change MTU SetFeature command (ENA_ADMIN_MTU property). The user can change MTU
via ip(8) and similar legacy tools. via `ip(8)` and similar legacy tools.
Stateless Offloads Stateless Offloads
================== ==================
The ENA driver supports: The ENA driver supports:
- TSO over IPv4/IPv6
- TSO with ECN
- IPv4 header checksum offload - IPv4 header checksum offload
- TCP/UDP over IPv4/IPv6 checksum offloads - TCP/UDP over IPv4/IPv6 checksum offloads
RSS RSS
=== ===
- The ENA device supports RSS that allows flexible Rx traffic - The ENA device supports RSS that allows flexible Rx traffic
steering. steering.
- Toeplitz and CRC32 hash functions are supported. - Toeplitz and CRC32 hash functions are supported.
...@@ -260,41 +251,42 @@ RSS ...@@ -260,41 +251,42 @@ RSS
function delivered in the Rx CQ descriptor is set in the received function delivered in the Rx CQ descriptor is set in the received
SKB. SKB.
- The user can provide a hash key, hash function, and configure the - The user can provide a hash key, hash function, and configure the
indirection table through ethtool(8). indirection table through `ethtool(8)`.
DATA PATH DATA PATH
========= =========
Tx Tx
-- --
ena_start_xmit() is called by the stack. This function does the following: :code:`ena_start_xmit()` is called by the stack. This function does the following:
- Maps data buffers (skb->data and frags). - Maps data buffers (``skb->data`` and frags).
- Populates ena_buf for the push buffer (if the driver and device are - Populates ``ena_buf`` for the push buffer (if the driver and device are
in push mode.) in push mode).
- Prepares ENA bufs for the remaining frags. - Prepares ENA bufs for the remaining frags.
- Allocates a new request ID from the empty req_id ring. The request - Allocates a new request ID from the empty ``req_id`` ring. The request
ID is the index of the packet in the Tx info. This is used for ID is the index of the packet in the Tx info. This is used for
out-of-order TX completions. out-of-order Tx completions.
- Adds the packet to the proper place in the Tx ring. - Adds the packet to the proper place in the Tx ring.
- Calls ena_com_prepare_tx(), an ENA communication layer that converts - Calls :code:`ena_com_prepare_tx()`, an ENA communication layer that converts
the ena_bufs to ENA descriptors (and adds meta ENA descriptors as the ``ena_bufs`` to ENA descriptors (and adds meta ENA descriptors as
needed.) needed).
* This function also copies the ENA descriptors and the push buffer * This function also copies the ENA descriptors and the push buffer
to the Device memory space (if in push mode.) to the Device memory space (if in push mode).
- Writes doorbell to the ENA device. - Writes a doorbell to the ENA device.
- When the ENA device finishes sending the packet, a completion - When the ENA device finishes sending the packet, a completion
interrupt is raised. interrupt is raised.
- The interrupt handler schedules NAPI. - The interrupt handler schedules NAPI.
- The ena_clean_tx_irq() function is called. This function handles the - The :code:`ena_clean_tx_irq()` function is called. This function handles the
completion descriptors generated by the ENA, with a single completion descriptors generated by the ENA, with a single
completion descriptor per completed packet. completion descriptor per completed packet.
* req_id is retrieved from the completion descriptor. The tx_info of * ``req_id`` is retrieved from the completion descriptor. The ``tx_info`` of
the packet is retrieved via the req_id. The data buffers are the packet is retrieved via the ``req_id``. The data buffers are
unmapped and req_id is returned to the empty req_id ring. unmapped and ``req_id`` is returned to the empty ``req_id`` ring.
* The function stops when the completion descriptors are completed or * The function stops when the completion descriptors are completed or
the budget is reached. the budget is reached.
...@@ -303,12 +295,11 @@ Rx ...@@ -303,12 +295,11 @@ Rx
- When a packet is received from the ENA device. - When a packet is received from the ENA device.
- The interrupt handler schedules NAPI. - The interrupt handler schedules NAPI.
- The ena_clean_rx_irq() function is called. This function calls - The :code:`ena_clean_rx_irq()` function is called. This function calls
ena_rx_pkt(), an ENA communication layer function, which returns the :code:`ena_com_rx_pkt()`, an ENA communication layer function, which returns the
number of descriptors used for a new unhandled packet, and zero if number of descriptors used for a new packet, and zero if
no new packet is found. no new packet is found.
- Then it calls the ena_clean_rx_irq() function. - :code:`ena_rx_skb()` checks packet length:
- ena_eth_rx_skb() checks packet length:
* If the packet is small (len < rx_copybreak), the driver allocates * If the packet is small (len < rx_copybreak), the driver allocates
a SKB for the new packet, and copies the packet payload into the a SKB for the new packet, and copies the packet payload into the
...@@ -317,9 +308,10 @@ Rx ...@@ -317,9 +308,10 @@ Rx
- In this way the original data buffer is not passed to the stack - In this way the original data buffer is not passed to the stack
and is reused for future Rx packets. and is reused for future Rx packets.
* Otherwise the function unmaps the Rx buffer, then allocates the * Otherwise the function unmaps the Rx buffer, sets the first
new SKB structure and hooks the Rx buffer to the SKB frags. descriptor as `skb`'s linear part and the other descriptors as the
`skb`'s frags.
- The new SKB is updated with the necessary information (protocol, - The new SKB is updated with the necessary information (protocol,
checksum hw verify result, etc.), and then passed to the network checksum hw verify result, etc), and then passed to the network
stack, using the NAPI interface function napi_gro_receive(). stack, using the NAPI interface function :code:`napi_gro_receive()`.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment