d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

ena: introduce documentation

Browse Source 
Signed-off-by: Alexander Matushevsky <matua@amazon.com>
Signed-off-by: Jan Medala <jan@semihalf.com>
Signed-off-by: Jakub Palider <jpa@semihalf.com>
This commit is contained in:
Jan Medala 2016-03-17 15:31:15 +01:00 committed by Thomas Monjalon
parent 78a38edf66
commit cf8a122c29
4 changed files with 318 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
MAINTAINERS
View File

@ -261,6 +261,14 @@ Linux AF_PACKET
M: John W. Linville <linville@tuxdriver.com> M: John W. Linville <linville@tuxdriver.com>
F: drivers/net/af_packet/ F: drivers/net/af_packet/
Amazon ENA
M: Jan Medala <jan@semihalf.com>
M: Jakub Palider <jpa@semihalf.com>
M: Netanel Belgazal <netanel@amazon.com>
M: Evgeny Schemeilin <evgenys@amazon.com>
F: drivers/net/ena/
F: doc/guides/nics/ena.rst
Chelsio cxgbe Chelsio cxgbe
M: Rahul Lakkireddy <rahul.lakkireddy@chelsio.com> M: Rahul Lakkireddy <rahul.lakkireddy@chelsio.com>
F: drivers/net/cxgbe/ F: drivers/net/cxgbe/

251
doc/guides/nics/ena.rst Normal file
View File

@ -0,0 +1,251 @@
.. BSD LICENSE
Copyright (c) 2015-2016 Amazon.com, Inc. or its affiliates.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
* Neither the name of Amazon.com, Inc. nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
ENA Poll Mode Driver
====================
The ENA PMD is a DPDK poll-mode driver for the Amazon Elastic
Network Adapter (ENA) family.
Overview
--------
The ENA driver exposes a lightweight management interface with a
minimal set of memory mapped registers and an extendable command set
through an Admin Queue.
The driver supports a wide range of ENA adapters, is link-speed
independent (i.e., the same driver is used for 10GbE, 25GbE, 40GbE,
etc.), and it negotiates and supports an extendable feature set.
ENA adapters allow high speed and low overhead Ethernet traffic
processing by providing a dedicated Tx/Rx queue pair per CPU core.
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.
Some of the ENA devices support a working mode called Low-latency
Queue (LLQ), which saves several more microseconds.
Management Interface
--------------------
ENA management interface is exposed by means of:
* Device Registers
* Admin Queue (AQ) and Admin Completion Queue (ACQ)
ENA device memory-mapped PCIe space for registers (MMIO registers)
are accessed only during driver initialization and are not involved
in further normal device operation.
AQ is used for submitting management commands, and the
results/responses are reported asynchronously through ACQ.
ENA introduces a very small set of management commands with room for
vendor-specific extensions. Most of the management operations are
framed in a generic Get/Set feature command.
The following admin queue commands are supported:
* Create I/O submission queue
* Create I/O completion queue
* Destroy I/O submission queue
* Destroy I/O completion queue
* Get feature
* Set feature
* Get statistics
Refer to ``ena_admin_defs.h`` for the list of supported Get/Set Feature
properties.
Data Path Interface
-------------------
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
with it.
The SQs and CQs are implemented as descriptor rings in contiguous
physical memory.
Refer to ``ena_eth_io_defs.h`` for the detailed structure of the descriptor
The driver supports multi-queue for both Tx and Rx.
Configuration information
-------------------------
**DPDK Configuration Parameters**
The following configuration options are available for the ENA PMD:
* **CONFIG_RTE_LIBRTE_ENA_PMD** (default y): Enables or disables inclusion
of the ENA PMD driver in the DPDK compilation.
* **CONFIG_RTE_LIBRTE_ENA_DEBUG_INIT** (default y): Enables or disables debug
logging of device initialization within the ENA PMD driver.
* **CONFIG_RTE_LIBRTE_ENA_DEBUG_RX** (default n): Enables or disables debug
logging of RX logic within the ENA PMD driver.
* **CONFIG_RTE_LIBRTE_ENA_DEBUG_TX** (default n): Enables or disables debug
logging of TX logic within the ENA PMD driver.
* **CONFIG_RTE_LIBRTE_ENA_COM_DEBUG** (default n): Enables or disables debug
logging of low level tx/rx logic in ena_com(base) within the ENA PMD driver.
**ENA Configuration Parameters**
* **Number of Queues**
This is the requested number of queues upon initialization, however, the actual
number of receive and transmit queues to be created will be the minimum between
the maximal number supported by the device and number of queues requested.
* **Size of Queues**
This is the requested size of receive/transmit queues, while the actual size
will be the minimum between the requested size and the maximal receive/transmit
supported by the device.
Building DPDK
-------------
See the :ref:`DPDK Getting Started Guide for Linux <linux_gsg>` for
instructions on how to build DPDK.
By default the ENA PMD library will be built into the DPDK library.
For configuring and using UIO and VFIO frameworks, please also refer :ref:`the
documentation that comes with DPDK suite <linux_gsg>`.
Supported ENA adapters
----------------------
Current ENA PMD supports the following ENA adapters including:
* ``1d0f:ec20`` - ENA VF
* ``1d0f:ec21`` - ENA VF with LLQ support
Supported Operating Systems
---------------------------
Any Linux distribution fulfilling the conditions described in ``System Requirements``
section of :ref:`the DPDK documentation <linux_gsg>` or refer to *DPDK Release Notes*.
Supported features
------------------
* Jumbo frames up to 9K
* Port Hardware Statistics
* IPv4/TCP/UDP checksum offload
* TSO offload
* Multiple receive and transmit queues
* RSS
* Low Latency Queue for Tx
Unsupported features
--------------------
The features supported by the device and not yet supported by this PMD include:
* Asynchronous Event Notification Queue (AENQ)
Prerequisites
-------------
#. Prepare the system as recommended by DPDK suite. This includes environment
variables, hugepages configuration, tool-chains and configuration
#. Insert igb_uio kernel module using the command 'modprobe igb_uio'
#. Bind the intended ENA device to igb_uio module
At this point the system should be ready to run DPDK applications. Once the
application runs to completion, the ENA can be detached from igb_uio if necessary.
Usage example
-------------
This section demonstrates how to launch **testpmd** with Amazon ENA
devices managed by librte_pmd_ena.
#. Load the kernel modules:
.. code-block:: console
modprobe uio
insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
.. note::
Currently Amazon ENA PMD driver depends on igb_uio user space I/O kernel module
#. Mount and request huge pages:
.. code-block:: console
mount -t hugetlbfs nodev /mnt/hugepages
echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
#. Bind UIO driver to ENA device (using provided by DPDK binding tool):
.. code-block:: console
./tools/dpdk_nic_bind.py --bind=igb_uio 0000:02:00.1
#. Start testpmd with basic parameters:
.. code-block:: console
./x86_64-native-linuxapp-gcc/app/testpmd -c 0xf -n 4 -- -i
Example output:
.. code-block:: console
[...]
EAL: PCI device 0000:02:00.1 on NUMA socket -1
EAL: probe driver: 1d0f:ec20 rte_ena_pmd
EAL: PCI memory mapped at 0x7f9b6c400000
PMD: eth_ena_dev_init(): Initializing 0:2:0.1
Interactive-mode selected
Configuring Port 0 (socket 0)
Port 0: 00:00:00:11:00:01
Checking link statuses...
Port 0 Link Up - speed 10000 Mbps - full-duplex
Done
testpmd>

1
doc/guides/nics/index.rst
View File

@ -39,6 +39,7 @@ Network Interface Controller Drivers
bnx2x bnx2x
cxgbe cxgbe
e1000em e1000em
ena
enic enic
fm10k fm10k
i40e i40e

116
doc/guides/nics/overview.rst
View File

@ -74,74 +74,74 @@ Most of these differences are summarized below.
.. table:: Features availability in networking drivers .. table:: Features availability in networking drivers
==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
Feature a b b b c e e i i i i i i i i i i f f m m m n n p r s v v v x Feature a b b b c e e e i i i i i i i i i i f f m m m n n p r s v v v x
f n n o x 1 n 4 4 4 4 g g x x x x m m l l p f u c i z i i m e f n n o x 1 n n 4 4 4 4 g g x x x x m m l l p f u c i z i i m e
p x x n g 0 i 0 0 0 0 b b g g g g 1 1 x x i p l a n e r r x n p x x n g 0 a i 0 0 0 0 b b g g g g 1 1 x x i p l a n e r r x n
a 2 2 d b 0 c e e e e v b b b b 0 0 4 5 p l p g d t t n v a 2 2 d b 0 c e e e e v b b b b 0 0 4 5 p l p g d t t n v
c x x i e 0 . v v f e e e e k k e a i i e i c x x i e 0 . v v f e e e e k k e a i i e i
k v n . f f . v v . t o o t r k v n . f f . v v . t o o t r
e f g . . . f f . a . 3 t e f g . . . f f . a . 3 t
t v v v v v 2 v t v v v v v 2 v
e e e e e e e e e e e e
c c c c c c c c c c c c
==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
link status X X X X link status X X X X
link status event X X link status event X X
Rx interrupt X X X X Rx interrupt X X X X
queue start/stop X X X X X X queue start/stop X X X X X X X
MTU update X MTU update X X
jumbo frame X X X X X jumbo frame X X X X X X
scattered Rx X X X X X X scattered Rx X X X X X X X
LRO LRO
TSO X X X X X TSO X X X X X X
promiscuous mode X X X X X X promiscuous mode X X X X X X
allmulticast mode X X X X X X allmulticast mode X X X X X X
unicast MAC filter X X X X unicast MAC filter X X X X
multicast MAC filter X X X X multicast MAC filter X X X X
RSS hash X X X X X RSS hash X X X X X X
RSS key update X X X X RSS key update X X X X X
RSS reta update X X X X RSS reta update X X X X X
VMDq X X VMDq X X
SR-IOV X X SR-IOV X X X
DCB X X DCB X X
VLAN filter X X X X VLAN filter X X X X
ethertype filter X X ethertype filter X X
n-tuple filter n-tuple filter
SYN filter SYN filter
tunnel filter X X tunnel filter X X
flexible filter flexible filter
hash filter X X X X hash filter X X X X
flow director X X flow director X X
flow control X X X flow control X X X
rate limitation rate limitation
traffic mirroring X X traffic mirroring X X
CRC offload X X X CRC offload X X X X
VLAN offload X X X VLAN offload X X X X
QinQ offload X X QinQ offload X X
L3 checksum offload X X X L3 checksum offload X X X X
L4 checksum offload X X X L4 checksum offload X X X X
inner L3 checksum X X inner L3 checksum X X X
inner L4 checksum X X inner L4 checksum X X X
packet type parsing X X X packet type parsing X X X
timesync X X timesync X X
basic stats X X X X X X basic stats X X X X X X X
extended stats X X X X extended stats X X X X X
stats per queue X X stats per queue X X
EEPROM dump EEPROM dump
registers dump registers dump
multiprocess aware X X X X multiprocess aware X X X X
BSD nic_uio X X X X X BSD nic_uio X X X X X
Linux UIO X X X X X Linux UIO X X X X X X
Linux VFIO X X X X X Linux VFIO X X X X X
other kdrv X other kdrv X
ARMv7 ARMv7
ARMv8 ARMv8
Power8 Power8
TILE-Gx TILE-Gx
x86-32 X X X X X x86-32 X X X X X X
x86-64 X X X X X X x86-64 X X X X X X X
usage doc X X usage doc X X
design doc design doc
perf doc perf doc
==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =