doc/guides/nics/cxgbe.rst

   1 ..  BSD LICENSE
   2     Copyright 2015 Chelsio Communications.
   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 Chelsio Communications 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 CXGBE Poll Mode Driver
  32 ======================
  33
  34 The CXGBE PMD (**librte_pmd_cxgbe**) provides poll mode driver support
  35 for **Chelsio T5** 10/40 Gbps family of adapters. CXGBE PMD has support
  36 for the latest Linux and FreeBSD operating systems.
  37
  38 More information can be found at `Chelsio Communications Official Website
  39 <http://www.chelsio.com>`_.
  40
  41 Features
  42 --------
  43
  44 CXGBE PMD has support for:
  45
  46 - Multiple queues for TX and RX
  47 - Receiver Side Steering (RSS)
  48 - VLAN filtering
  49 - Checksum offload
  50 - Promiscuous mode
  51 - All multicast mode
  52 - Port hardware statistics
  53
  54 Limitations
  55 -----------
  56
  57 The Chelsio T5 devices provide two/four ports but expose a single PCI bus
  58 address, thus, librte_pmd_cxgbe registers itself as a
  59 PCI driver that allocates one Ethernet device per detected port.
  60
  61 For this reason, one cannot whitelist/blacklist a single port without
  62 whitelisting/blacklisting the other ports on the same device.
  63
  64 Supported Chelsio T5 NICs
  65 -------------------------
  66
  67 - 1G NICs: T502-BT
  68 - 10G NICs: T520-BT, T520-CR, T520-LL-CR, T520-SO-CR, T540-CR
  69 - 40G NICs: T580-CR, T580-LP-CR, T580-SO-CR
  70 - Other T5 NICs: T522-CR
  71
  72 Prerequisites
  73 -------------
  74
  75 - Requires firmware version **1.13.32.0** and higher. Visit
  76   `Chelsio Download Center <http://service.chelsio.com>`_ to get latest firmware
  77   bundled with the latest Chelsio Unified Wire package.
  78
  79   For Linux, installing and loading the latest cxgb4 kernel driver from the
  80   Chelsio Unified Wire package should get you the latest firmware. More
  81   information can be obtained from the User Guide that is bundled with the
  82   Chelsio Unified Wire package.
  83
  84   For FreeBSD, the latest firmware obtained from the Chelsio Unified Wire
  85   package must be manually flashed via cxgbetool available in FreeBSD source
  86   repository.
  87
  88   Instructions on how to manually flash the firmware are given in section
  89   :ref:`linux-installation` for Linux and section :ref:`freebsd-installation`
  90   for FreeBSD.
  91
  92 Pre-Installation Configuration
  93 ------------------------------
  94
  95 Config File Options
  96 ~~~~~~~~~~~~~~~~~~~
  97
  98 The following options can be modified in the ``.config`` file. Please note that
  99 enabling debugging options may affect system performance.
 100
 101 - ``CONFIG_RTE_LIBRTE_CXGBE_PMD`` (default **y**)
 102
 103   Toggle compilation of librte_pmd_cxgbe driver.
 104
 105 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG`` (default **n**)
 106
 107   Toggle display of generic debugging messages.
 108
 109 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_REG`` (default **n**)
 110
 111   Toggle display of registers related run-time check messages.
 112
 113 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_MBOX`` (default **n**)
 114
 115   Toggle display of firmware mailbox related run-time check messages.
 116
 117 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_TX`` (default **n**)
 118
 119   Toggle display of transmission data path run-time check messages.
 120
 121 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_RX`` (default **n**)
 122
 123   Toggle display of receiving data path run-time check messages.
 124
 125 .. _driver-compilation:
 126
 127 Driver Compilation
 128 ~~~~~~~~~~~~~~~~~~
 129
 130 To compile CXGBE PMD for Linux x86_64 gcc target, run the following "make"
 131 command:
 132
 133 .. code-block:: console
 134
 135    cd <DPDK-source-directory>
 136    make config T=x86_64-native-linuxapp-gcc install
 137
 138 To compile CXGBE PMD for FreeBSD x86_64 clang target, run the following "gmake"
 139 command:
 140
 141 .. code-block:: console
 142
 143    cd <DPDK-source-directory>
 144    gmake config T=x86_64-native-bsdapp-clang install
 145
 146 Linux
 147 -----
 148
 149 .. _linux-installation:
 150
 151 Linux Installation
 152 ~~~~~~~~~~~~~~~~~~
 153
 154 Steps to manually install the latest firmware from the downloaded Chelsio
 155 Unified Wire package for Linux operating system are as follows:
 156
 157 #. Load the kernel module:
 158
 159    .. code-block:: console
 160
 161       modprobe cxgb4
 162
 163 #. Use ifconfig to get the interface name assigned to Chelsio card:
 164
 165    .. code-block:: console
 166
 167       ifconfig -a | grep "00:07:43"
 168
 169    Example output:
 170
 171    .. code-block:: console
 172
 173       p1p1      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C0
 174       p1p2      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C8
 175
 176 #. Install cxgbtool:
 177
 178    .. code-block:: console
 179
 180       cd <path_to_uwire>/tools/cxgbtool
 181       make install
 182
 183 #. Use cxgbtool to load the firmware config file onto the card:
 184
 185    .. code-block:: console
 186
 187       cxgbtool p1p1 loadcfg <path_to_uwire>/src/network/firmware/t5-config.txt
 188
 189 #. Use cxgbtool to load the firmware image onto the card:
 190
 191    .. code-block:: console
 192
 193       cxgbtool p1p1 loadfw <path_to_uwire>/src/network/firmware/t5fw-*.bin
 194
 195 #. Unload and reload the kernel module:
 196
 197    .. code-block:: console
 198
 199       modprobe -r cxgb4
 200       modprobe cxgb4
 201
 202 #. Verify with ethtool:
 203
 204    .. code-block:: console
 205
 206       ethtool -i p1p1 | grep "firmware"
 207
 208    Example output:
 209
 210    .. code-block:: console
 211
 212       firmware-version: 1.13.32.0, TP 0.1.4.8
 213
 214 Sample Application Notes
 215 ~~~~~~~~~~~~~~~~~~~~~~~~
 216
 217 This section demonstrates how to launch **testpmd** with Chelsio T5
 218 devices managed by librte_pmd_cxgbe in Linux operating system.
 219
 220 #. Change to DPDK source directory where the target has been compiled in
 221    section :ref:`driver-compilation`:
 222
 223    .. code-block:: console
 224
 225       cd <DPDK-source-directory>
 226
 227 #. Load the kernel module:
 228
 229    .. code-block:: console
 230
 231       modprobe cxgb4
 232
 233 #. Get the PCI bus addresses of the interfaces bound to cxgb4 driver:
 234
 235    .. code-block:: console
 236
 237       dmesg | tail -2
 238
 239    Example output:
 240
 241    .. code-block:: console
 242
 243       cxgb4 0000:02:00.4 p1p1: renamed from eth0
 244       cxgb4 0000:02:00.4 p1p2: renamed from eth1
 245
 246    .. note::
 247
 248       Both the interfaces of a Chelsio T5 2-port adapter are bound to the
 249       same PCI bus address.
 250
 251 #. Unload the kernel module:
 252
 253    .. code-block:: console
 254
 255       modprobe -ar cxgb4 csiostor
 256
 257 #. Request huge pages:
 258
 259    .. code-block:: console
 260
 261       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
 262
 263 #. Load igb_uio or vfio-pci driver:
 264
 265    .. code-block:: console
 266
 267       insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
 268
 269    or
 270
 271    .. code-block:: console
 272
 273       modprobe vfio-pci
 274
 275 #. Bind the Chelsio T5 adapters to igb_uio or vfio-pci loaded in the previous
 276    step:
 277
 278    .. code-block:: console
 279
 280       ./tools/dpdk_nic_bind.py --bind igb_uio 0000:02:00.4
 281
 282    or
 283
 284    Setup VFIO permissions for regular users and then bind to vfio-pci:
 285
 286    .. code-block:: console
 287
 288       sudo chmod a+x /dev/vfio
 289
 290       sudo chmod 0666 /dev/vfio/*
 291
 292       ./tools/dpdk_nic_bind.py --bind vfio-pci 0000:02:00.4
 293
 294    .. note::
 295
 296       Currently, CXGBE PMD only supports the binding of PF4 for Chelsio T5 NICs.
 297
 298 #. Start testpmd with basic parameters:
 299
 300    .. code-block:: console
 301
 302       ./x86_64-native-linuxapp-gcc/app/testpmd -c 0xf -n 4 -w 0000:02:00.4 -- -i
 303
 304    Example output:
 305
 306    .. code-block:: console
 307
 308       [...]
 309       EAL: PCI device 0000:02:00.4 on NUMA socket -1
 310       EAL:   probe driver: 1425:5401 rte_cxgbe_pmd
 311       EAL:   PCI memory mapped at 0x7fd7c0200000
 312       EAL:   PCI memory mapped at 0x7fd77cdfd000
 313       EAL:   PCI memory mapped at 0x7fd7c10b7000
 314       PMD: rte_cxgbe_pmd: fw: 1.13.32.0, TP: 0.1.4.8
 315       PMD: rte_cxgbe_pmd: Coming up as MASTER: Initializing adapter
 316       Interactive-mode selected
 317       Configuring Port 0 (socket 0)
 318       Port 0: 00:07:43:2D:EA:C0
 319       Configuring Port 1 (socket 0)
 320       Port 1: 00:07:43:2D:EA:C8
 321       Checking link statuses...
 322       PMD: rte_cxgbe_pmd: Port0: passive DA port module inserted
 323       PMD: rte_cxgbe_pmd: Port1: passive DA port module inserted
 324       Port 0 Link Up - speed 10000 Mbps - full-duplex
 325       Port 1 Link Up - speed 10000 Mbps - full-duplex
 326       Done
 327       testpmd>
 328
 329 .. note::
 330
 331    Flow control pause TX/RX is disabled by default and can be enabled via
 332    testpmd as follows:
 333
 334    .. code-block:: console
 335
 336       testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 0
 337       testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 1
 338
 339    To disable again, use:
 340
 341    .. code-block:: console
 342
 343       testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 0
 344       testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 1
 345
 346 FreeBSD
 347 -------
 348
 349 .. _freebsd-installation:
 350
 351 FreeBSD Installation
 352 ~~~~~~~~~~~~~~~~~~~~
 353
 354 Steps to manually install the latest firmware from the downloaded Chelsio
 355 Unified Wire package for FreeBSD operating system are as follows:
 356
 357 #. Load the kernel module:
 358
 359    .. code-block:: console
 360
 361       kldload if_cxgbe
 362
 363 #. Use dmesg to get the t5nex instance assigned to the Chelsio card:
 364
 365    .. code-block:: console
 366
 367       dmesg | grep "t5nex"
 368
 369    Example output:
 370
 371    .. code-block:: console
 372
 373       t5nex0: <Chelsio T520-CR> irq 16 at device 0.4 on pci2
 374       cxl0: <port 0> on t5nex0
 375       cxl1: <port 1> on t5nex0
 376       t5nex0: PCIe x8, 2 ports, 14 MSI-X interrupts, 31 eq, 13 iq
 377
 378    In the example above, a Chelsio T520-CR card is bound to a t5nex0 instance.
 379
 380 #. Install cxgbetool from FreeBSD source repository:
 381
 382    .. code-block:: console
 383
 384       cd <path_to_FreeBSD_source>/tools/tools/cxgbetool/
 385       make && make install
 386
 387 #. Use cxgbetool to load the firmware image onto the card:
 388
 389    .. code-block:: console
 390
 391       cxgbetool t5nex0 loadfw <path_to_uwire>/src/network/firmware/t5fw-*.bin
 392
 393 #. Unload and reload the kernel module:
 394
 395    .. code-block:: console
 396
 397       kldunload if_cxgbe
 398       kldload if_cxgbe
 399
 400 #. Verify with sysctl:
 401
 402    .. code-block:: console
 403
 404       sysctl -a | grep "t5nex" | grep "firmware"
 405
 406    Example output:
 407
 408    .. code-block:: console
 409
 410       dev.t5nex.0.firmware_version: 1.13.32.0
 411
 412 Sample Application Notes
 413 ~~~~~~~~~~~~~~~~~~~~~~~~
 414
 415 This section demonstrates how to launch **testpmd** with Chelsio T5
 416 devices managed by librte_pmd_cxgbe in FreeBSD operating system.
 417
 418 #. Change to DPDK source directory where the target has been compiled in
 419    section :ref:`driver-compilation`:
 420
 421    .. code-block:: console
 422
 423       cd <DPDK-source-directory>
 424
 425 #. Copy the contigmem kernel module to /boot/kernel directory:
 426
 427    .. code-block:: console
 428
 429       cp x86_64-native-bsdapp-clang/kmod/contigmem.ko /boot/kernel/
 430
 431 #. Add the following lines to /boot/loader.conf:
 432
 433    .. code-block:: console
 434
 435       # reserve 2 x 1G blocks of contiguous memory using contigmem driver
 436       hw.contigmem.num_buffers=2
 437       hw.contigmem.buffer_size=1073741824
 438       # load contigmem module during boot process
 439       contigmem_load="YES"
 440
 441    The above lines load the contigmem kernel module during boot process and
 442    allocate 2 x 1G blocks of contiguous memory to be used for DPDK later on.
 443    This is to avoid issues with potential memory fragmentation during later
 444    system up time, which may result in failure of allocating the contiguous
 445    memory required for the contigmem kernel module.
 446
 447 #. Restart the system and ensure the contigmem module is loaded successfully:
 448
 449    .. code-block:: console
 450
 451       reboot
 452       kldstat | grep "contigmem"
 453
 454    Example output:
 455
 456    .. code-block:: console
 457
 458       2    1 0xffffffff817f1000 3118     contigmem.ko
 459
 460 #. Repeat step 1 to ensure that you are in the DPDK source directory.
 461
 462 #. Load the cxgbe kernel module:
 463
 464    .. code-block:: console
 465
 466       kldload if_cxgbe
 467
 468 #. Get the PCI bus addresses of the interfaces bound to t5nex driver:
 469
 470    .. code-block:: console
 471
 472       pciconf -l | grep "t5nex"
 473
 474    Example output:
 475
 476    .. code-block:: console
 477
 478       t5nex0@pci0:2:0:4: class=0x020000 card=0x00001425 chip=0x54011425 rev=0x00
 479
 480    In the above example, the t5nex0 is bound to 2:0:4 bus address.
 481
 482    .. note::
 483
 484       Both the interfaces of a Chelsio T5 2-port adapter are bound to the
 485       same PCI bus address.
 486
 487 #. Unload the kernel module:
 488
 489    .. code-block:: console
 490
 491       kldunload if_cxgbe
 492
 493 #. Set the PCI bus addresses to hw.nic_uio.bdfs kernel environment parameter:
 494
 495    .. code-block:: console
 496
 497       kenv hw.nic_uio.bdfs="2:0:4"
 498
 499    This automatically binds 2:0:4 to nic_uio kernel driver when it is loaded in
 500    the next step.
 501
 502    .. note::
 503
 504       Currently, CXGBE PMD only supports the binding of PF4 for Chelsio T5 NICs.
 505
 506 #. Load nic_uio kernel driver:
 507
 508    .. code-block:: console
 509
 510       kldload ./x86_64-native-bsdapp-clang/kmod/nic_uio.ko
 511
 512 #. Start testpmd with basic parameters:
 513
 514    .. code-block:: console
 515
 516       ./x86_64-native-bsdapp-clang/app/testpmd -c 0xf -n 4 -w 0000:02:00.4 -- -i
 517
 518    Example output:
 519
 520    .. code-block:: console
 521
 522       [...]
 523       EAL: PCI device 0000:02:00.4 on NUMA socket 0
 524       EAL:   probe driver: 1425:5401 rte_cxgbe_pmd
 525       EAL:   PCI memory mapped at 0x8007ec000
 526       EAL:   PCI memory mapped at 0x842800000
 527       EAL:   PCI memory mapped at 0x80086c000
 528       PMD: rte_cxgbe_pmd: fw: 1.13.32.0, TP: 0.1.4.8
 529       PMD: rte_cxgbe_pmd: Coming up as MASTER: Initializing adapter
 530       Interactive-mode selected
 531       Configuring Port 0 (socket 0)
 532       Port 0: 00:07:43:2D:EA:C0
 533       Configuring Port 1 (socket 0)
 534       Port 1: 00:07:43:2D:EA:C8
 535       Checking link statuses...
 536       PMD: rte_cxgbe_pmd: Port0: passive DA port module inserted
 537       PMD: rte_cxgbe_pmd: Port1: passive DA port module inserted
 538       Port 0 Link Up - speed 10000 Mbps - full-duplex
 539       Port 1 Link Up - speed 10000 Mbps - full-duplex
 540       Done
 541       testpmd>
 542
 543 .. note::
 544
 545    Flow control pause TX/RX is disabled by default and can be enabled via
 546    testpmd as follows:
 547
 548    .. code-block:: console
 549
 550       testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 0
 551       testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 1
 552
 553    To disable again, use:
 554
 555    .. code-block:: console
 556
 557       testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 0
 558       testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 1