ena: introduce documentation
authorJan Medala <jan@semihalf.com>
Thu, 17 Mar 2016 14:31:15 +0000 (15:31 +0100)
committerThomas Monjalon <thomas.monjalon@6wind.com>
Fri, 25 Mar 2016 17:56:43 +0000 (18:56 +0100)
Signed-off-by: Alexander Matushevsky <matua@amazon.com>
Signed-off-by: Jan Medala <jan@semihalf.com>
Signed-off-by: Jakub Palider <jpa@semihalf.com>
MAINTAINERS
doc/guides/nics/ena.rst [new file with mode: 0644]
doc/guides/nics/index.rst
doc/guides/nics/overview.rst

index c7e9fe4..3f6920c 100644 (file)
@@ -261,6 +261,14 @@ Linux AF_PACKET
 M: John W. Linville <linville@tuxdriver.com>
 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
 M: Rahul Lakkireddy <rahul.lakkireddy@chelsio.com>
 F: drivers/net/cxgbe/
diff --git a/doc/guides/nics/ena.rst b/doc/guides/nics/ena.rst
new file mode 100644 (file)
index 0000000..9f93848
--- /dev/null
@@ -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>
index 0b353a8..d060265 100644 (file)
@@ -39,6 +39,7 @@ Network Interface Controller Drivers
     bnx2x
     cxgbe
     e1000em
+    ena
     enic
     fm10k
     i40e
index 2d4f014..28237e9 100644 (file)
@@ -74,74 +74,74 @@ Most of these differences are summarized below.
 
 .. 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
-                        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
-                        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
-                        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
-                        k   v n         . f f       . v v   .               t o o t r
-                        e   f g         .   .       . f f   .               a   . 3 t
-                        t               v   v       v   v   v               2   v
-                                        e   e       e   e   e                   e
-                                        c   c       c   c   c                   c
-   ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
-   link status                  X     X X                                   X
-   link status event                  X X
-   Rx interrupt                       X X X X
-   queue start/stop             X     X X X X                               X
-   MTU update                   X
-   jumbo frame                  X     X X X X
-   scattered Rx                 X     X X X X                               X
+   ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+   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
+                        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
+                        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
+                        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
+                        k   v n           . f f       . v v   .               t o o t r
+                        e   f g           .   .       . f f   .               a   . 3 t
+                        t                 v   v       v   v   v               2   v
+                                          e   e       e   e   e                   e
+                                          c   c       c   c   c                   c
+   ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+   link status                  X       X X                                   X
+   link status event                    X X
+   Rx interrupt                         X X X X
+   queue start/stop             X     X X X X                               X
+   MTU update                   X   X
+   jumbo frame                  X     X X X X
+   scattered Rx                 X     X X X X                               X
    LRO
-   TSO                          X     X X X X
-   promiscuous mode             X     X X X X                               X
-   allmulticast mode            X     X X X X                               X
-   unicast MAC filter                 X X X X
-   multicast MAC filter               X X X X
-   RSS hash                     X     X X X X
-   RSS key update                     X X X X
-   RSS reta update                    X X X X
-   VMDq                               X X
-   SR-IOV                             X X
-   DCB                                X X
-   VLAN filter                        X X X X
-   ethertype filter                   X X
+   TSO                          X     X X X X
+   promiscuous mode             X       X X X X                               X
+   allmulticast mode            X       X X X X                               X
+   unicast MAC filter                   X X X X
+   multicast MAC filter                 X X X X
+   RSS hash                     X     X X X X
+   RSS key update                     X X X X
+   RSS reta update                    X X X X
+   VMDq                                 X X
+   SR-IOV                             X X
+   DCB                                  X X
+   VLAN filter                          X X X X
+   ethertype filter                     X X
    n-tuple filter
    SYN filter
-   tunnel filter                      X X
+   tunnel filter                        X X
    flexible filter
-   hash filter                        X X X X
-   flow director                      X X
-   flow control                 X     X X
+   hash filter                          X X X X
+   flow director                        X X
+   flow control                 X       X X
    rate limitation
-   traffic mirroring                  X X
-   CRC offload                  X     X   X
-   VLAN offload                 X     X   X
-   QinQ offload                       X   X
-   L3 checksum offload          X     X   X
-   L4 checksum offload          X     X   X
-   inner L3 checksum                  X   X
-   inner L4 checksum                  X   X
-   packet type parsing          X     X   X
-   timesync                           X X
-   basic stats                  X     X X X X                               X
-   extended stats                     X X X X
-   stats per queue              X                                           X
+   traffic mirroring                    X X
+   CRC offload                  X     X   X
+   VLAN offload                 X     X   X
+   QinQ offload                         X   X
+   L3 checksum offload          X     X   X
+   L4 checksum offload          X     X   X
+   inner L3 checksum                  X   X
+   inner L4 checksum                  X   X
+   packet type parsing          X       X   X
+   timesync                             X X
+   basic stats                  X     X X X X                               X
+   extended stats                     X X X X
+   stats per queue              X                                             X
    EEPROM dump
    registers dump
-   multiprocess aware                 X X X X
-   BSD nic_uio                  X     X X X X
-   Linux UIO                    X     X X X X
-   Linux VFIO                   X     X X X X
-   other kdrv                                                               X
+   multiprocess aware                   X X X X
+   BSD nic_uio                  X       X X X X
+   Linux UIO                    X     X X X X
+   Linux VFIO                   X       X X X X
+   other kdrv                                                                 X
    ARMv7
    ARMv8
    Power8
    TILE-Gx
-   x86-32                       X     X X X X
-   x86-64                       X     X X X X                               X
-   usage doc                    X                                           X
+   x86-32                       X     X X X X
+   x86-64                       X     X X X X                               X
+   usage doc                    X                                             X
    design doc
    perf doc
-   ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+   ==================== = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =