doc/guides/nics/octeontx.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Cavium, Inc
   3
   4 OCTEONTX Poll Mode driver
   5 =========================
   6
   7 The OCTEONTX ETHDEV PMD (**librte_pmd_octeontx**) provides poll mode ethdev
   8 driver support for the inbuilt network device found in the **Cavium OCTEONTX**
   9 SoC family as well as their virtual functions (VF) in SR-IOV context.
  10
  11 More information can be found at `Cavium, Inc Official Website
  12 <http://www.cavium.com/OCTEON-TX_ARM_Processors.html>`_.
  13
  14 Features
  15 --------
  16
  17 Features of the OCTEONTX Ethdev PMD are:
  18
  19 - Packet type information
  20 - Promiscuous mode
  21 - Port hardware statistics
  22 - Jumbo frames
  23 - Link state information
  24 - SR-IOV VF
  25 - Multiple queues for TX
  26 - Lock-free Tx queue
  27 - HW offloaded `ethdev Rx queue` to `eventdev event queue` packet injection
  28
  29 Supported OCTEONTX SoCs
  30 -----------------------
  31
  32 - CN83xx
  33
  34 Unsupported features
  35 --------------------
  36
  37 The features supported by the device and not yet supported by this PMD include:
  38
  39 - Receive Side Scaling (RSS)
  40 - Scattered and gather for TX and RX
  41 - Ingress classification support
  42 - Egress hierarchical scheduling, traffic shaping, and marking
  43
  44 Prerequisites
  45 -------------
  46
  47 See :doc:`../platform/octeontx` for setup information.
  48
  49 Pre-Installation Configuration
  50 ------------------------------
  51
  52 Config File Options
  53 ~~~~~~~~~~~~~~~~~~~
  54
  55 The following options can be modified in the ``config`` file.
  56 Please note that enabling debugging options may affect system performance.
  57
  58 - ``CONFIG_RTE_LIBRTE_OCTEONTX_PMD`` (default ``y``)
  59
  60   Toggle compilation of the ``librte_pmd_octeontx`` driver.
  61
  62 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_DRIVER`` (default ``n``)
  63
  64   Toggle display of generic debugging messages
  65
  66 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_INIT`` (default ``n``)
  67
  68   Toggle display of initialization related messages.
  69
  70 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_RX`` (default ``n``)
  71
  72   Toggle display of receive path message
  73
  74 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_TX`` (default ``n``)
  75
  76   Toggle display of transmit path message
  77
  78 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_MBOX`` (default ``n``)
  79
  80   Toggle display of mbox related message
  81
  82
  83 Driver compilation and testing
  84 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  85
  86 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
  87 for details.
  88
  89 To compile the OCTEONTX PMD for Linux arm64 gcc target, run the
  90 following ``make`` command:
  91
  92 .. code-block:: console
  93
  94    cd <DPDK-source-directory>
  95    make config T=arm64-thunderx-linuxapp-gcc install
  96
  97 #. Running testpmd:
  98
  99    Follow instructions available in the document
 100    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 101    to run testpmd.
 102
 103    Example output:
 104
 105    .. code-block:: console
 106
 107       ./arm64-thunderx-linuxapp-gcc/app/testpmd -c 700 \
 108                 --base-virtaddr=0x100000000000 \
 109                 --mbuf-pool-ops-name="octeontx_fpavf" \
 110                 --vdev='event_octeontx' \
 111                 --vdev='eth_octeontx,nr_port=2' \
 112                 -- --rxq=1 --txq=1 --nb-core=2 --total-num-mbufs=16384 \
 113                 --disable-hw-vlan-filter -i
 114       .....
 115       EAL: Detected 24 lcore(s)
 116       EAL: Probing VFIO support...
 117       EAL: VFIO support initialized
 118       .....
 119       EAL: PCI device 0000:07:00.1 on NUMA socket 0
 120       EAL:   probe driver: 177d:a04b octeontx_ssovf
 121       .....
 122       EAL: PCI device 0001:02:00.7 on NUMA socket 0
 123       EAL:   probe driver: 177d:a0dd octeontx_pkivf
 124       .....
 125       EAL: PCI device 0001:03:01.0 on NUMA socket 0
 126       EAL:   probe driver: 177d:a049 octeontx_pkovf
 127       .....
 128       PMD: octeontx_probe(): created ethdev eth_octeontx for port 0
 129       PMD: octeontx_probe(): created ethdev eth_octeontx for port 1
 130       .....
 131       Configuring Port 0 (socket 0)
 132       Port 0: 00:0F:B7:11:94:46
 133       Configuring Port 1 (socket 0)
 134       Port 1: 00:0F:B7:11:94:47
 135       .....
 136       Checking link statuses...
 137       Port 0 Link Up - speed 40000 Mbps - full-duplex
 138       Port 1 Link Up - speed 40000 Mbps - full-duplex
 139       Done
 140       testpmd>
 141
 142
 143 Initialization
 144 --------------
 145
 146 The octeontx ethdev pmd is exposed as a vdev device which consists of a set
 147 of PKI and PKO PCIe VF devices. On EAL initialization,
 148 PKI/PKO PCIe VF devices will be probed and then the vdev device can be created
 149 from the application code, or from the EAL command line based on
 150 the number of probed/bound PKI/PKO PCIe VF device to DPDK by
 151
 152 * Invoking ``rte_vdev_init("eth_octeontx")`` from the application
 153
 154 * Using ``--vdev="eth_octeontx"`` in the EAL options, which will call
 155   rte_vdev_init() internally
 156
 157 Device arguments
 158 ~~~~~~~~~~~~~~~~
 159 Each ethdev port is mapped to a physical port(LMAC), Application can specify
 160 the number of interesting ports with ``nr_ports`` argument.
 161
 162 Dependency
 163 ~~~~~~~~~~
 164 ``eth_octeontx`` pmd is depend on ``event_octeontx`` eventdev device and
 165 ``octeontx_fpavf`` external mempool handler.
 166
 167 Example:
 168
 169 .. code-block:: console
 170
 171     ./your_dpdk_application --mbuf-pool-ops-name="octeontx_fpavf" \
 172                 --vdev='event_octeontx' \
 173                 --vdev="eth_octeontx,nr_port=2"
 174
 175 Limitations
 176 -----------
 177
 178 ``octeontx_fpavf`` external mempool handler dependency
 179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 180 The OCTEONTX SoC family NIC has inbuilt HW assisted external mempool manager.
 181 This driver will only work with ``octeontx_fpavf`` external mempool handler
 182 as it is the most performance effective way for packet allocation and Tx buffer
 183 recycling on OCTEONTX SoC platform.
 184
 185 CRC striping
 186 ~~~~~~~~~~~~
 187
 188 The OCTEONTX SoC family NICs strip the CRC for every packets coming into the
 189 host interface. So, CRC will be stripped even when the
 190 ``rxmode.hw_strip_crc`` member is set to 0 in ``struct rte_eth_conf``.
 191
 192 Maximum packet length
 193 ~~~~~~~~~~~~~~~~~~~~~
 194
 195 The OCTEONTX SoC family NICs support a maximum of a 32K jumbo frame. The value
 196 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 197 member of ``struct rte_eth_conf`` is set to a value lower than 32k, frames
 198 up to 32k bytes can still reach the host interface.