[dpdk-dev] [PATCH 26/26] doc: add octeontx ethdev driver documentation

[Jerin Jacob <jerin.jacob@caviumnetworks.com>]

Adding octeontx ethdev driver documentation and claim octeontx ethdev
driver maintainership.

Cc: John McNamara <john.mcnamara@intel.com>

Signed-off-by: Jerin Jacob <jerin.jacob@caviumnetworks.com>
Co-authored-by: Santosh Shukla <santosh.shukla@caviumnetworks.com>
---
 MAINTAINERS                  |   7 ++
 doc/guides/nics/index.rst    |   1 +
 doc/guides/nics/octeontx.rst | 251 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 259 insertions(+)
 create mode 100644 doc/guides/nics/octeontx.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 58287ea0d..fb73ff1d0 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -323,6 +323,13 @@ F: drivers/net/bnxt/
 F: doc/guides/nics/bnxt.rst
 F: doc/guides/nics/features/bnxt.ini
 
+Cavium OCTEONTX
+M: Santosh Shukla <santosh.shukla@caviumnetworks.com>
+M: Jerin Jacob <jerin.jacob@caviumnetworks.com>
+F: drivers/net/octeontx/
+F: doc/guides/nics/octeontx.rst
+F: doc/guides/nics/features/octeontx.ini
+
 Cavium ThunderX nicvf
 M: Jerin Jacob <jerin.jacob@caviumnetworks.com>
 M: Maciej Czekaj <maciej.czekaj@caviumnetworks.com>
diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index 36f4f3ff5..62eb3bd94 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -56,6 +56,7 @@ Network Interface Controller Drivers
     mlx4
     mlx5
     nfp
+    octeontx
     qede
     sfc_efx
     szedata2
diff --git a/doc/guides/nics/octeontx.rst b/doc/guides/nics/octeontx.rst
new file mode 100644
index 000000000..4b276ddac
--- /dev/null
+++ b/doc/guides/nics/octeontx.rst
@@ -0,0 +1,251 @@
+..  BSD LICENSE
+    Copyright (C) Cavium, Inc. 2017.
+    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 Cavium, 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.
+
+OCTEONTX Poll Mode driver
+=========================
+
+The OCTEONTX ETHDEV PMD (**librte_pmd_octeontx**) provides poll mode ethdev
+driver support for the inbuilt network device found in the **Cavium OCTEONTX**
+SoC family as well as their virtual functions (VF) in SR-IOV context.
+
+More information can be found at `Cavium, Inc Official Website
+<http://www.cavium.com/OCTEON-TX_ARM_Processors.html>`_.
+
+Features
+--------
+
+Features of the OCTEONTX Ethdev PMD are:
+
+- Packet type information
+- Promiscuous mode
+- Port hardware statistics
+- Jumbo frames
+- Link state information
+- SR-IOV VF
+- Multiple queues for TX
+- Lock-free Tx queue
+- HW offloaded `ethdev Rx queue` to `eventdev event queue` packet injection
+
+Supported OCTEONTX SoCs
+-----------------------
+- CN83xx
+
+Unsupported features
+--------------------
+
+The features supported by the device and not yet supported by this PMD include:
+
+- Receive Side Scaling (RSS)
+- Scattered and gather for TX and RX
+- Ingress classification support
+- Egress hierarchical scheduling, traffic shaping, and marking
+
+Prerequisites
+-------------
+
+There are three main pre-perquisites for executing OCTEONTX PMD on a OCTEONTX
+compatible board:
+
+1. **OCTEONTX Linux kernel PF driver for Network acceleration HW blocks**
+
+   The OCTEONTX Linux kernel drivers (including the required PF driver for the
+   all network acceleration blocks) are available on GitHub at
+   `octeontx-kmod <https://github.com/caviumnetworks/octeontx-kmod>`_
+   along with build, install and dpdk usage instructions.
+
+2. **ARM64 Tool Chain**
+
+   For example, the *aarch64* Linaro Toolchain, which can be obtained from
+   `here <https://releases.linaro.org/components/toolchain/binaries/4.9-2017.01/aarch64-linux-gnu>`_.
+
+3. **Rootfile system**
+
+   Any *aarch64* supporting filesystem can be used. For example,
+   Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
+   from `<http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
+
+   As an alternative method, OCTEONTX PMD can also be executed using images provided
+   as part of SDK from Cavium. The SDK includes all the above prerequisites necessary
+   to bring up a OCTEONTX board.
+
+   SDK and related information can be obtained from: `Cavium support site <https://support.cavium.com/>`_.
+
+- Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
+
+Pre-Installation Configuration
+------------------------------
+
+Config File Options
+~~~~~~~~~~~~~~~~~~~
+
+The following options can be modified in the ``config`` file.
+Please note that enabling debugging options may affect system performance.
+
+- ``CONFIG_RTE_LIBRTE_OCTEONTX_PMD`` (default ``y``)
+
+  Toggle compilation of the ``librte_pmd_octeontx`` driver.
+
+- ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_DRIVER`` (default ``n``)
+
+  Toggle display of generic debugging messages
+
+- ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_INIT`` (default ``n``)
+
+  Toggle display of initialization related messages.
+
+- ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_RX`` (default ``n``)
+
+  Toggle display of receive path message
+
+- ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_TX`` (default ``n``)
+
+  Toggle display of transmit path message
+
+- ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_MBOX`` (default ``n``)
+
+  Toggle display of mbox related message
+
+
+Driver compilation and testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+for details.
+
+To compile the OCTEONTX PMD for Linux arm64 gcc target, run the
+following ``make`` command:
+
+.. code-block:: console
+
+   cd <DPDK-source-directory>
+   make config T=arm64-thunderx-linuxapp-gcc install
+
+#. Running testpmd:
+
+   Follow instructions available in the document
+   :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+   to run testpmd.
+
+   Example output:
+
+   .. code-block:: console
+
+      ./arm64-thunderx-linuxapp-gcc/app/testpmd -c 700 \
+                --base-virtaddr=0x100000000000 \
+                --mbuf-pool-ops="octeontx_fpavf" \
+                --vdev='event_octeontx' \
+                --vdev='eth_octeontx,nr_port=2' \
+                -- --rxq=1 --txq=1 --nb-core=2 --total-num-mbufs=16384 \
+                --disable-hw-vlan-filter -i
+      .....
+      EAL: Detected 24 lcore(s)
+      EAL: Probing VFIO support...
+      EAL: VFIO support initialized
+      .....
+      EAL: PCI device 0000:07:00.1 on NUMA socket 0
+      EAL:   probe driver: 177d:a04b octeontx_ssovf
+      .....
+      EAL: PCI device 0001:02:00.7 on NUMA socket 0
+      EAL:   probe driver: 177d:a0dd octeontx_pkivf
+      .....
+      EAL: PCI device 0001:03:01.0 on NUMA socket 0
+      EAL:   probe driver: 177d:a049 octeontx_pkovf
+      .....
+      PMD: octeontx_probe(): created ethdev eth_octeontx for port 0
+      PMD: octeontx_probe(): created ethdev eth_octeontx for port 1
+      .....
+      Configuring Port 0 (socket 0)
+      Port 0: 00:0F:B7:11:94:46
+      Configuring Port 1 (socket 0)
+      Port 1: 00:0F:B7:11:94:47
+      .....
+      Checking link statuses...
+      Port 0 Link Up - speed 40000 Mbps - full-duplex
+      Port 1 Link Up - speed 40000 Mbps - full-duplex
+      Done
+      testpmd>
+
+
+Initialization
+--------------
+
+The octeontx ethdev pmd is exposed as a vdev device which consists of a set
+of PKI and PKO PCIe VF devices. On EAL initialization,
+PKI/PKO PCIe VF devices will be probed and then the vdev device can be created
+from the application code, or from the EAL command line based on
+the number of probed/bound PKI/PKO PCIe VF device to DPDK by
+
+* Invoking ``rte_vdev_init("eth_octeontx")`` from the application
+
+* Using ``--vdev="eth_octeontx"`` in the EAL options, which will call
+  rte_vdev_init() internally
+
+Device arguments
+~~~~~~~~~~~~~~~~
+Each ethdev port is mapped to a physical port(LMAC), Application can specify
+the number of interesting ports with ``nr_ports`` argument.
+
+Dependency
+~~~~~~~~~~
+``eth_octeontx`` pmd is depend on ``event_octeontx`` eventdev device and
+``octeontx_fpavf`` external mempool handler.
+
+Example:
+
+.. code-block:: console
+
+    ./your_dpdk_application --mbuf-pool-ops="octeontx_fpavf" \
+                --vdev='event_octeontx' \
+                --vdev="eth_octeontx,nr_port=2"
+
+Limitations
+-----------
+
+``octeontx_fpavf`` external mempool handler dependency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The OCTEONTX SoC family NIC has inbuilt HW assisted external mempool manager.
+This driver will only work with ``octeontx_fpavf`` external mempool handler
+as it is the most performance effective way for packet allocation and Tx buffer
+recycling on OCTEONTX SoC platform.
+
+CRC striping
+~~~~~~~~~~~~
+
+The OCTEONTX SoC family NICs strip the CRC for every packets coming into the
+host interface. So, CRC will be stripped even when the
+``rxmode.hw_strip_crc`` member is set to 0 in ``struct rte_eth_conf``.
+
+Maximum packet length
+~~~~~~~~~~~~~~~~~~~~~
+
+The OCTEONTX SoC family NICs support a maximum of a 32K jumbo frame. The value
+is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
+member of ``struct rte_eth_conf`` is set to a value lower than 32k, frames
+up to 32k bytes can still reach the host interface.
-- 
2.14.1