[dpdk-dev] [PATCH 3/4] doc: Add documents for AMD XGBE Ethernet

[Ravi Kumar <ravi1.kumar@amd.com>]

Signed-off-by: Ravi Kumar <ravi1.kumar@amd.com>
---
 doc/guides/nics/axgbe.rst          | 214 +++++++++++++++++++++++++++++++++++++
 doc/guides/nics/features/axgbe.ini |  18 ++++
 doc/guides/nics/index.rst          |   1 +
 3 files changed, 233 insertions(+)
 create mode 100644 doc/guides/nics/axgbe.rst
 create mode 100644 doc/guides/nics/features/axgbe.ini

diff --git a/doc/guides/nics/axgbe.rst b/doc/guides/nics/axgbe.rst
new file mode 100644
index 0000000..97056fa
--- /dev/null
+++ b/doc/guides/nics/axgbe.rst
@@ -0,0 +1,214 @@
+..  Copyright (c) 2017 Advanced Micro Devices, Inc.
+    All rights reserved.
+
+    AMD 10Gb Ethernet driver
+
+    This file is available to you under your choice of the following two
+    licenses:
+
+    License 1: GPLv2
+
+    Copyright (c) 2017 Advanced Micro Devices, Inc.
+
+    This file is free software; you may copy, redistribute and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 2 of the License, or (at
+    your option) any later version.
+
+    This file is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+    General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+    This file incorporates work covered by the following copyright and
+    permission notice:
+
+    Copyright (c) 2013 Synopsys, Inc.
+
+    The Synopsys DWC ETHER XGMAC Software Driver and documentation
+    (hereinafter "Software") is an unsupported proprietary work of Synopsys,
+    Inc. unless otherwise expressly agreed to in writing between Synopsys
+    and you.
+
+    The Software IS NOT an item of Licensed Software or Licensed Product
+    under any End User Software License Agreement or Agreement for Licensed
+    Product with Synopsys or any supplement thereto. Permission is hereby
+    granted, free of charge, to any person obtaining a copy of this software
+    annotated with this license and the Software, to deal in the Software
+    without restriction, including without limitation the rights to use,
+    copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+    of the Software, and to permit persons to whom the Software is furnished
+    to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THIS SOFTWARE IS BEING DISTRIBUTED BY SYNOPSYS SOLELY ON AN "AS IS"
+    BASIS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+    TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+    PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL SYNOPSYS
+    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.
+
+    License 2: Modified BSD
+
+    Copyright (c) 2017 Advanced Micro Devices, Inc.
+    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 Advanced Micro Devices, 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 <COPYRIGHT HOLDER> 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.
+
+    This file incorporates work covered by the following copyright and
+    permission notice:
+
+    Copyright (c) 2013 Synopsys, Inc.
+
+    The Synopsys DWC ETHER XGMAC Software Driver and documentation
+    (hereinafter "Software") is an unsupported proprietary work of Synopsys,
+    Inc. unless otherwise expressly agreed to in writing between Synopsys
+    and you.
+
+    The Software IS NOT an item of Licensed Software or Licensed Product
+    under any End User Software License Agreement or Agreement for Licensed
+    Product with Synopsys or any supplement thereto. Permission is hereby
+    granted, free of charge, to any person obtaining a copy of this software
+    annotated with this license and the Software, to deal in the Software
+    without restriction, including without limitation the rights to use,
+    copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+    of the Software, and to permit persons to whom the Software is furnished
+    to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THIS SOFTWARE IS BEING DISTRIBUTED BY SYNOPSYS SOLELY ON AN "AS IS"
+    BASIS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+    TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+    PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL SYNOPSYS
+    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.
+
+AXGBE Poll Mode Driver
+======================
+
+The AXGBE poll mode driver library (**librte_pmd_axgbe**) implements support
+for AMD 10 Gbps family of adapters. It is compiled and tested in standard linux distro like Ubuntu.
+
+Supported Features
+------------------
+
+AXGBE PMD has support for:
+
+- Base L2 features
+- Unicast/multicast filtering
+- Promiscuous mode
+- Port statistics
+- TSS (Transmit Side Scaling)
+- RSS (Receive Side Scaling)
+- Checksum offload
+- Jumbo Frame upto 9K
+
+
+Supported Chipsets and NICs
+---------------------------
+- AMD 10 Gigabit Ethernet Controller
+
+
+Configuration Information
+-------------------------
+
+The following options can be modified in the ``.config`` file. Please note that
+enabling debugging options may affect system performance.
+
+- ``CONFIG_RTE_LIBRTE_AXGBE_PMD`` (default **n**)
+
+  Toggle compilation of axgbe driver. To use axgbe PMD set this config parameter
+  to 'y'. 
+
+- ``CONFIG_RTE_LIBRTE_AXGBE_DEBUG_INIT`` (default **n**)
+
+  Toggle display of initialization related messages.
+
+
+Building DPDK
+-------------
+
+See the :ref:`DPDK Getting Started Guide for Linux <linux_gsg>` for
+instructions on how to build DPDK.
+
+By default the AXGBE PMD library will be built into the DPDK library.
+
+For configuring and using UIO frameworks, please also refer :ref:`the
+documentation that comes with DPDK suite <linux_gsg>`.
+
+
+Prerequisites and Pre-conditions
+--------------------------------
+- Prepare the system as recommended by DPDK suite.
+
+- AXGBE PMD works only with legacy interrupts, so load igb_uio module in legacy interrupt mode
+  using module params.
+
+- Bind the intented AMD device to igb_uio module.
+
+Now system is ready to run DPDK application.
+
+
+Usage Example
+-------------
+
+Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+for details.
+
+Example output:
+
+.. code-block:: console
+
+   [...]
+   EAL: PCI device 0000:02:00.4 on NUMA socket 0
+   EAL:   probe driver: 1022:1458 net_axgbe
+   Interactive-mode selected
+   USER1: create a new mbuf pool <mbuf_pool_socket_0>: n=171456, size=2176, socket=0
+   USER1: create a new mbuf pool <mbuf_pool_socket_1>: n=171456, size=2176, socket=1
+   USER1: create a new mbuf pool <mbuf_pool_socket_2>: n=171456, size=2176, socket=2
+   USER1: create a new mbuf pool <mbuf_pool_socket_3>: n=171456, size=2176, socket=3
+   Configuring Port 0 (socket 0)
+   Port 0: 00:00:1A:1C:6A:17
+   Checking link statuses...
+   Port 0 Link Up - speed 10000 Mbps - full-duplex
+   Done
+   testpmd>
diff --git a/doc/guides/nics/features/axgbe.ini b/doc/guides/nics/features/axgbe.ini
new file mode 100644
index 0000000..042ff1e
--- /dev/null
+++ b/doc/guides/nics/features/axgbe.ini
@@ -0,0 +1,18 @@
+;
+; Supported features of the 'axgbe' network poll mode driver.
+;
+; Refer to default.ini for the full list of available PMD features.
+;
+[Features]
+Speed capabilities   = Y
+Link status          = Y
+Jumbo frame          = Y
+Promiscuous mode     = Y
+Allmulticast mode    = Y
+RSS hash             = Y
+CRC offload          = Y
+L3 checksum offload  = Y
+L4 checksum offload  = Y
+Basic stats          = Y
+Linux UIO            = Y
+x86-64               = Y
diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index 36f4f3f..8e39847 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -40,6 +40,7 @@ Network Interface Controller Drivers
     build_and_test
     ark
     avp
+    axgbe
     bnx2x
     bnxt
     cxgbe
-- 
2.7.4