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