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 There are three main pre-perquisites for executing OCTEONTX PMD on a OCTEONTX
  75 compatible board:
  76
  77 1. **OCTEONTX Linux kernel PF driver for Network acceleration HW blocks**
  78
  79    The OCTEONTX Linux kernel drivers (including the required PF driver for the
  80    all network acceleration blocks) are available on GitHub at
  81    `octeontx-kmod <https://github.com/caviumnetworks/octeontx-kmod>`_
  82    along with build, install and dpdk usage instructions.
  83
  84 2. **ARM64 Tool Chain**
  85
  86    For example, the *aarch64* Linaro Toolchain, which can be obtained from
  87    `here <https://releases.linaro.org/components/toolchain/binaries/4.9-2017.01/aarch64-linux-gnu>`_.
  88
  89 3. **Rootfile system**
  90
  91    Any *aarch64* supporting filesystem can be used. For example,
  92    Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
  93    from `<http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
  94
  95    As an alternative method, OCTEONTX PMD can also be executed using images provided
  96    as part of SDK from Cavium. The SDK includes all the above prerequisites necessary
  97    to bring up a OCTEONTX board.
  98
  99    SDK and related information can be obtained from: `Cavium support site <https://support.cavium.com/>`_.
 100
 101 Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
 102
 103 Pre-Installation Configuration
 104 ------------------------------
 105
 106 Config File Options
 107 ~~~~~~~~~~~~~~~~~~~
 108
 109 The following options can be modified in the ``config`` file.
 110 Please note that enabling debugging options may affect system performance.
 111
 112 - ``CONFIG_RTE_LIBRTE_OCTEONTX_PMD`` (default ``y``)
 113
 114   Toggle compilation of the ``librte_pmd_octeontx`` driver.
 115
 116 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_DRIVER`` (default ``n``)
 117
 118   Toggle display of generic debugging messages
 119
 120 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_INIT`` (default ``n``)
 121
 122   Toggle display of initialization related messages.
 123
 124 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_RX`` (default ``n``)
 125
 126   Toggle display of receive path message
 127
 128 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_TX`` (default ``n``)
 129
 130   Toggle display of transmit path message
 131
 132 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_MBOX`` (default ``n``)
 133
 134   Toggle display of mbox related message
 135
 136
 137 Driver compilation and testing
 138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 139
 140 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 141 for details.
 142
 143 To compile the OCTEONTX PMD for Linux arm64 gcc target, run the
 144 following ``make`` command:
 145
 146 .. code-block:: console
 147
 148    cd <DPDK-source-directory>
 149    make config T=arm64-thunderx-linuxapp-gcc install
 150
 151 #. Running testpmd:
 152
 153    Follow instructions available in the document
 154    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 155    to run testpmd.
 156
 157    Example output:
 158
 159    .. code-block:: console
 160
 161       ./arm64-thunderx-linuxapp-gcc/app/testpmd -c 700 \
 162                 --base-virtaddr=0x100000000000 \
 163                 --mbuf-pool-ops-name="octeontx_fpavf" \
 164                 --vdev='event_octeontx' \
 165                 --vdev='eth_octeontx,nr_port=2' \
 166                 -- --rxq=1 --txq=1 --nb-core=2 --total-num-mbufs=16384 \
 167                 --disable-hw-vlan-filter -i
 168       .....
 169       EAL: Detected 24 lcore(s)
 170       EAL: Probing VFIO support...
 171       EAL: VFIO support initialized
 172       .....
 173       EAL: PCI device 0000:07:00.1 on NUMA socket 0
 174       EAL:   probe driver: 177d:a04b octeontx_ssovf
 175       .....
 176       EAL: PCI device 0001:02:00.7 on NUMA socket 0
 177       EAL:   probe driver: 177d:a0dd octeontx_pkivf
 178       .....
 179       EAL: PCI device 0001:03:01.0 on NUMA socket 0
 180       EAL:   probe driver: 177d:a049 octeontx_pkovf
 181       .....
 182       PMD: octeontx_probe(): created ethdev eth_octeontx for port 0
 183       PMD: octeontx_probe(): created ethdev eth_octeontx for port 1
 184       .....
 185       Configuring Port 0 (socket 0)
 186       Port 0: 00:0F:B7:11:94:46
 187       Configuring Port 1 (socket 0)
 188       Port 1: 00:0F:B7:11:94:47
 189       .....
 190       Checking link statuses...
 191       Port 0 Link Up - speed 40000 Mbps - full-duplex
 192       Port 1 Link Up - speed 40000 Mbps - full-duplex
 193       Done
 194       testpmd>
 195
 196
 197 Initialization
 198 --------------
 199
 200 The octeontx ethdev pmd is exposed as a vdev device which consists of a set
 201 of PKI and PKO PCIe VF devices. On EAL initialization,
 202 PKI/PKO PCIe VF devices will be probed and then the vdev device can be created
 203 from the application code, or from the EAL command line based on
 204 the number of probed/bound PKI/PKO PCIe VF device to DPDK by
 205
 206 * Invoking ``rte_vdev_init("eth_octeontx")`` from the application
 207
 208 * Using ``--vdev="eth_octeontx"`` in the EAL options, which will call
 209   rte_vdev_init() internally
 210
 211 Device arguments
 212 ~~~~~~~~~~~~~~~~
 213 Each ethdev port is mapped to a physical port(LMAC), Application can specify
 214 the number of interesting ports with ``nr_ports`` argument.
 215
 216 Dependency
 217 ~~~~~~~~~~
 218 ``eth_octeontx`` pmd is depend on ``event_octeontx`` eventdev device and
 219 ``octeontx_fpavf`` external mempool handler.
 220
 221 Example:
 222
 223 .. code-block:: console
 224
 225     ./your_dpdk_application --mbuf-pool-ops="octeontx_fpavf" \
 226                 --vdev='event_octeontx' \
 227                 --vdev="eth_octeontx,nr_port=2"
 228
 229 Limitations
 230 -----------
 231
 232 ``octeontx_fpavf`` external mempool handler dependency
 233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 234 The OCTEONTX SoC family NIC has inbuilt HW assisted external mempool manager.
 235 This driver will only work with ``octeontx_fpavf`` external mempool handler
 236 as it is the most performance effective way for packet allocation and Tx buffer
 237 recycling on OCTEONTX SoC platform.
 238
 239 CRC striping
 240 ~~~~~~~~~~~~
 241
 242 The OCTEONTX SoC family NICs strip the CRC for every packets coming into the
 243 host interface. So, CRC will be stripped even when the
 244 ``rxmode.hw_strip_crc`` member is set to 0 in ``struct rte_eth_conf``.
 245
 246 Maximum packet length
 247 ~~~~~~~~~~~~~~~~~~~~~
 248
 249 The OCTEONTX SoC family NICs support a maximum of a 32K jumbo frame. The value
 250 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 251 member of ``struct rte_eth_conf`` is set to a value lower than 32k, frames
 252 up to 32k bytes can still reach the host interface.