doc/guides/nics/octeontx.rst

   1 ..  BSD LICENSE
   2     Copyright (C) Cavium, Inc. 2017.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Cavium, Inc nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 OCTEONTX Poll Mode driver
  32 =========================
  33
  34 The OCTEONTX ETHDEV PMD (**librte_pmd_octeontx**) provides poll mode ethdev
  35 driver support for the inbuilt network device found in the **Cavium OCTEONTX**
  36 SoC family as well as their virtual functions (VF) in SR-IOV context.
  37
  38 More information can be found at `Cavium, Inc Official Website
  39 <http://www.cavium.com/OCTEON-TX_ARM_Processors.html>`_.
  40
  41 Features
  42 --------
  43
  44 Features of the OCTEONTX Ethdev PMD are:
  45
  46 - Packet type information
  47 - Promiscuous mode
  48 - Port hardware statistics
  49 - Jumbo frames
  50 - Link state information
  51 - SR-IOV VF
  52 - Multiple queues for TX
  53 - Lock-free Tx queue
  54 - HW offloaded `ethdev Rx queue` to `eventdev event queue` packet injection
  55
  56 Supported OCTEONTX SoCs
  57 -----------------------
  58
  59 - CN83xx
  60
  61 Unsupported features
  62 --------------------
  63
  64 The features supported by the device and not yet supported by this PMD include:
  65
  66 - Receive Side Scaling (RSS)
  67 - Scattered and gather for TX and RX
  68 - Ingress classification support
  69 - Egress hierarchical scheduling, traffic shaping, and marking
  70
  71 Prerequisites
  72 -------------
  73
  74 See :doc:`../platform/octeontx` for setup information.
  75
  76 Pre-Installation Configuration
  77 ------------------------------
  78
  79 Config File Options
  80 ~~~~~~~~~~~~~~~~~~~
  81
  82 The following options can be modified in the ``config`` file.
  83 Please note that enabling debugging options may affect system performance.
  84
  85 - ``CONFIG_RTE_LIBRTE_OCTEONTX_PMD`` (default ``y``)
  86
  87   Toggle compilation of the ``librte_pmd_octeontx`` driver.
  88
  89 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_DRIVER`` (default ``n``)
  90
  91   Toggle display of generic debugging messages
  92
  93 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_INIT`` (default ``n``)
  94
  95   Toggle display of initialization related messages.
  96
  97 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_RX`` (default ``n``)
  98
  99   Toggle display of receive path message
 100
 101 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_TX`` (default ``n``)
 102
 103   Toggle display of transmit path message
 104
 105 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_MBOX`` (default ``n``)
 106
 107   Toggle display of mbox related message
 108
 109
 110 Driver compilation and testing
 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112
 113 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 114 for details.
 115
 116 To compile the OCTEONTX PMD for Linux arm64 gcc target, run the
 117 following ``make`` command:
 118
 119 .. code-block:: console
 120
 121    cd <DPDK-source-directory>
 122    make config T=arm64-thunderx-linuxapp-gcc install
 123
 124 #. Running testpmd:
 125
 126    Follow instructions available in the document
 127    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 128    to run testpmd.
 129
 130    Example output:
 131
 132    .. code-block:: console
 133
 134       ./arm64-thunderx-linuxapp-gcc/app/testpmd -c 700 \
 135                 --base-virtaddr=0x100000000000 \
 136                 --mbuf-pool-ops-name="octeontx_fpavf" \
 137                 --vdev='event_octeontx' \
 138                 --vdev='eth_octeontx,nr_port=2' \
 139                 -- --rxq=1 --txq=1 --nb-core=2 --total-num-mbufs=16384 \
 140                 --disable-hw-vlan-filter -i
 141       .....
 142       EAL: Detected 24 lcore(s)
 143       EAL: Probing VFIO support...
 144       EAL: VFIO support initialized
 145       .....
 146       EAL: PCI device 0000:07:00.1 on NUMA socket 0
 147       EAL:   probe driver: 177d:a04b octeontx_ssovf
 148       .....
 149       EAL: PCI device 0001:02:00.7 on NUMA socket 0
 150       EAL:   probe driver: 177d:a0dd octeontx_pkivf
 151       .....
 152       EAL: PCI device 0001:03:01.0 on NUMA socket 0
 153       EAL:   probe driver: 177d:a049 octeontx_pkovf
 154       .....
 155       PMD: octeontx_probe(): created ethdev eth_octeontx for port 0
 156       PMD: octeontx_probe(): created ethdev eth_octeontx for port 1
 157       .....
 158       Configuring Port 0 (socket 0)
 159       Port 0: 00:0F:B7:11:94:46
 160       Configuring Port 1 (socket 0)
 161       Port 1: 00:0F:B7:11:94:47
 162       .....
 163       Checking link statuses...
 164       Port 0 Link Up - speed 40000 Mbps - full-duplex
 165       Port 1 Link Up - speed 40000 Mbps - full-duplex
 166       Done
 167       testpmd>
 168
 169
 170 Initialization
 171 --------------
 172
 173 The octeontx ethdev pmd is exposed as a vdev device which consists of a set
 174 of PKI and PKO PCIe VF devices. On EAL initialization,
 175 PKI/PKO PCIe VF devices will be probed and then the vdev device can be created
 176 from the application code, or from the EAL command line based on
 177 the number of probed/bound PKI/PKO PCIe VF device to DPDK by
 178
 179 * Invoking ``rte_vdev_init("eth_octeontx")`` from the application
 180
 181 * Using ``--vdev="eth_octeontx"`` in the EAL options, which will call
 182   rte_vdev_init() internally
 183
 184 Device arguments
 185 ~~~~~~~~~~~~~~~~
 186 Each ethdev port is mapped to a physical port(LMAC), Application can specify
 187 the number of interesting ports with ``nr_ports`` argument.
 188
 189 Dependency
 190 ~~~~~~~~~~
 191 ``eth_octeontx`` pmd is depend on ``event_octeontx`` eventdev device and
 192 ``octeontx_fpavf`` external mempool handler.
 193
 194 Example:
 195
 196 .. code-block:: console
 197
 198     ./your_dpdk_application --mbuf-pool-ops="octeontx_fpavf" \
 199                 --vdev='event_octeontx' \
 200                 --vdev="eth_octeontx,nr_port=2"
 201
 202 Limitations
 203 -----------
 204
 205 ``octeontx_fpavf`` external mempool handler dependency
 206 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 207 The OCTEONTX SoC family NIC has inbuilt HW assisted external mempool manager.
 208 This driver will only work with ``octeontx_fpavf`` external mempool handler
 209 as it is the most performance effective way for packet allocation and Tx buffer
 210 recycling on OCTEONTX SoC platform.
 211
 212 CRC striping
 213 ~~~~~~~~~~~~
 214
 215 The OCTEONTX SoC family NICs strip the CRC for every packets coming into the
 216 host interface. So, CRC will be stripped even when the
 217 ``rxmode.hw_strip_crc`` member is set to 0 in ``struct rte_eth_conf``.
 218
 219 Maximum packet length
 220 ~~~~~~~~~~~~~~~~~~~~~
 221
 222 The OCTEONTX SoC family NICs support a maximum of a 32K jumbo frame. The value
 223 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 224 member of ``struct rte_eth_conf`` is set to a value lower than 32k, frames
 225 up to 32k bytes can still reach the host interface.