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