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