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