doc/guides/nics/thunderx.rst

   1 ..  BSD LICENSE
   2     Copyright (C) Cavium networks Ltd. 2016.
   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 networks 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 ThunderX NICVF Poll Mode Driver
  32 ===============================
  33
  34 The ThunderX NICVF PMD (**librte_pmd_thunderx_nicvf**) provides poll mode driver
  35 support for the inbuilt NIC found in the **Cavium ThunderX** SoC family
  36 as well as their virtual functions (VF) in SR-IOV context.
  37
  38 More information can be found at `Cavium Networks Official Website
  39 <http://www.cavium.com/ThunderX_ARM_Processors.html>`_.
  40
  41 Features
  42 --------
  43
  44 Features of the ThunderX PMD are:
  45
  46 - Multiple queues for TX and RX
  47 - Receive Side Scaling (RSS)
  48 - Packet type information
  49 - Checksum offload
  50 - Promiscuous mode
  51 - Multicast mode
  52 - Port hardware statistics
  53 - Jumbo frames
  54 - Link state information
  55 - Scattered and gather for TX and RX
  56 - VLAN stripping
  57 - SR-IOV VF
  58 - NUMA support
  59
  60 Supported ThunderX SoCs
  61 -----------------------
  62 - CN88xx
  63 - CN81xx
  64
  65 Prerequisites
  66 -------------
  67 - Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
  68
  69 Pre-Installation Configuration
  70 ------------------------------
  71
  72 Config File Options
  73 ~~~~~~~~~~~~~~~~~~~
  74
  75 The following options can be modified in the ``config`` file.
  76 Please note that enabling debugging options may affect system performance.
  77
  78 - ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_PMD`` (default ``n``)
  79
  80   By default it is enabled only for defconfig_arm64-thunderx-* config.
  81   Toggle compilation of the ``librte_pmd_thunderx_nicvf`` driver.
  82
  83 - ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_INIT`` (default ``n``)
  84
  85   Toggle display of initialization related messages.
  86
  87 - ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_RX`` (default ``n``)
  88
  89   Toggle display of receive fast path run-time message
  90
  91 - ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_TX`` (default ``n``)
  92
  93   Toggle display of transmit fast path run-time message
  94
  95 - ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_DRIVER`` (default ``n``)
  96
  97   Toggle display of generic debugging messages
  98
  99 - ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_MBOX`` (default ``n``)
 100
 101   Toggle display of PF mailbox related run-time check messages
 102
 103 Driver Compilation
 104 ~~~~~~~~~~~~~~~~~~
 105
 106 To compile the ThunderX NICVF PMD for Linux arm64 gcc target, run the
 107 following “make” command:
 108
 109 .. code-block:: console
 110
 111    cd <DPDK-source-directory>
 112    make config T=arm64-thunderx-linuxapp-gcc install
 113
 114 Linux
 115 -----
 116
 117 .. _thunderx_testpmd_example:
 118
 119 Running testpmd
 120 ~~~~~~~~~~~~~~~
 121
 122 This section demonstrates how to launch ``testpmd`` with ThunderX NIC VF device
 123 managed by ``librte_pmd_thunderx_nicvf`` in the Linux operating system.
 124
 125 #. Load ``vfio-pci`` driver:
 126
 127    .. code-block:: console
 128
 129       modprobe vfio-pci
 130
 131    .. _thunderx_vfio_noiommu:
 132
 133 #. Enable **VFIO-NOIOMMU** mode (optional):
 134
 135    .. code-block:: console
 136
 137       echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
 138
 139    .. note::
 140
 141       **VFIO-NOIOMMU** is required only when running in VM context and should not be enabled otherwise.
 142       See also :ref:`SR-IOV: Prerequisites and sample Application Notes <thunderx_sriov_example>`.
 143
 144 #. Bind the ThunderX NIC VF device to ``vfio-pci`` loaded in the previous step:
 145
 146    Setup VFIO permissions for regular users and then bind to ``vfio-pci``:
 147
 148    .. code-block:: console
 149
 150       ./tools/dpdk-devbind.py --bind vfio-pci 0002:01:00.2
 151
 152 #. Start ``testpmd`` with basic parameters:
 153
 154    .. code-block:: console
 155
 156       ./arm64-thunderx-linuxapp-gcc/app/testpmd -c 0xf -n 4 -w 0002:01:00.2 \
 157         -- -i --disable-hw-vlan-filter --crc-strip --no-flush-rx \
 158         --port-topology=loop
 159
 160    Example output:
 161
 162    .. code-block:: console
 163
 164       ...
 165
 166       PMD: rte_nicvf_pmd_init(): librte_pmd_thunderx nicvf version 1.0
 167
 168       ...
 169       EAL:   probe driver: 177d:11 rte_nicvf_pmd
 170       EAL:   using IOMMU type 1 (Type 1)
 171       EAL:   PCI memory mapped at 0x3ffade50000
 172       EAL: Trying to map BAR 4 that contains the MSI-X table.
 173            Trying offsets: 0x40000000000:0x0000, 0x10000:0x1f0000
 174       EAL:   PCI memory mapped at 0x3ffadc60000
 175       PMD: nicvf_eth_dev_init(): nicvf: device (177d:11) 2:1:0:2
 176       PMD: nicvf_eth_dev_init(): node=0 vf=1 mode=tns-bypass sqs=false
 177            loopback_supported=true
 178       PMD: nicvf_eth_dev_init(): Port 0 (177d:11) mac=a6:c6:d9:17:78:01
 179       Interactive-mode selected
 180       Configuring Port 0 (socket 0)
 181       ...
 182
 183       PMD: nicvf_dev_configure(): Configured ethdev port0 hwcap=0x0
 184       Port 0: A6:C6:D9:17:78:01
 185       Checking link statuses...
 186       Port 0 Link Up - speed 10000 Mbps - full-duplex
 187       Done
 188       testpmd>
 189
 190 .. _thunderx_sriov_example:
 191
 192 SR-IOV: Prerequisites and sample Application Notes
 193 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 194
 195 Current ThunderX NIC PF/VF kernel modules maps each physical Ethernet port
 196 automatically to virtual function (VF) and presented them as PCIe-like SR-IOV device.
 197 This section provides instructions to configure SR-IOV with Linux OS.
 198
 199 #. Verify PF devices capabilities using ``lspci``:
 200
 201    .. code-block:: console
 202
 203       lspci -vvv
 204
 205    Example output:
 206
 207    .. code-block:: console
 208
 209       0002:01:00.0 Ethernet controller: Cavium Networks Device a01e (rev 01)
 210               ...
 211               Capabilities: [100 v1] Alternative Routing-ID Interpretation (ARI)
 212               ...
 213               Capabilities: [180 v1] Single Root I/O Virtualization (SR-IOV)
 214               ...
 215               Kernel driver in use: thunder-nic
 216               ...
 217
 218    .. note::
 219
 220       Unless ``thunder-nic`` driver is in use make sure your kernel config includes ``CONFIG_THUNDER_NIC_PF`` setting.
 221
 222 #. Verify VF devices capabilities and drivers using ``lspci``:
 223
 224    .. code-block:: console
 225
 226       lspci -vvv
 227
 228    Example output:
 229
 230    .. code-block:: console
 231
 232       0002:01:00.1 Ethernet controller: Cavium Networks Device 0011 (rev 01)
 233               ...
 234               Capabilities: [100 v1] Alternative Routing-ID Interpretation (ARI)
 235               ...
 236               Kernel driver in use: thunder-nicvf
 237               ...
 238
 239       0002:01:00.2 Ethernet controller: Cavium Networks Device 0011 (rev 01)
 240               ...
 241               Capabilities: [100 v1] Alternative Routing-ID Interpretation (ARI)
 242               ...
 243               Kernel driver in use: thunder-nicvf
 244               ...
 245
 246    .. note::
 247
 248       Unless ``thunder-nicvf`` driver is in use make sure your kernel config includes ``CONFIG_THUNDER_NIC_VF`` setting.
 249
 250 #. Verify PF/VF bind using ``dpdk-devbind.py``:
 251
 252    .. code-block:: console
 253
 254       ./tools/dpdk-devbind.py --status
 255
 256    Example output:
 257
 258    .. code-block:: console
 259
 260       ...
 261       0002:01:00.0 'Device a01e' if= drv=thunder-nic unused=vfio-pci
 262       0002:01:00.1 'Device 0011' if=eth0 drv=thunder-nicvf unused=vfio-pci
 263       0002:01:00.2 'Device 0011' if=eth1 drv=thunder-nicvf unused=vfio-pci
 264       ...
 265
 266 #. Load ``vfio-pci`` driver:
 267
 268    .. code-block:: console
 269
 270       modprobe vfio-pci
 271
 272 #. Bind VF devices to ``vfio-pci`` using ``dpdk-devbind.py``:
 273
 274    .. code-block:: console
 275
 276       ./tools/dpdk-devbind.py --bind vfio-pci 0002:01:00.1
 277       ./tools/dpdk-devbind.py --bind vfio-pci 0002:01:00.2
 278
 279 #. Verify VF bind using ``dpdk-devbind.py``:
 280
 281    .. code-block:: console
 282
 283       ./tools/dpdk-devbind.py --status
 284
 285    Example output:
 286
 287    .. code-block:: console
 288
 289       ...
 290       0002:01:00.1 'Device 0011' drv=vfio-pci unused=
 291       0002:01:00.2 'Device 0011' drv=vfio-pci unused=
 292       ...
 293       0002:01:00.0 'Device a01e' if= drv=thunder-nic unused=vfio-pci
 294       ...
 295
 296 #. Pass VF device to VM context (PCIe Passthrough):
 297
 298    The VF devices may be passed through to the guest VM using qemu or
 299    virt-manager or virsh etc.
 300    ``librte_pmd_thunderx_nicvf`` or ``thunder-nicvf`` should be used to bind
 301    the VF devices in the guest VM in :ref:`VFIO-NOIOMMU <thunderx_vfio_noiommu>` mode.
 302
 303    Example qemu guest launch command:
 304
 305    .. code-block:: console
 306
 307       sudo qemu-system-aarch64 -name vm1 \
 308       -machine virt,gic_version=3,accel=kvm,usb=off \
 309       -cpu host -m 4096 \
 310       -smp 4,sockets=1,cores=8,threads=1 \
 311       -nographic -nodefaults \
 312       -kernel <kernel image> \
 313       -append "root=/dev/vda console=ttyAMA0 rw hugepagesz=512M hugepages=3" \
 314       -device vfio-pci,host=0002:01:00.1 \
 315       -drive file=<rootfs.ext3>,if=none,id=disk1,format=raw  \
 316       -device virtio-blk-device,scsi=off,drive=disk1,id=virtio-disk1,bootindex=1 \
 317       -netdev tap,id=net0,ifname=tap0,script=/etc/qemu-ifup_thunder \
 318       -device virtio-net-device,netdev=net0 \
 319       -serial stdio \
 320       -mem-path /dev/huge
 321
 322 #. Refer to section :ref:`Running testpmd <thunderx_testpmd_example>` for instruction
 323    how to launch ``testpmd`` application.
 324
 325 Limitations
 326 -----------
 327
 328 CRC striping
 329 ~~~~~~~~~~~~
 330
 331 The ThunderX SoC family NICs strip the CRC for every packets coming into the
 332 host interface. So, CRC will be stripped even when the
 333 ``rxmode.hw_strip_crc`` member is set to 0 in ``struct rte_eth_conf``.
 334
 335 Maximum packet length
 336 ~~~~~~~~~~~~~~~~~~~~~
 337
 338 The ThunderX SoC family NICs support a maximum of a 9K jumbo frame. The value
 339 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 340 member of ``struct rte_eth_conf`` is set to a value lower than 9200, frames
 341 up to 9200 bytes can still reach the host interface.
 342
 343 Maximum packet segments
 344 ~~~~~~~~~~~~~~~~~~~~~~~
 345
 346 The ThunderX SoC family NICs support up to 12 segments per packet when working
 347 in scatter/gather mode. So, setting MTU will result with ``EINVAL`` when the
 348 frame size does not fit in the maximum number of segments.
 349
 350 Limited VFs
 351 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 352
 353 The ThunderX SoC family NICs has 128VFs and each VF has 8/8 queues
 354 for RX/TX respectively. Current driver implementation has one to one mapping
 355 between physical port and VF hence only limited VFs can be used.