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 - ``switch header enable`` (default ``none``)
 174
 175    A port can be configured to a specific switch header type by using
 176    ``switch_header`` ``devargs`` parameter.
 177
 178    For example::
 179
 180       -w 0002:02:00.0,switch_header="higig2"
 181
 182    With the above configuration, higig2 will be enabled on that port and the
 183    traffic on this port should be higig2 traffic only. Supported switch header
 184    types are "higig2" and "dsa".
 185
 186 .. note::
 187
 188    Above devarg parameters are configurable per device, user needs to pass the
 189    parameters to all the PCIe devices if application requires to configure on
 190    all the ethdev ports.
 191
 192 Limitations
 193 -----------
 194
 195 ``mempool_octeontx2`` external mempool handler dependency
 196 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 197
 198 The OCTEON TX2 SoC family NIC has inbuilt HW assisted external mempool manager.
 199 ``net_octeontx2`` pmd only works with ``mempool_octeontx2`` mempool handler
 200 as it is performance wise most effective way for packet allocation and Tx buffer
 201 recycling on OCTEON TX2 SoC platform.
 202
 203 CRC stripping
 204 ~~~~~~~~~~~~~
 205
 206 The OCTEON TX2 SoC family NICs strip the CRC for every packet being received by
 207 the host interface irrespective of the offload configuration.
 208
 209 Multicast MAC filtering
 210 ~~~~~~~~~~~~~~~~~~~~~~~
 211
 212 ``net_octeontx2`` pmd supports multicast mac filtering feature only on physical
 213 function devices.
 214
 215 Debugging Options
 216 -----------------
 217
 218 .. _table_octeontx2_ethdev_debug_options:
 219
 220 .. table:: OCTEON TX2 ethdev debug options
 221
 222    +---+------------+-------------------------------------------------------+
 223    | # | Component  | EAL log command                                       |
 224    +===+============+=======================================================+
 225    | 1 | NIX        | --log-level='pmd\.net.octeontx2,8'                    |
 226    +---+------------+-------------------------------------------------------+
 227    | 2 | NPC        | --log-level='pmd\.net.octeontx2\.flow,8'              |
 228    +---+------------+-------------------------------------------------------+
 229
 230 RTE Flow Support
 231 ----------------
 232
 233 The OCTEON TX2 SoC family NIC has support for the following patterns and
 234 actions.
 235
 236 Patterns:
 237
 238 .. _table_octeontx2_supported_flow_item_types:
 239
 240 .. table:: Item types
 241
 242    +----+--------------------------------+
 243    | #  | Pattern Type                   |
 244    +====+================================+
 245    | 1  | RTE_FLOW_ITEM_TYPE_ETH         |
 246    +----+--------------------------------+
 247    | 2  | RTE_FLOW_ITEM_TYPE_VLAN        |
 248    +----+--------------------------------+
 249    | 3  | RTE_FLOW_ITEM_TYPE_E_TAG       |
 250    +----+--------------------------------+
 251    | 4  | RTE_FLOW_ITEM_TYPE_IPV4        |
 252    +----+--------------------------------+
 253    | 5  | RTE_FLOW_ITEM_TYPE_IPV6        |
 254    +----+--------------------------------+
 255    | 6  | RTE_FLOW_ITEM_TYPE_ARP_ETH_IPV4|
 256    +----+--------------------------------+
 257    | 7  | RTE_FLOW_ITEM_TYPE_MPLS        |
 258    +----+--------------------------------+
 259    | 8  | RTE_FLOW_ITEM_TYPE_ICMP        |
 260    +----+--------------------------------+
 261    | 9  | RTE_FLOW_ITEM_TYPE_UDP         |
 262    +----+--------------------------------+
 263    | 10 | RTE_FLOW_ITEM_TYPE_TCP         |
 264    +----+--------------------------------+
 265    | 11 | RTE_FLOW_ITEM_TYPE_SCTP        |
 266    +----+--------------------------------+
 267    | 12 | RTE_FLOW_ITEM_TYPE_ESP         |
 268    +----+--------------------------------+
 269    | 13 | RTE_FLOW_ITEM_TYPE_GRE         |
 270    +----+--------------------------------+
 271    | 14 | RTE_FLOW_ITEM_TYPE_NVGRE       |
 272    +----+--------------------------------+
 273    | 15 | RTE_FLOW_ITEM_TYPE_VXLAN       |
 274    +----+--------------------------------+
 275    | 16 | RTE_FLOW_ITEM_TYPE_GTPC        |
 276    +----+--------------------------------+
 277    | 17 | RTE_FLOW_ITEM_TYPE_GTPU        |
 278    +----+--------------------------------+
 279    | 18 | RTE_FLOW_ITEM_TYPE_GENEVE      |
 280    +----+--------------------------------+
 281    | 19 | RTE_FLOW_ITEM_TYPE_VXLAN_GPE   |
 282    +----+--------------------------------+
 283    | 20 | RTE_FLOW_ITEM_TYPE_IPV6_EXT    |
 284    +----+--------------------------------+
 285    | 21 | RTE_FLOW_ITEM_TYPE_VOID        |
 286    +----+--------------------------------+
 287    | 22 | RTE_FLOW_ITEM_TYPE_ANY         |
 288    +----+--------------------------------+
 289    | 23 | RTE_FLOW_ITEM_TYPE_GRE_KEY     |
 290    +----+--------------------------------+
 291
 292 .. note::
 293
 294    ``RTE_FLOW_ITEM_TYPE_GRE_KEY`` works only when checksum and routing
 295    bits in the GRE header are equal to 0.
 296
 297 Actions:
 298
 299 .. _table_octeontx2_supported_ingress_action_types:
 300
 301 .. table:: Ingress action types
 302
 303    +----+--------------------------------+
 304    | #  | Action Type                    |
 305    +====+================================+
 306    | 1  | RTE_FLOW_ACTION_TYPE_VOID      |
 307    +----+--------------------------------+
 308    | 2  | RTE_FLOW_ACTION_TYPE_MARK      |
 309    +----+--------------------------------+
 310    | 3  | RTE_FLOW_ACTION_TYPE_FLAG      |
 311    +----+--------------------------------+
 312    | 4  | RTE_FLOW_ACTION_TYPE_COUNT     |
 313    +----+--------------------------------+
 314    | 5  | RTE_FLOW_ACTION_TYPE_DROP      |
 315    +----+--------------------------------+
 316    | 6  | RTE_FLOW_ACTION_TYPE_QUEUE     |
 317    +----+--------------------------------+
 318    | 7  | RTE_FLOW_ACTION_TYPE_RSS       |
 319    +----+--------------------------------+
 320    | 8  | RTE_FLOW_ACTION_TYPE_SECURITY  |
 321    +----+--------------------------------+
 322    | 9  | RTE_FLOW_ACTION_TYPE_PF        |
 323    +----+--------------------------------+
 324    | 10 | RTE_FLOW_ACTION_TYPE_VF        |
 325    +----+--------------------------------+
 326
 327 .. _table_octeontx2_supported_egress_action_types:
 328
 329 .. table:: Egress action types
 330
 331    +----+--------------------------------+
 332    | #  | Action Type                    |
 333    +====+================================+
 334    | 1  | RTE_FLOW_ACTION_TYPE_COUNT     |
 335    +----+--------------------------------+
 336    | 2  | RTE_FLOW_ACTION_TYPE_DROP      |
 337    +----+--------------------------------+