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 Running testpmd
 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 #. Mount huge pages:
 264
 265    .. code-block:: console
 266
 267       mkdir /mnt/huge
 268       mount -t hugetlbfs nodev /mnt/huge
 269
 270 #. Load igb_uio or vfio-pci driver:
 271
 272    .. code-block:: console
 273
 274       insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
 275
 276    or
 277
 278    .. code-block:: console
 279
 280       modprobe vfio-pci
 281
 282 #. Bind the Chelsio T5 adapters to igb_uio or vfio-pci loaded in the previous
 283    step:
 284
 285    .. code-block:: console
 286
 287       ./tools/dpdk_nic_bind.py --bind igb_uio 0000:02:00.4
 288
 289    or
 290
 291    Setup VFIO permissions for regular users and then bind to vfio-pci:
 292
 293    .. code-block:: console
 294
 295       sudo chmod a+x /dev/vfio
 296
 297       sudo chmod 0666 /dev/vfio/*
 298
 299       ./tools/dpdk_nic_bind.py --bind vfio-pci 0000:02:00.4
 300
 301    .. note::
 302
 303       Currently, CXGBE PMD only supports the binding of PF4 for Chelsio T5 NICs.
 304
 305 #. Start testpmd with basic parameters:
 306
 307    .. code-block:: console
 308
 309       ./x86_64-native-linuxapp-gcc/app/testpmd -c 0xf -n 4 -w 0000:02:00.4 -- -i
 310
 311    Example output:
 312
 313    .. code-block:: console
 314
 315       [...]
 316       EAL: PCI device 0000:02:00.4 on NUMA socket -1
 317       EAL:   probe driver: 1425:5401 rte_cxgbe_pmd
 318       EAL:   PCI memory mapped at 0x7fd7c0200000
 319       EAL:   PCI memory mapped at 0x7fd77cdfd000
 320       EAL:   PCI memory mapped at 0x7fd7c10b7000
 321       PMD: rte_cxgbe_pmd: fw: 1.13.32.0, TP: 0.1.4.8
 322       PMD: rte_cxgbe_pmd: Coming up as MASTER: Initializing adapter
 323       Interactive-mode selected
 324       Configuring Port 0 (socket 0)
 325       Port 0: 00:07:43:2D:EA:C0
 326       Configuring Port 1 (socket 0)
 327       Port 1: 00:07:43:2D:EA:C8
 328       Checking link statuses...
 329       PMD: rte_cxgbe_pmd: Port0: passive DA port module inserted
 330       PMD: rte_cxgbe_pmd: Port1: passive DA port module inserted
 331       Port 0 Link Up - speed 10000 Mbps - full-duplex
 332       Port 1 Link Up - speed 10000 Mbps - full-duplex
 333       Done
 334       testpmd>
 335
 336 .. note::
 337
 338    Flow control pause TX/RX is disabled by default and can be enabled via
 339    testpmd. Refer section :ref:`flow-control` for more details.
 340
 341 FreeBSD
 342 -------
 343
 344 .. _freebsd-installation:
 345
 346 FreeBSD Installation
 347 ~~~~~~~~~~~~~~~~~~~~
 348
 349 Steps to manually install the latest firmware from the downloaded Chelsio
 350 Unified Wire package for FreeBSD operating system are as follows:
 351
 352 #. Load the kernel module:
 353
 354    .. code-block:: console
 355
 356       kldload if_cxgbe
 357
 358 #. Use dmesg to get the t5nex instance assigned to the Chelsio card:
 359
 360    .. code-block:: console
 361
 362       dmesg | grep "t5nex"
 363
 364    Example output:
 365
 366    .. code-block:: console
 367
 368       t5nex0: <Chelsio T520-CR> irq 16 at device 0.4 on pci2
 369       cxl0: <port 0> on t5nex0
 370       cxl1: <port 1> on t5nex0
 371       t5nex0: PCIe x8, 2 ports, 14 MSI-X interrupts, 31 eq, 13 iq
 372
 373    In the example above, a Chelsio T520-CR card is bound to a t5nex0 instance.
 374
 375 #. Install cxgbetool from FreeBSD source repository:
 376
 377    .. code-block:: console
 378
 379       cd <path_to_FreeBSD_source>/tools/tools/cxgbetool/
 380       make && make install
 381
 382 #. Use cxgbetool to load the firmware image onto the card:
 383
 384    .. code-block:: console
 385
 386       cxgbetool t5nex0 loadfw <path_to_uwire>/src/network/firmware/t5fw-*.bin
 387
 388 #. Unload and reload the kernel module:
 389
 390    .. code-block:: console
 391
 392       kldunload if_cxgbe
 393       kldload if_cxgbe
 394
 395 #. Verify with sysctl:
 396
 397    .. code-block:: console
 398
 399       sysctl -a | grep "t5nex" | grep "firmware"
 400
 401    Example output:
 402
 403    .. code-block:: console
 404
 405       dev.t5nex.0.firmware_version: 1.13.32.0
 406
 407 Running testpmd
 408 ~~~~~~~~~~~~~~~
 409
 410 This section demonstrates how to launch **testpmd** with Chelsio T5
 411 devices managed by librte_pmd_cxgbe in FreeBSD operating system.
 412
 413 #. Change to DPDK source directory where the target has been compiled in
 414    section :ref:`driver-compilation`:
 415
 416    .. code-block:: console
 417
 418       cd <DPDK-source-directory>
 419
 420 #. Copy the contigmem kernel module to /boot/kernel directory:
 421
 422    .. code-block:: console
 423
 424       cp x86_64-native-bsdapp-clang/kmod/contigmem.ko /boot/kernel/
 425
 426 #. Add the following lines to /boot/loader.conf:
 427
 428    .. code-block:: console
 429
 430       # reserve 2 x 1G blocks of contiguous memory using contigmem driver
 431       hw.contigmem.num_buffers=2
 432       hw.contigmem.buffer_size=1073741824
 433       # load contigmem module during boot process
 434       contigmem_load="YES"
 435
 436    The above lines load the contigmem kernel module during boot process and
 437    allocate 2 x 1G blocks of contiguous memory to be used for DPDK later on.
 438    This is to avoid issues with potential memory fragmentation during later
 439    system up time, which may result in failure of allocating the contiguous
 440    memory required for the contigmem kernel module.
 441
 442 #. Restart the system and ensure the contigmem module is loaded successfully:
 443
 444    .. code-block:: console
 445
 446       reboot
 447       kldstat | grep "contigmem"
 448
 449    Example output:
 450
 451    .. code-block:: console
 452
 453       2    1 0xffffffff817f1000 3118     contigmem.ko
 454
 455 #. Repeat step 1 to ensure that you are in the DPDK source directory.
 456
 457 #. Load the cxgbe kernel module:
 458
 459    .. code-block:: console
 460
 461       kldload if_cxgbe
 462
 463 #. Get the PCI bus addresses of the interfaces bound to t5nex driver:
 464
 465    .. code-block:: console
 466
 467       pciconf -l | grep "t5nex"
 468
 469    Example output:
 470
 471    .. code-block:: console
 472
 473       t5nex0@pci0:2:0:4: class=0x020000 card=0x00001425 chip=0x54011425 rev=0x00
 474
 475    In the above example, the t5nex0 is bound to 2:0:4 bus address.
 476
 477    .. note::
 478
 479       Both the interfaces of a Chelsio T5 2-port adapter are bound to the
 480       same PCI bus address.
 481
 482 #. Unload the kernel module:
 483
 484    .. code-block:: console
 485
 486       kldunload if_cxgbe
 487
 488 #. Set the PCI bus addresses to hw.nic_uio.bdfs kernel environment parameter:
 489
 490    .. code-block:: console
 491
 492       kenv hw.nic_uio.bdfs="2:0:4"
 493
 494    This automatically binds 2:0:4 to nic_uio kernel driver when it is loaded in
 495    the next step.
 496
 497    .. note::
 498
 499       Currently, CXGBE PMD only supports the binding of PF4 for Chelsio T5 NICs.
 500
 501 #. Load nic_uio kernel driver:
 502
 503    .. code-block:: console
 504
 505       kldload ./x86_64-native-bsdapp-clang/kmod/nic_uio.ko
 506
 507 #. Start testpmd with basic parameters:
 508
 509    .. code-block:: console
 510
 511       ./x86_64-native-bsdapp-clang/app/testpmd -c 0xf -n 4 -w 0000:02:00.4 -- -i
 512
 513    Example output:
 514
 515    .. code-block:: console
 516
 517       [...]
 518       EAL: PCI device 0000:02:00.4 on NUMA socket 0
 519       EAL:   probe driver: 1425:5401 rte_cxgbe_pmd
 520       EAL:   PCI memory mapped at 0x8007ec000
 521       EAL:   PCI memory mapped at 0x842800000
 522       EAL:   PCI memory mapped at 0x80086c000
 523       PMD: rte_cxgbe_pmd: fw: 1.13.32.0, TP: 0.1.4.8
 524       PMD: rte_cxgbe_pmd: Coming up as MASTER: Initializing adapter
 525       Interactive-mode selected
 526       Configuring Port 0 (socket 0)
 527       Port 0: 00:07:43:2D:EA:C0
 528       Configuring Port 1 (socket 0)
 529       Port 1: 00:07:43:2D:EA:C8
 530       Checking link statuses...
 531       PMD: rte_cxgbe_pmd: Port0: passive DA port module inserted
 532       PMD: rte_cxgbe_pmd: Port1: passive DA port module inserted
 533       Port 0 Link Up - speed 10000 Mbps - full-duplex
 534       Port 1 Link Up - speed 10000 Mbps - full-duplex
 535       Done
 536       testpmd>
 537
 538 .. note::
 539
 540    Flow control pause TX/RX is disabled by default and can be enabled via
 541    testpmd. Refer section :ref:`flow-control` for more details.
 542
 543 Sample Application Notes
 544 ------------------------
 545
 546 .. _flow-control:
 547
 548 Enable/Disable Flow Control
 549 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 550
 551 Flow control pause TX/RX is disabled by default and can be enabled via
 552 testpmd as follows:
 553
 554 .. code-block:: console
 555
 556    testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 0
 557    testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 1
 558
 559 To disable again, run:
 560
 561 .. code-block:: console
 562
 563    testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 0
 564    testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 1