[dpdk-dev] [PATCH v1 58/58] doc: add Marvell OCTEON TX2 ethdev documentation

[<jerinj@marvell.com>]

From: Jerin Jacob <jerinj@marvell.com>

Add Marvell OCTEON TX2 ethdev documentation.

This patch also updates the MAINTAINERS file and
shared library versions in release_19_08.rst.

Cc: John McNamara <john.mcnamara@intel.com>
Cc: Thomas Monjalon <thomas@monjalon.net>

Signed-off-by: Jerin Jacob <jerinj@marvell.com>
Signed-off-by: Vamsi Attunuru <vattunuru@marvell.com>
Signed-off-by: Kiran Kumar K <kirankumark@marvell.com>
Signed-off-by: Nithin Dabilpuram <ndabilpuram@marvell.com>
---
 MAINTAINERS                                |   8 +
 doc/guides/nics/features/octeontx2.ini     |   1 +
 doc/guides/nics/features/octeontx2_vec.ini |   1 +
 doc/guides/nics/features/octeontx2_vf.ini  |   1 +
 doc/guides/nics/index.rst                  |   1 +
 doc/guides/nics/octeontx2.rst              | 289 +++++++++++++++++++++
 doc/guides/platform/octeontx2.rst          |   3 +
 doc/guides/rel_notes/release_19_05.rst     |   1 +
 8 files changed, 305 insertions(+)
 create mode 100644 doc/guides/nics/octeontx2.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 74ac6d41f..fe509c1f9 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -668,6 +668,14 @@ F: drivers/net/mvneta/
 F: doc/guides/nics/mvneta.rst
 F: doc/guides/nics/features/mvneta.ini
 
+Marvell OCTEON TX2
+M: Jerin Jacob <jerinj@marvell.com>
+M: Nithin Dabilpuram <ndabilpuram@marvell.com>
+M: Kiran Kumar K <kirankumark@marvell.com>
+F: drivers/net/octeontx2/
+F: doc/guides/nics/features/octeontx2*.rst
+F: doc/guides/nics/octeontx2.rst
+
 Mellanox mlx4
 M: Matan Azrad <matan@mellanox.com>
 M: Shahaf Shuler <shahafs@mellanox.com>
diff --git a/doc/guides/nics/features/octeontx2.ini b/doc/guides/nics/features/octeontx2.ini
index e96c588fa..ef1a638e9 100644
--- a/doc/guides/nics/features/octeontx2.ini
+++ b/doc/guides/nics/features/octeontx2.ini
@@ -44,3 +44,4 @@ Extended stats       = Y
 FW version           = Y
 Module EEPROM dump   = Y
 Registers dump       = Y
+Usage doc            = Y
diff --git a/doc/guides/nics/features/octeontx2_vec.ini b/doc/guides/nics/features/octeontx2_vec.ini
index 7ad097df4..8f95727f7 100644
--- a/doc/guides/nics/features/octeontx2_vec.ini
+++ b/doc/guides/nics/features/octeontx2_vec.ini
@@ -41,3 +41,4 @@ Stats per queue      = Y
 FW version           = Y
 Module EEPROM dump   = Y
 Registers dump       = Y
+Usage doc            = Y
diff --git a/doc/guides/nics/features/octeontx2_vf.ini b/doc/guides/nics/features/octeontx2_vf.ini
index 0d5137316..e78385bb2 100644
--- a/doc/guides/nics/features/octeontx2_vf.ini
+++ b/doc/guides/nics/features/octeontx2_vf.ini
@@ -36,3 +36,4 @@ Stats per queue      = Y
 FW version           = Y
 Module EEPROM dump   = Y
 Registers dump       = Y
+Usage doc            = Y
diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index 2221c35f2..6fa075594 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -44,6 +44,7 @@ Network Interface Controller Drivers
     nfb
     nfp
     octeontx
+    octeontx2
     qede
     sfc_efx
     softnic
diff --git a/doc/guides/nics/octeontx2.rst b/doc/guides/nics/octeontx2.rst
new file mode 100644
index 000000000..2f14a4a1c
--- /dev/null
+++ b/doc/guides/nics/octeontx2.rst
@@ -0,0 +1,289 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(C) 2019 Marvell International Ltd.
+
+OCTEON TX2 Poll Mode driver
+===========================
+
+The OCTEON TX2 ETHDEV PMD (**librte_pmd_octeontx2**) provides poll mode ethdev
+driver support for the inbuilt network device found in **Marvell OCTEON TX2**
+SoC family as well as for their virtual functions (VF) in SR-IOV context.
+
+More information can be found at `Marvell Official Website
+<https://www.marvell.com/embedded-processors/infrastructure-processors>`_.
+
+Features
+--------
+
+Features of the OCTEON TX2 Ethdev PMD are:
+
+- Packet type information
+- Promiscuous mode
+- Port hardware statistics
+- Jumbo frames
+- SR-IOV VF
+- Lock-free Tx queue
+- Multiple queues for TX and RX
+- Receiver Side Scaling (RSS)
+- MAC/VLAN filtering
+- Generic flow API
+- Inner and Outer Checksum offload
+- VLAN/QinQ stripping and insertion
+- Port hardware statistics
+- Link state information
+- Link flow control
+- MTU update
+- Scatter-Gather IO support
+- Vector Poll mode driver
+- Debug utilities - Context dump and error interrupt support
+- IEEE1588 timestamping
+- HW offloaded `ethdev Rx queue` to `eventdev event queue` packet injection
+
+Prerequisites
+-------------
+
+See :doc:`../platform/octeontx2` for setup information.
+
+Compile time Config Options
+---------------------------
+
+The following options may be modified in the ``config`` file.
+
+- ``CONFIG_RTE_LIBRTE_OCTEONTX2_PMD`` (default ``y``)
+
+  Toggle compilation of the ``librte_pmd_octeontx2`` driver.
+
+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 OCTEON TX2 PMD for Linux arm64 gcc,
+use arm64-octeontx2-linux-gcc as target.
+
+#. 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
+
+      ./build/app/testpmd -c 0x300 -w 0002:02:00.0 -- --portmask=0x1 --nb-cores=1 --port-topology=loop --rxq=1 --txq=1
+      EAL: Detected 24 lcore(s)
+      EAL: Detected 1 NUMA nodes
+      EAL: Multi-process socket /var/run/dpdk/rte/mp_socket
+      EAL: No available hugepages reported in hugepages-2048kB
+      EAL: Probing VFIO support...
+      EAL: VFIO support initialized
+      EAL: PCI device 0002:02:00.0 on NUMA socket 0
+      EAL:   probe driver: 177d:a063 net_octeontx2
+      EAL:   using IOMMU type 1 (Type 1)
+      testpmd: create a new mbuf pool <mbuf_pool_socket_0>: n=267456, size=2176, socket=0
+      testpmd: preferred mempool ops selected: octeontx2_npa
+      Configuring Port 0 (socket 0)
+      PMD: Port 0: Link Up - speed 40000 Mbps - full-duplex
+
+      Port 0: link state change event
+      Port 0: 36:10:66:88:7A:57
+      Checking link statuses...
+      Done
+      No commandline core given, start packet forwarding
+      io packet forwarding - ports=1 - cores=1 - streams=1 - NUMA support enabled, MP allocation mode: native
+      Logical Core 9 (socket 0) forwards packets on 1 streams:
+        RX P=0/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
+
+        io packet forwarding packets/burst=32
+        nb forwarding cores=1 - nb forwarding ports=1
+        port 0: RX queue number: 1 Tx queue number: 1
+          Rx offloads=0x0 Tx offloads=0x10000
+          RX queue: 0
+            RX desc=512 - RX free threshold=0
+            RX threshold registers: pthresh=0 hthresh=0  wthresh=0
+            RX Offloads=0x0
+          TX queue: 0
+            TX desc=512 - TX free threshold=0
+            TX threshold registers: pthresh=0 hthresh=0  wthresh=0
+            TX offloads=0x10000 - TX RS bit threshold=0
+      Press enter to exit
+
+Runtime Config Options
+----------------------
+
+- ``HW offload ptype parsing disable`` (default ``0``)
+
+   Packet type parsing is HW offloaded by default and this feature may be toggled
+   using ``ptype_disable`` ``devargs`` parameter.
+
+- ``Rx scalar mode enable`` (default ``0``)
+
+   Ethdev rx supports both scalar and vector mode, it may be selected at runtime
+   using ``scalar_enable`` ``devargs`` parameter.
+
+- ``RSS reta size`` (default ``64``)
+
+   RSS redirection table size may be configured during runtime using ``reta_size``
+   ``devargs`` parameter.
+
+   For example::
+
+      -w 0002:02:00.0,reta_size=256
+
+   With the above configuration, reta table of size 256 is populated.
+
+- ``Flow priority levels`` (default ``3``)
+
+   RTE Flow priority levels can be configured during runtime using
+   ``flow_max_priority`` ``devargs`` parameter.
+
+   For example::
+
+      -w 0002:02:00.0,flow_max_priority=10
+
+   With the above configuration, priority level was set to 10 (0-9). Max
+   priority level supported is 32.
+
+- ``Reserve Flow entries`` (default ``8``)
+
+   RTE flow entries can be pre allocated and the size of pre allocation can be
+   selected runtime using ``flow_prealloc_size`` ``devargs`` parameter.
+
+   For example::
+
+      -w 0002:02:00.0,flow_prealloc_size=4
+
+   With the above configuration, pre alloc size was set to 4. Max pre alloc
+   size supported is 32.
+
+.. note::
+
+   Above devarg parameters are configurable per device, user needs to pass the
+   parameters to all the PCIe devices if application requires to configure on
+   all the ethdev ports.
+
+Limitations
+-----------
+
+``mempool_octeontx2`` external mempool handler dependency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The OCTEON TX2 SoC family NIC has inbuilt HW assisted external mempool manager.
+``net_octeontx2`` pmd only works with ``mempool_octeontx2`` mempool handler
+as it is performance wise most effective way for packet allocation and Tx buffer
+recycling on OCTEON TX2 SoC platform.
+
+CRC striping
+~~~~~~~~~~~~
+
+The OCTEON TX2 SoC family NICs strip the CRC for every packet being received by
+the host interface irrespective of the offload configuration.
+
+
+Debugging Options
+-----------------
+
+.. _table_octeontx2_ethdev_debug_options:
+
+.. table:: OCTEON TX2 ethdev debug options
+
+   +---+------------+-------------------------------------------------------+
+   | # | Component  | EAL log command                                       |
+   +===+============+=======================================================+
+   | 1 | NIX        | --log-level='pmd\.net.octeontx2,8'                    |
+   +---+------------+-------------------------------------------------------+
+   | 2 | NPC        | --log-level='pmd\.net.octeontx2\.flow,8'              |
+   +---+------------+-------------------------------------------------------+
+
+RTE Flow Support
+----------------
+
+The OCTEON TX2 SoC family NIC has support for the following patterns and
+actions.
+
+Patterns:
+
+.. _table_octeontx2_supported_flow_item_types:
+
+.. table:: Item types
+
+   +----+--------------------------------+
+   | #  | Pattern Type                   |
+   +====+================================+
+   | 1  | RTE_FLOW_ITEM_TYPE_ETH         |
+   +----+--------------------------------+
+   | 2  | RTE_FLOW_ITEM_TYPE_VLAN        |
+   +----+--------------------------------+
+   | 3  | RTE_FLOW_ITEM_TYPE_E_TAG       |
+   +----+--------------------------------+
+   | 4  | RTE_FLOW_ITEM_TYPE_IPV4        |
+   +----+--------------------------------+
+   | 5  | RTE_FLOW_ITEM_TYPE_IPV6        |
+   +----+--------------------------------+
+   | 6  | RTE_FLOW_ITEM_TYPE_ARP_ETH_IPV4|
+   +----+--------------------------------+
+   | 7  | RTE_FLOW_ITEM_TYPE_MPLS        |
+   +----+--------------------------------+
+   | 8  | RTE_FLOW_ITEM_TYPE_ICMP        |
+   +----+--------------------------------+
+   | 9  | RTE_FLOW_ITEM_TYPE_UDP         |
+   +----+--------------------------------+
+   | 10 | RTE_FLOW_ITEM_TYPE_TCP         |
+   +----+--------------------------------+
+   | 11 | RTE_FLOW_ITEM_TYPE_SCTP        |
+   +----+--------------------------------+
+   | 12 | RTE_FLOW_ITEM_TYPE_ESP         |
+   +----+--------------------------------+
+   | 13 | RTE_FLOW_ITEM_TYPE_GRE         |
+   +----+--------------------------------+
+   | 14 | RTE_FLOW_ITEM_TYPE_NVGRE       |
+   +----+--------------------------------+
+   | 15 | RTE_FLOW_ITEM_TYPE_VXLAN       |
+   +----+--------------------------------+
+   | 16 | RTE_FLOW_ITEM_TYPE_GTPC        |
+   +----+--------------------------------+
+   | 17 | RTE_FLOW_ITEM_TYPE_GTPU        |
+   +----+--------------------------------+
+   | 18 | RTE_FLOW_ITEM_TYPE_VOID        |
+   +----+--------------------------------+
+   | 19 | RTE_FLOW_ITEM_TYPE_ANY         |
+   +----+--------------------------------+
+
+Actions:
+
+.. _table_octeontx2_supported_ingress_action_types:
+
+.. table:: Ingress action types
+
+   +----+--------------------------------+
+   | #  | Action Type                    |
+   +====+================================+
+   | 1  | RTE_FLOW_ACTION_TYPE_VOID      |
+   +----+--------------------------------+
+   | 2  | RTE_FLOW_ACTION_TYPE_MARK      |
+   +----+--------------------------------+
+   | 3  | RTE_FLOW_ACTION_TYPE_FLAG      |
+   +----+--------------------------------+
+   | 4  | RTE_FLOW_ACTION_TYPE_COUNT     |
+   +----+--------------------------------+
+   | 5  | RTE_FLOW_ACTION_TYPE_DROP      |
+   +----+--------------------------------+
+   | 6  | RTE_FLOW_ACTION_TYPE_QUEUE     |
+   +----+--------------------------------+
+   | 7  | RTE_FLOW_ACTION_TYPE_RSS       |
+   +----+--------------------------------+
+   | 8  | RTE_FLOW_ACTION_TYPE_SECURITY  |
+   +----+--------------------------------+
+
+.. _table_octeontx2_supported_egress_action_types:
+
+.. table:: Egress action types
+
+   +----+--------------------------------+
+   | #  | Action Type                    |
+   +====+================================+
+   | 1  | RTE_FLOW_ACTION_TYPE_COUNT     |
+   +----+--------------------------------+
+   | 2  | RTE_FLOW_ACTION_TYPE_DROP      |
+   +----+--------------------------------+
diff --git a/doc/guides/platform/octeontx2.rst b/doc/guides/platform/octeontx2.rst
index c9ea45647..d2592f119 100644
--- a/doc/guides/platform/octeontx2.rst
+++ b/doc/guides/platform/octeontx2.rst
@@ -98,6 +98,9 @@ HW Offload Drivers
 
 This section lists dataplane H/W block(s) available in OCTEON TX2 SoC.
 
+#. **Ethdev Driver**
+   See :doc:`../nics/octeontx2` for NIX Ethdev driver information.
+
 #. **Mempool Driver**
    See :doc:`../mempool/octeontx2` for NPA mempool driver information.
 
diff --git a/doc/guides/rel_notes/release_19_05.rst b/doc/guides/rel_notes/release_19_05.rst
index b4c6972e3..e925ccf0e 100644
--- a/doc/guides/rel_notes/release_19_05.rst
+++ b/doc/guides/rel_notes/release_19_05.rst
@@ -386,6 +386,7 @@ The libraries prepended with a plus sign were incremented in this version.
      librte_pmd_i40e.so.2
      librte_pmd_ixgbe.so.2
      librte_pmd_dpaa2_qdma.so.1
+   + librte_pmd_octeontx2.so.1
      librte_pmd_ring.so.2
      librte_pmd_softnic.so.1
      librte_pmd_vhost.so.2
-- 
2.21.0