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