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