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 .. note::
 214
 215    Above devarg parameters are configurable per device, user needs to pass the
 216    parameters to all the PCIe devices if application requires to configure on
 217    all the ethdev ports.
 218
 219 - ``Lock NPA contexts in NDC``
 220
 221    Lock NPA aura and pool contexts in NDC cache.
 222    The device args take hexadecimal bitmask where each bit represent the
 223    corresponding aura/pool id.
 224
 225    For example::
 226
 227       -w 0002:02:00.0,npa_lock_mask=0xf
 228
 229 .. _otx2_tmapi:
 230
 231 Traffic Management API
 232 ----------------------
 233
 234 OCTEON TX2 PMD supports generic DPDK Traffic Management API which allows to
 235 configure the following features:
 236
 237 #. Hierarchical scheduling
 238 #. Single rate - Two color, Two rate - Three color shaping
 239
 240 Both DWRR and Static Priority(SP) hierarchial scheduling is supported.
 241
 242 Every parent can have atmost 10 SP Children and unlimited DWRR children.
 243
 244 Both PF & VF supports traffic management API with PF supporting 6 levels
 245 and VF supporting 5 levels of topology.
 246
 247 Limitations
 248 -----------
 249
 250 ``mempool_octeontx2`` external mempool handler dependency
 251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 252
 253 The OCTEON TX2 SoC family NIC has inbuilt HW assisted external mempool manager.
 254 ``net_octeontx2`` pmd only works with ``mempool_octeontx2`` mempool handler
 255 as it is performance wise most effective way for packet allocation and Tx buffer
 256 recycling on OCTEON TX2 SoC platform.
 257
 258 CRC stripping
 259 ~~~~~~~~~~~~~
 260
 261 The OCTEON TX2 SoC family NICs strip the CRC for every packet being received by
 262 the host interface irrespective of the offload configuration.
 263
 264 Multicast MAC filtering
 265 ~~~~~~~~~~~~~~~~~~~~~~~
 266
 267 ``net_octeontx2`` pmd supports multicast mac filtering feature only on physical
 268 function devices.
 269
 270 SDP interface support
 271 ~~~~~~~~~~~~~~~~~~~~~
 272 OCTEON TX2 SDP interface support is limited to PF device, No VF support.
 273
 274 Inline Protocol Processing
 275 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 276 ``net_octeontx2`` pmd doesn't support the following features for packets to be
 277 inline protocol processed.
 278 - TSO offload
 279 - VLAN/QinQ offload
 280 - Fragmentation
 281
 282 Debugging Options
 283 -----------------
 284
 285 .. _table_octeontx2_ethdev_debug_options:
 286
 287 .. table:: OCTEON TX2 ethdev debug options
 288
 289    +---+------------+-------------------------------------------------------+
 290    | # | Component  | EAL log command                                       |
 291    +===+============+=======================================================+
 292    | 1 | NIX        | --log-level='pmd\.net.octeontx2,8'                    |
 293    +---+------------+-------------------------------------------------------+
 294    | 2 | NPC        | --log-level='pmd\.net.octeontx2\.flow,8'              |
 295    +---+------------+-------------------------------------------------------+
 296
 297 RTE Flow Support
 298 ----------------
 299
 300 The OCTEON TX2 SoC family NIC has support for the following patterns and
 301 actions.
 302
 303 Patterns:
 304
 305 .. _table_octeontx2_supported_flow_item_types:
 306
 307 .. table:: Item types
 308
 309    +----+--------------------------------+
 310    | #  | Pattern Type                   |
 311    +====+================================+
 312    | 1  | RTE_FLOW_ITEM_TYPE_ETH         |
 313    +----+--------------------------------+
 314    | 2  | RTE_FLOW_ITEM_TYPE_VLAN        |
 315    +----+--------------------------------+
 316    | 3  | RTE_FLOW_ITEM_TYPE_E_TAG       |
 317    +----+--------------------------------+
 318    | 4  | RTE_FLOW_ITEM_TYPE_IPV4        |
 319    +----+--------------------------------+
 320    | 5  | RTE_FLOW_ITEM_TYPE_IPV6        |
 321    +----+--------------------------------+
 322    | 6  | RTE_FLOW_ITEM_TYPE_ARP_ETH_IPV4|
 323    +----+--------------------------------+
 324    | 7  | RTE_FLOW_ITEM_TYPE_MPLS        |
 325    +----+--------------------------------+
 326    | 8  | RTE_FLOW_ITEM_TYPE_ICMP        |
 327    +----+--------------------------------+
 328    | 9  | RTE_FLOW_ITEM_TYPE_UDP         |
 329    +----+--------------------------------+
 330    | 10 | RTE_FLOW_ITEM_TYPE_TCP         |
 331    +----+--------------------------------+
 332    | 11 | RTE_FLOW_ITEM_TYPE_SCTP        |
 333    +----+--------------------------------+
 334    | 12 | RTE_FLOW_ITEM_TYPE_ESP         |
 335    +----+--------------------------------+
 336    | 13 | RTE_FLOW_ITEM_TYPE_GRE         |
 337    +----+--------------------------------+
 338    | 14 | RTE_FLOW_ITEM_TYPE_NVGRE       |
 339    +----+--------------------------------+
 340    | 15 | RTE_FLOW_ITEM_TYPE_VXLAN       |
 341    +----+--------------------------------+
 342    | 16 | RTE_FLOW_ITEM_TYPE_GTPC        |
 343    +----+--------------------------------+
 344    | 17 | RTE_FLOW_ITEM_TYPE_GTPU        |
 345    +----+--------------------------------+
 346    | 18 | RTE_FLOW_ITEM_TYPE_GENEVE      |
 347    +----+--------------------------------+
 348    | 19 | RTE_FLOW_ITEM_TYPE_VXLAN_GPE   |
 349    +----+--------------------------------+
 350    | 20 | RTE_FLOW_ITEM_TYPE_IPV6_EXT    |
 351    +----+--------------------------------+
 352    | 21 | RTE_FLOW_ITEM_TYPE_VOID        |
 353    +----+--------------------------------+
 354    | 22 | RTE_FLOW_ITEM_TYPE_ANY         |
 355    +----+--------------------------------+
 356    | 23 | RTE_FLOW_ITEM_TYPE_GRE_KEY     |
 357    +----+--------------------------------+
 358    | 24 | RTE_FLOW_ITEM_TYPE_HIGIG2      |
 359    +----+--------------------------------+
 360
 361 .. note::
 362
 363    ``RTE_FLOW_ITEM_TYPE_GRE_KEY`` works only when checksum and routing
 364    bits in the GRE header are equal to 0.
 365
 366 Actions:
 367
 368 .. _table_octeontx2_supported_ingress_action_types:
 369
 370 .. table:: Ingress action types
 371
 372    +----+--------------------------------+
 373    | #  | Action Type                    |
 374    +====+================================+
 375    | 1  | RTE_FLOW_ACTION_TYPE_VOID      |
 376    +----+--------------------------------+
 377    | 2  | RTE_FLOW_ACTION_TYPE_MARK      |
 378    +----+--------------------------------+
 379    | 3  | RTE_FLOW_ACTION_TYPE_FLAG      |
 380    +----+--------------------------------+
 381    | 4  | RTE_FLOW_ACTION_TYPE_COUNT     |
 382    +----+--------------------------------+
 383    | 5  | RTE_FLOW_ACTION_TYPE_DROP      |
 384    +----+--------------------------------+
 385    | 6  | RTE_FLOW_ACTION_TYPE_QUEUE     |
 386    +----+--------------------------------+
 387    | 7  | RTE_FLOW_ACTION_TYPE_RSS       |
 388    +----+--------------------------------+
 389    | 8  | RTE_FLOW_ACTION_TYPE_SECURITY  |
 390    +----+--------------------------------+
 391    | 9  | RTE_FLOW_ACTION_TYPE_PF        |
 392    +----+--------------------------------+
 393    | 10 | RTE_FLOW_ACTION_TYPE_VF        |
 394    +----+--------------------------------+
 395
 396 .. _table_octeontx2_supported_egress_action_types:
 397
 398 .. table:: Egress action types
 399
 400    +----+--------------------------------+
 401    | #  | Action Type                    |
 402    +====+================================+
 403    | 1  | RTE_FLOW_ACTION_TYPE_COUNT     |
 404    +----+--------------------------------+
 405    | 2  | RTE_FLOW_ACTION_TYPE_DROP      |
 406    +----+--------------------------------+