doc/guides/nics/octeontx2.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(C) 2019 Marvell International Ltd.
   3
   4 OCTEON TX2 Poll Mode driver
   5 ===========================
   6
   7 The OCTEON TX2 ETHDEV PMD (**librte_pmd_octeontx2**) provides poll mode ethdev
   8 driver support for the inbuilt network device found in **Marvell OCTEON TX2**
   9 SoC family as well as for their virtual functions (VF) in SR-IOV context.
  10
  11 More information can be found at `Marvell Official Website
  12 <https://www.marvell.com/embedded-processors/infrastructure-processors>`_.
  13
  14 Features
  15 --------
  16
  17 Features of the OCTEON TX2 Ethdev PMD are:
  18
  19 - Packet type information
  20 - Promiscuous mode
  21 - Jumbo frames
  22 - SR-IOV VF
  23 - Lock-free Tx queue
  24 - Multiple queues for TX and RX
  25 - Receiver Side Scaling (RSS)
  26 - MAC/VLAN filtering
  27 - Generic flow API
  28 - Inner and Outer Checksum offload
  29 - VLAN/QinQ stripping and insertion
  30 - Port hardware statistics
  31 - Link state information
  32 - Link flow control
  33 - Scatter-Gather IO support
  34 - Vector Poll mode driver
  35 - Debug utilities - Context dump and error interrupt support
  36 - IEEE1588 timestamping
  37 - HW offloaded `ethdev Rx queue` to `eventdev event queue` packet injection
  38
  39 Prerequisites
  40 -------------
  41
  42 See :doc:`../platform/octeontx2` for setup information.
  43
  44 Compile time Config Options
  45 ---------------------------
  46
  47 The following options may be modified in the ``config`` file.
  48
  49 - ``CONFIG_RTE_LIBRTE_OCTEONTX2_PMD`` (default ``y``)
  50
  51   Toggle compilation of the ``librte_pmd_octeontx2`` driver.
  52
  53 Driver compilation and testing
  54 ------------------------------
  55
  56 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
  57 for details.
  58
  59 To compile the OCTEON TX2 PMD for Linux arm64 gcc,
  60 use arm64-octeontx2-linux-gcc as target.
  61
  62 #. Running testpmd:
  63
  64    Follow instructions available in the document
  65    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
  66    to run testpmd.
  67
  68    Example output:
  69
  70    .. code-block:: console
  71
  72       ./build/app/testpmd -c 0x300 -w 0002:02:00.0 -- --portmask=0x1 --nb-cores=1 --port-topology=loop --rxq=1 --txq=1
  73       EAL: Detected 24 lcore(s)
  74       EAL: Detected 1 NUMA nodes
  75       EAL: Multi-process socket /var/run/dpdk/rte/mp_socket
  76       EAL: No available hugepages reported in hugepages-2048kB
  77       EAL: Probing VFIO support...
  78       EAL: VFIO support initialized
  79       EAL: PCI device 0002:02:00.0 on NUMA socket 0
  80       EAL:   probe driver: 177d:a063 net_octeontx2
  81       EAL:   using IOMMU type 1 (Type 1)
  82       testpmd: create a new mbuf pool <mbuf_pool_socket_0>: n=267456, size=2176, socket=0
  83       testpmd: preferred mempool ops selected: octeontx2_npa
  84       Configuring Port 0 (socket 0)
  85       PMD: Port 0: Link Up - speed 40000 Mbps - full-duplex
  86
  87       Port 0: link state change event
  88       Port 0: 36:10:66:88:7A:57
  89       Checking link statuses...
  90       Done
  91       No commandline core given, start packet forwarding
  92       io packet forwarding - ports=1 - cores=1 - streams=1 - NUMA support enabled, MP allocation mode: native
  93       Logical Core 9 (socket 0) forwards packets on 1 streams:
  94         RX P=0/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
  95
  96         io packet forwarding packets/burst=32
  97         nb forwarding cores=1 - nb forwarding ports=1
  98         port 0: RX queue number: 1 Tx queue number: 1
  99           Rx offloads=0x0 Tx offloads=0x10000
 100           RX queue: 0
 101             RX desc=512 - RX free threshold=0
 102             RX threshold registers: pthresh=0 hthresh=0  wthresh=0
 103             RX Offloads=0x0
 104           TX queue: 0
 105             TX desc=512 - TX free threshold=0
 106             TX threshold registers: pthresh=0 hthresh=0  wthresh=0
 107             TX offloads=0x10000 - TX RS bit threshold=0
 108       Press enter to exit
 109
 110 Runtime Config Options
 111 ----------------------
 112
 113 - ``HW offload ptype parsing disable`` (default ``0``)
 114
 115    Packet type parsing is HW offloaded by default and this feature may be toggled
 116    using ``ptype_disable`` ``devargs`` parameter.
 117
 118 - ``Rx&Tx scalar mode enable`` (default ``0``)
 119
 120    Ethdev supports both scalar and vector mode, it may be selected at runtime
 121    using ``scalar_enable`` ``devargs`` parameter.
 122
 123 - ``RSS reta size`` (default ``64``)
 124
 125    RSS redirection table size may be configured during runtime using ``reta_size``
 126    ``devargs`` parameter.
 127
 128    For example::
 129
 130       -w 0002:02:00.0,reta_size=256
 131
 132    With the above configuration, reta table of size 256 is populated.
 133
 134 - ``Flow priority levels`` (default ``3``)
 135
 136    RTE Flow priority levels can be configured during runtime using
 137    ``flow_max_priority`` ``devargs`` parameter.
 138
 139    For example::
 140
 141       -w 0002:02:00.0,flow_max_priority=10
 142
 143    With the above configuration, priority level was set to 10 (0-9). Max
 144    priority level supported is 32.
 145
 146 - ``Reserve Flow entries`` (default ``8``)
 147
 148    RTE flow entries can be pre allocated and the size of pre allocation can be
 149    selected runtime using ``flow_prealloc_size`` ``devargs`` parameter.
 150
 151    For example::
 152
 153       -w 0002:02:00.0,flow_prealloc_size=4
 154
 155    With the above configuration, pre alloc size was set to 4. Max pre alloc
 156    size supported is 32.
 157
 158 - ``Max SQB buffer count`` (default ``512``)
 159
 160    Send queue descriptor buffer count may be limited during runtime using
 161    ``max_sqb_count`` ``devargs`` parameter.
 162
 163    For example::
 164
 165       -w 0002:02:00.0,max_sqb_count=64
 166
 167    With the above configuration, each send queue's decscriptor buffer count is
 168    limited to a maximum of 64 buffers.
 169
 170
 171 .. note::
 172
 173    Above devarg parameters are configurable per device, user needs to pass the
 174    parameters to all the PCIe devices if application requires to configure on
 175    all the ethdev ports.
 176
 177 Limitations
 178 -----------
 179
 180 ``mempool_octeontx2`` external mempool handler dependency
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 182
 183 The OCTEON TX2 SoC family NIC has inbuilt HW assisted external mempool manager.
 184 ``net_octeontx2`` pmd only works with ``mempool_octeontx2`` mempool handler
 185 as it is performance wise most effective way for packet allocation and Tx buffer
 186 recycling on OCTEON TX2 SoC platform.
 187
 188 CRC striping
 189 ~~~~~~~~~~~~
 190
 191 The OCTEON TX2 SoC family NICs strip the CRC for every packet being received by
 192 the host interface irrespective of the offload configuration.
 193
 194
 195 Debugging Options
 196 -----------------
 197
 198 .. _table_octeontx2_ethdev_debug_options:
 199
 200 .. table:: OCTEON TX2 ethdev debug options
 201
 202    +---+------------+-------------------------------------------------------+
 203    | # | Component  | EAL log command                                       |
 204    +===+============+=======================================================+
 205    | 1 | NIX        | --log-level='pmd\.net.octeontx2,8'                    |
 206    +---+------------+-------------------------------------------------------+
 207    | 2 | NPC        | --log-level='pmd\.net.octeontx2\.flow,8'              |
 208    +---+------------+-------------------------------------------------------+
 209
 210 RTE Flow Support
 211 ----------------
 212
 213 The OCTEON TX2 SoC family NIC has support for the following patterns and
 214 actions.
 215
 216 Patterns:
 217
 218 .. _table_octeontx2_supported_flow_item_types:
 219
 220 .. table:: Item types
 221
 222    +----+--------------------------------+
 223    | #  | Pattern Type                   |
 224    +====+================================+
 225    | 1  | RTE_FLOW_ITEM_TYPE_ETH         |
 226    +----+--------------------------------+
 227    | 2  | RTE_FLOW_ITEM_TYPE_VLAN        |
 228    +----+--------------------------------+
 229    | 3  | RTE_FLOW_ITEM_TYPE_E_TAG       |
 230    +----+--------------------------------+
 231    | 4  | RTE_FLOW_ITEM_TYPE_IPV4        |
 232    +----+--------------------------------+
 233    | 5  | RTE_FLOW_ITEM_TYPE_IPV6        |
 234    +----+--------------------------------+
 235    | 6  | RTE_FLOW_ITEM_TYPE_ARP_ETH_IPV4|
 236    +----+--------------------------------+
 237    | 7  | RTE_FLOW_ITEM_TYPE_MPLS        |
 238    +----+--------------------------------+
 239    | 8  | RTE_FLOW_ITEM_TYPE_ICMP        |
 240    +----+--------------------------------+
 241    | 9  | RTE_FLOW_ITEM_TYPE_UDP         |
 242    +----+--------------------------------+
 243    | 10 | RTE_FLOW_ITEM_TYPE_TCP         |
 244    +----+--------------------------------+
 245    | 11 | RTE_FLOW_ITEM_TYPE_SCTP        |
 246    +----+--------------------------------+
 247    | 12 | RTE_FLOW_ITEM_TYPE_ESP         |
 248    +----+--------------------------------+
 249    | 13 | RTE_FLOW_ITEM_TYPE_GRE         |
 250    +----+--------------------------------+
 251    | 14 | RTE_FLOW_ITEM_TYPE_NVGRE       |
 252    +----+--------------------------------+
 253    | 15 | RTE_FLOW_ITEM_TYPE_VXLAN       |
 254    +----+--------------------------------+
 255    | 16 | RTE_FLOW_ITEM_TYPE_GTPC        |
 256    +----+--------------------------------+
 257    | 17 | RTE_FLOW_ITEM_TYPE_GTPU        |
 258    +----+--------------------------------+
 259    | 18 | RTE_FLOW_ITEM_TYPE_GENEVE      |
 260    +----+--------------------------------+
 261    | 19 | RTE_FLOW_ITEM_TYPE_VXLAN_GPE   |
 262    +----+--------------------------------+
 263    | 20 | RTE_FLOW_ITEM_TYPE_VOID        |
 264    +----+--------------------------------+
 265    | 21 | RTE_FLOW_ITEM_TYPE_ANY         |
 266    +----+--------------------------------+
 267
 268 Actions:
 269
 270 .. _table_octeontx2_supported_ingress_action_types:
 271
 272 .. table:: Ingress action types
 273
 274    +----+--------------------------------+
 275    | #  | Action Type                    |
 276    +====+================================+
 277    | 1  | RTE_FLOW_ACTION_TYPE_VOID      |
 278    +----+--------------------------------+
 279    | 2  | RTE_FLOW_ACTION_TYPE_MARK      |
 280    +----+--------------------------------+
 281    | 3  | RTE_FLOW_ACTION_TYPE_FLAG      |
 282    +----+--------------------------------+
 283    | 4  | RTE_FLOW_ACTION_TYPE_COUNT     |
 284    +----+--------------------------------+
 285    | 5  | RTE_FLOW_ACTION_TYPE_DROP      |
 286    +----+--------------------------------+
 287    | 6  | RTE_FLOW_ACTION_TYPE_QUEUE     |
 288    +----+--------------------------------+
 289    | 7  | RTE_FLOW_ACTION_TYPE_RSS       |
 290    +----+--------------------------------+
 291    | 8  | RTE_FLOW_ACTION_TYPE_SECURITY  |
 292    +----+--------------------------------+
 293
 294 .. _table_octeontx2_supported_egress_action_types:
 295
 296 .. table:: Egress action types
 297
 298    +----+--------------------------------+
 299    | #  | Action Type                    |
 300    +====+================================+
 301    | 1  | RTE_FLOW_ACTION_TYPE_COUNT     |
 302    +----+--------------------------------+
 303    | 2  | RTE_FLOW_ACTION_TYPE_DROP      |
 304    +----+--------------------------------+