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 - ``Rx&Tx scalar mode enable`` (default ``0``)
 117
 118    Ethdev supports both scalar and vector mode, it may be selected at runtime
 119    using ``scalar_enable`` ``devargs`` parameter.
 120
 121 - ``RSS reta size`` (default ``64``)
 122
 123    RSS redirection table size may be configured during runtime using ``reta_size``
 124    ``devargs`` parameter.
 125
 126    For example::
 127
 128       -w 0002:02:00.0,reta_size=256
 129
 130    With the above configuration, reta table of size 256 is populated.
 131
 132 - ``Flow priority levels`` (default ``3``)
 133
 134    RTE Flow priority levels can be configured during runtime using
 135    ``flow_max_priority`` ``devargs`` parameter.
 136
 137    For example::
 138
 139       -w 0002:02:00.0,flow_max_priority=10
 140
 141    With the above configuration, priority level was set to 10 (0-9). Max
 142    priority level supported is 32.
 143
 144 - ``Reserve Flow entries`` (default ``8``)
 145
 146    RTE flow entries can be pre allocated and the size of pre allocation can be
 147    selected runtime using ``flow_prealloc_size`` ``devargs`` parameter.
 148
 149    For example::
 150
 151       -w 0002:02:00.0,flow_prealloc_size=4
 152
 153    With the above configuration, pre alloc size was set to 4. Max pre alloc
 154    size supported is 32.
 155
 156 - ``Max SQB buffer count`` (default ``512``)
 157
 158    Send queue descriptor buffer count may be limited during runtime using
 159    ``max_sqb_count`` ``devargs`` parameter.
 160
 161    For example::
 162
 163       -w 0002:02:00.0,max_sqb_count=64
 164
 165    With the above configuration, each send queue's decscriptor buffer count is
 166    limited to a maximum of 64 buffers.
 167
 168 - ``Switch header enable`` (default ``none``)
 169
 170    A port can be configured to a specific switch header type by using
 171    ``switch_header`` ``devargs`` parameter.
 172
 173    For example::
 174
 175       -w 0002:02:00.0,switch_header="higig2"
 176
 177    With the above configuration, higig2 will be enabled on that port and the
 178    traffic on this port should be higig2 traffic only. Supported switch header
 179    types are "higig2" and "dsa".
 180
 181 - ``RSS tag as XOR`` (default ``0``)
 182
 183    C0 HW revision onward, The HW gives an option to configure the RSS adder as
 184
 185    * ``rss_adder<7:0> = flow_tag<7:0> ^ flow_tag<15:8> ^ flow_tag<23:16> ^ flow_tag<31:24>``
 186
 187    * ``rss_adder<7:0> = flow_tag<7:0>``
 188
 189    Latter one aligns with standard NIC behavior vs former one is a legacy
 190    RSS adder scheme used in OCTEON TX2 products.
 191
 192    By default, the driver runs in the latter mode from C0 HW revision onward.
 193    Setting this flag to 1 to select the legacy mode.
 194
 195    For example to select the legacy mode(RSS tag adder as XOR)::
 196       -w 0002:02:00.0,tag_as_xor=1
 197
 198 .. note::
 199
 200    Above devarg parameters are configurable per device, user needs to pass the
 201    parameters to all the PCIe devices if application requires to configure on
 202    all the ethdev ports.
 203
 204 Limitations
 205 -----------
 206
 207 ``mempool_octeontx2`` external mempool handler dependency
 208 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 209
 210 The OCTEON TX2 SoC family NIC has inbuilt HW assisted external mempool manager.
 211 ``net_octeontx2`` pmd only works with ``mempool_octeontx2`` mempool handler
 212 as it is performance wise most effective way for packet allocation and Tx buffer
 213 recycling on OCTEON TX2 SoC platform.
 214
 215 CRC stripping
 216 ~~~~~~~~~~~~~
 217
 218 The OCTEON TX2 SoC family NICs strip the CRC for every packet being received by
 219 the host interface irrespective of the offload configuration.
 220
 221 Multicast MAC filtering
 222 ~~~~~~~~~~~~~~~~~~~~~~~
 223
 224 ``net_octeontx2`` pmd supports multicast mac filtering feature only on physical
 225 function devices.
 226
 227 SDP interface support
 228 ~~~~~~~~~~~~~~~~~~~~~
 229 OCTEON TX2 SDP interface support is limited to PF device, No VF support.
 230
 231 Debugging Options
 232 -----------------
 233
 234 .. _table_octeontx2_ethdev_debug_options:
 235
 236 .. table:: OCTEON TX2 ethdev debug options
 237
 238    +---+------------+-------------------------------------------------------+
 239    | # | Component  | EAL log command                                       |
 240    +===+============+=======================================================+
 241    | 1 | NIX        | --log-level='pmd\.net.octeontx2,8'                    |
 242    +---+------------+-------------------------------------------------------+
 243    | 2 | NPC        | --log-level='pmd\.net.octeontx2\.flow,8'              |
 244    +---+------------+-------------------------------------------------------+
 245
 246 RTE Flow Support
 247 ----------------
 248
 249 The OCTEON TX2 SoC family NIC has support for the following patterns and
 250 actions.
 251
 252 Patterns:
 253
 254 .. _table_octeontx2_supported_flow_item_types:
 255
 256 .. table:: Item types
 257
 258    +----+--------------------------------+
 259    | #  | Pattern Type                   |
 260    +====+================================+
 261    | 1  | RTE_FLOW_ITEM_TYPE_ETH         |
 262    +----+--------------------------------+
 263    | 2  | RTE_FLOW_ITEM_TYPE_VLAN        |
 264    +----+--------------------------------+
 265    | 3  | RTE_FLOW_ITEM_TYPE_E_TAG       |
 266    +----+--------------------------------+
 267    | 4  | RTE_FLOW_ITEM_TYPE_IPV4        |
 268    +----+--------------------------------+
 269    | 5  | RTE_FLOW_ITEM_TYPE_IPV6        |
 270    +----+--------------------------------+
 271    | 6  | RTE_FLOW_ITEM_TYPE_ARP_ETH_IPV4|
 272    +----+--------------------------------+
 273    | 7  | RTE_FLOW_ITEM_TYPE_MPLS        |
 274    +----+--------------------------------+
 275    | 8  | RTE_FLOW_ITEM_TYPE_ICMP        |
 276    +----+--------------------------------+
 277    | 9  | RTE_FLOW_ITEM_TYPE_UDP         |
 278    +----+--------------------------------+
 279    | 10 | RTE_FLOW_ITEM_TYPE_TCP         |
 280    +----+--------------------------------+
 281    | 11 | RTE_FLOW_ITEM_TYPE_SCTP        |
 282    +----+--------------------------------+
 283    | 12 | RTE_FLOW_ITEM_TYPE_ESP         |
 284    +----+--------------------------------+
 285    | 13 | RTE_FLOW_ITEM_TYPE_GRE         |
 286    +----+--------------------------------+
 287    | 14 | RTE_FLOW_ITEM_TYPE_NVGRE       |
 288    +----+--------------------------------+
 289    | 15 | RTE_FLOW_ITEM_TYPE_VXLAN       |
 290    +----+--------------------------------+
 291    | 16 | RTE_FLOW_ITEM_TYPE_GTPC        |
 292    +----+--------------------------------+
 293    | 17 | RTE_FLOW_ITEM_TYPE_GTPU        |
 294    +----+--------------------------------+
 295    | 18 | RTE_FLOW_ITEM_TYPE_GENEVE      |
 296    +----+--------------------------------+
 297    | 19 | RTE_FLOW_ITEM_TYPE_VXLAN_GPE   |
 298    +----+--------------------------------+
 299    | 20 | RTE_FLOW_ITEM_TYPE_IPV6_EXT    |
 300    +----+--------------------------------+
 301    | 21 | RTE_FLOW_ITEM_TYPE_VOID        |
 302    +----+--------------------------------+
 303    | 22 | RTE_FLOW_ITEM_TYPE_ANY         |
 304    +----+--------------------------------+
 305    | 23 | RTE_FLOW_ITEM_TYPE_GRE_KEY     |
 306    +----+--------------------------------+
 307    | 24 | RTE_FLOW_ITEM_TYPE_HIGIG2      |
 308    +----+--------------------------------+
 309
 310 .. note::
 311
 312    ``RTE_FLOW_ITEM_TYPE_GRE_KEY`` works only when checksum and routing
 313    bits in the GRE header are equal to 0.
 314
 315 Actions:
 316
 317 .. _table_octeontx2_supported_ingress_action_types:
 318
 319 .. table:: Ingress action types
 320
 321    +----+--------------------------------+
 322    | #  | Action Type                    |
 323    +====+================================+
 324    | 1  | RTE_FLOW_ACTION_TYPE_VOID      |
 325    +----+--------------------------------+
 326    | 2  | RTE_FLOW_ACTION_TYPE_MARK      |
 327    +----+--------------------------------+
 328    | 3  | RTE_FLOW_ACTION_TYPE_FLAG      |
 329    +----+--------------------------------+
 330    | 4  | RTE_FLOW_ACTION_TYPE_COUNT     |
 331    +----+--------------------------------+
 332    | 5  | RTE_FLOW_ACTION_TYPE_DROP      |
 333    +----+--------------------------------+
 334    | 6  | RTE_FLOW_ACTION_TYPE_QUEUE     |
 335    +----+--------------------------------+
 336    | 7  | RTE_FLOW_ACTION_TYPE_RSS       |
 337    +----+--------------------------------+
 338    | 8  | RTE_FLOW_ACTION_TYPE_SECURITY  |
 339    +----+--------------------------------+
 340    | 9  | RTE_FLOW_ACTION_TYPE_PF        |
 341    +----+--------------------------------+
 342    | 10 | RTE_FLOW_ACTION_TYPE_VF        |
 343    +----+--------------------------------+
 344
 345 .. _table_octeontx2_supported_egress_action_types:
 346
 347 .. table:: Egress action types
 348
 349    +----+--------------------------------+
 350    | #  | Action Type                    |
 351    +====+================================+
 352    | 1  | RTE_FLOW_ACTION_TYPE_COUNT     |
 353    +----+--------------------------------+
 354    | 2  | RTE_FLOW_ACTION_TYPE_DROP      |
 355    +----+--------------------------------+