doc/guides/nics/cnxk.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(C) 2021 Marvell.
   3
   4 CNXK Poll Mode driver
   5 =====================
   6
   7 The CNXK ETHDEV PMD (**librte_net_cnxk**) provides poll mode ethdev driver
   8 support for the inbuilt network device found in **Marvell OCTEON CN9K/CN10K**
   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 CNXK 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 filtering
  27 - Generic flow API
  28 - Inner and Outer Checksum offload
  29 - Port hardware statistics
  30 - Link state information
  31 - Link flow control
  32 - MTU update
  33 - Scatter-Gather IO support
  34 - Vector Poll mode driver
  35 - Support Rx interrupt
  36
  37 Prerequisites
  38 -------------
  39
  40 See :doc:`../platform/cnxk` for setup information.
  41
  42
  43 Driver compilation and testing
  44 ------------------------------
  45
  46 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
  47 for details.
  48
  49 #. Running testpmd:
  50
  51    Follow instructions available in the document
  52    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
  53    to run testpmd.
  54
  55    Example output:
  56
  57    .. code-block:: console
  58
  59       ./<build_dir>/app/dpdk-testpmd -c 0xc -a 0002:02:00.0 -- --portmask=0x1 --nb-cores=1 --port-topology=loop --rxq=1 --txq=1
  60       EAL: Detected 4 lcore(s)
  61       EAL: Detected 1 NUMA nodes
  62       EAL: Multi-process socket /var/run/dpdk/rte/mp_socket
  63       EAL: Selected IOVA mode 'VA'
  64       EAL: No available hugepages reported in hugepages-16777216kB
  65       EAL: No available hugepages reported in hugepages-2048kB
  66       EAL: Probing VFIO support...
  67       EAL: VFIO support initialized
  68       EAL:   using IOMMU type 1 (Type 1)
  69       [ 2003.202721] vfio-pci 0002:02:00.0: vfio_cap_init: hiding cap 0x14@0x98
  70       EAL: Probe PCI driver: net_cn10k (177d:a063) device: 0002:02:00.0 (socket 0)
  71       PMD: RoC Model: cn10k
  72       EAL: No legacy callbacks, legacy socket not created
  73       testpmd: create a new mbuf pool <mb_pool_0>: n=155456, size=2176, socket=0
  74       testpmd: preferred mempool ops selected: cn10k_mempool_ops
  75       Configuring Port 0 (socket 0)
  76       PMD: Port 0: Link Up - speed 25000 Mbps - full-duplex
  77
  78       Port 0: link state change event
  79       Port 0: 96:D4:99:72:A5:BF
  80       Checking link statuses...
  81       Done
  82       No commandline core given, start packet forwarding
  83       io packet forwarding - ports=1 - cores=1 - streams=1 - NUMA support enabled, MP allocation mode: native
  84       Logical Core 3 (socket 0) forwards packets on 1 streams:
  85         RX P=0/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
  86
  87         io packet forwarding packets/burst=32
  88         nb forwarding cores=1 - nb forwarding ports=1
  89         port 0: RX queue number: 1 Tx queue number: 1
  90           Rx offloads=0x0 Tx offloads=0x10000
  91           RX queue: 0
  92             RX desc=4096 - RX free threshold=0
  93             RX threshold registers: pthresh=0 hthresh=0  wthresh=0
  94             RX Offloads=0x0
  95           TX queue: 0
  96             TX desc=512 - TX free threshold=0
  97             TX threshold registers: pthresh=0 hthresh=0  wthresh=0
  98             TX offloads=0x0 - TX RS bit threshold=0
  99       Press enter to exit
 100
 101 Runtime Config Options
 102 ----------------------
 103
 104 - ``Rx&Tx scalar mode enable`` (default ``0``)
 105
 106    PMD supports both scalar and vector mode, it may be selected at runtime
 107    using ``scalar_enable`` ``devargs`` parameter.
 108
 109 - ``RSS reta size`` (default ``64``)
 110
 111    RSS redirection table size may be configured during runtime using ``reta_size``
 112    ``devargs`` parameter.
 113
 114    For example::
 115
 116       -a 0002:02:00.0,reta_size=256
 117
 118    With the above configuration, reta table of size 256 is populated.
 119
 120 - ``Flow priority levels`` (default ``3``)
 121
 122    RTE Flow priority levels can be configured during runtime using
 123    ``flow_max_priority`` ``devargs`` parameter.
 124
 125    For example::
 126
 127       -a 0002:02:00.0,flow_max_priority=10
 128
 129    With the above configuration, priority level was set to 10 (0-9). Max
 130    priority level supported is 32.
 131
 132 - ``Reserve Flow entries`` (default ``8``)
 133
 134    RTE flow entries can be pre allocated and the size of pre allocation can be
 135    selected runtime using ``flow_prealloc_size`` ``devargs`` parameter.
 136
 137    For example::
 138
 139       -a 0002:02:00.0,flow_prealloc_size=4
 140
 141    With the above configuration, pre alloc size was set to 4. Max pre alloc
 142    size supported is 32.
 143
 144 - ``Max SQB buffer count`` (default ``512``)
 145
 146    Send queue descriptor buffer count may be limited during runtime using
 147    ``max_sqb_count`` ``devargs`` parameter.
 148
 149    For example::
 150
 151       -a 0002:02:00.0,max_sqb_count=64
 152
 153    With the above configuration, each send queue's descriptor buffer count is
 154    limited to a maximum of 64 buffers.
 155
 156 - ``Switch header enable`` (default ``none``)
 157
 158    A port can be configured to a specific switch header type by using
 159    ``switch_header`` ``devargs`` parameter.
 160
 161    For example::
 162
 163       -a 0002:02:00.0,switch_header="higig2"
 164
 165    With the above configuration, higig2 will be enabled on that port and the
 166    traffic on this port should be higig2 traffic only. Supported switch header
 167    types are "higig2", "dsa", "chlen90b" and "chlen24b".
 168
 169 - ``RSS tag as XOR`` (default ``0``)
 170
 171    The HW gives two options to configure the RSS adder i.e
 172
 173    * ``rss_adder<7:0> = flow_tag<7:0> ^ flow_tag<15:8> ^ flow_tag<23:16> ^ flow_tag<31:24>``
 174
 175    * ``rss_adder<7:0> = flow_tag<7:0>``
 176
 177    Latter one aligns with standard NIC behavior vs former one is a legacy
 178    RSS adder scheme used in OCTEON TX2 products.
 179
 180    By default, the driver runs in the latter mode.
 181    Setting this flag to 1 to select the legacy mode.
 182
 183    For example to select the legacy mode(RSS tag adder as XOR)::
 184
 185       -a 0002:02:00.0,tag_as_xor=1
 186
 187
 188 .. note::
 189
 190    Above devarg parameters are configurable per device, user needs to pass the
 191    parameters to all the PCIe devices if application requires to configure on
 192    all the ethdev ports.
 193
 194 Limitations
 195 -----------
 196
 197 ``mempool_cnxk`` external mempool handler dependency
 198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 199
 200 The OCTEON CN9K/CN10K SoC family NIC has inbuilt HW assisted external mempool manager.
 201 ``net_cnxk`` pmd only works with ``mempool_cnxk`` mempool handler
 202 as it is performance wise most effective way for packet allocation and Tx buffer
 203 recycling on OCTEON TX2 SoC platform.
 204
 205 CRC stripping
 206 ~~~~~~~~~~~~~
 207
 208 The OCTEON CN9K/CN10K SoC family NICs strip the CRC for every packet being received by
 209 the host interface irrespective of the offload configuration.
 210
 211 RTE flow GRE support
 212 ~~~~~~~~~~~~~~~~~~~~
 213
 214 - ``RTE_FLOW_ITEM_TYPE_GRE_KEY`` works only when checksum and routing
 215   bits in the GRE header are equal to 0.
 216
 217 Debugging Options
 218 -----------------
 219
 220 .. _table_cnxk_ethdev_debug_options:
 221
 222 .. table:: cnxk ethdev debug options
 223
 224    +---+------------+-------------------------------------------------------+
 225    | # | Component  | EAL log command                                       |
 226    +===+============+=======================================================+
 227    | 1 | NIX        | --log-level='pmd\.net.cnxk,8'                         |
 228    +---+------------+-------------------------------------------------------+
 229    | 2 | NPC        | --log-level='pmd\.net.cnxk\.flow,8'                   |
 230    +---+------------+-------------------------------------------------------+