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