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