doc/guides/nics/cxgbe.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright(c) 2014-2018 Chelsio Communications.
   3    All rights reserved.
   4
   5 CXGBE Poll Mode Driver
   6 ======================
   7
   8 The CXGBE PMD (**librte_pmd_cxgbe**) provides poll mode driver support
   9 for **Chelsio Terminator** 10/25/40/100 Gbps family of adapters. CXGBE PMD
  10 has support for the latest Linux and FreeBSD operating systems.
  11
  12 CXGBEVF PMD provides poll mode driver support for SR-IOV Virtual functions
  13 and has support for the latest Linux operating systems.
  14
  15 More information can be found at `Chelsio Communications Official Website
  16 <http://www.chelsio.com>`_.
  17
  18 Features
  19 --------
  20
  21 CXGBE and CXGBEVF PMD has support for:
  22
  23 - Multiple queues for TX and RX
  24 - Receiver Side Steering (RSS)
  25   Receiver Side Steering (RSS) on IPv4, IPv6, IPv4-TCP/UDP, IPv6-TCP/UDP.
  26   For 4-tuple, enabling 'RSS on TCP' and 'RSS on TCP + UDP' is supported.
  27 - VLAN filtering
  28 - Checksum offload
  29 - Promiscuous mode
  30 - All multicast mode
  31 - Port hardware statistics
  32 - Jumbo frames
  33
  34 Limitations
  35 -----------
  36
  37 The Chelsio Terminator series of devices provide two/four ports but
  38 expose a single PCI bus address, thus, librte_pmd_cxgbe registers
  39 itself as a PCI driver that allocates one Ethernet device per detected
  40 port.
  41
  42 For this reason, one cannot whitelist/blacklist a single port without
  43 whitelisting/blacklisting the other ports on the same device.
  44
  45 .. _t5-nics:
  46
  47 Supported Chelsio T5 NICs
  48 -------------------------
  49
  50 - 1G NICs: T502-BT
  51 - 10G NICs: T520-BT, T520-CR, T520-LL-CR, T520-SO-CR, T540-CR
  52 - 40G NICs: T580-CR, T580-LP-CR, T580-SO-CR
  53 - Other T5 NICs: T522-CR
  54
  55 .. _t6-nics:
  56
  57 Supported Chelsio T6 NICs
  58 -------------------------
  59
  60 - 25G NICs: T6425-CR, T6225-CR, T6225-LL-CR, T6225-SO-CR
  61 - 100G NICs: T62100-CR, T62100-LP-CR, T62100-SO-CR
  62
  63 Supported SR-IOV Chelsio NICs
  64 -----------------------------
  65
  66 SR-IOV virtual functions are supported on all the Chelsio NICs listed
  67 in :ref:`t5-nics` and :ref:`t6-nics`.
  68
  69 Prerequisites
  70 -------------
  71
  72 - Requires firmware version **1.17.14.0** and higher. Visit
  73   `Chelsio Download Center <http://service.chelsio.com>`_ to get latest firmware
  74   bundled with the latest Chelsio Unified Wire package.
  75
  76   For Linux, installing and loading the latest cxgb4 kernel driver from the
  77   Chelsio Unified Wire package should get you the latest firmware. More
  78   information can be obtained from the User Guide that is bundled with the
  79   Chelsio Unified Wire package.
  80
  81   For FreeBSD, the latest firmware obtained from the Chelsio Unified Wire
  82   package must be manually flashed via cxgbetool available in FreeBSD source
  83   repository.
  84
  85   Instructions on how to manually flash the firmware are given in section
  86   :ref:`linux-installation` for Linux and section :ref:`freebsd-installation`
  87   for FreeBSD.
  88
  89 Pre-Installation Configuration
  90 ------------------------------
  91
  92 Config File Options
  93 ~~~~~~~~~~~~~~~~~~~
  94
  95 The following options can be modified in the ``.config`` file. Please note that
  96 enabling debugging options may affect system performance.
  97
  98 - ``CONFIG_RTE_LIBRTE_CXGBE_PMD`` (default **y**)
  99
 100   Toggle compilation of librte_pmd_cxgbe driver.
 101
 102   .. note::
 103
 104      This controls compilation of both CXGBE and CXGBEVF PMD.
 105
 106 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG`` (default **n**)
 107
 108   Toggle display of generic debugging messages.
 109
 110 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_REG`` (default **n**)
 111
 112   Toggle display of registers related run-time check messages.
 113
 114 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_MBOX`` (default **n**)
 115
 116   Toggle display of firmware mailbox related run-time check messages.
 117
 118 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_TX`` (default **n**)
 119
 120   Toggle display of transmission data path run-time check messages.
 121
 122 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_RX`` (default **n**)
 123
 124   Toggle display of receiving data path run-time check messages.
 125
 126 - ``CONFIG_RTE_LIBRTE_CXGBE_TPUT`` (default **y**)
 127
 128   Toggle behaviour to prefer Throughput or Latency.
 129
 130 .. _driver-compilation:
 131
 132 Driver compilation and testing
 133 ------------------------------
 134
 135 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 136 for details.
 137
 138 Linux
 139 -----
 140
 141 .. _linux-installation:
 142
 143 Linux Installation
 144 ~~~~~~~~~~~~~~~~~~
 145
 146 Steps to manually install the latest firmware from the downloaded Chelsio
 147 Unified Wire package for Linux operating system are as follows:
 148
 149 #. Load the kernel module:
 150
 151    .. code-block:: console
 152
 153       modprobe cxgb4
 154
 155 #. Use ifconfig to get the interface name assigned to Chelsio card:
 156
 157    .. code-block:: console
 158
 159       ifconfig -a | grep "00:07:43"
 160
 161    Example output:
 162
 163    .. code-block:: console
 164
 165       p1p1      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C0
 166       p1p2      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C8
 167
 168 #. Install cxgbtool:
 169
 170    .. code-block:: console
 171
 172       cd <path_to_uwire>/tools/cxgbtool
 173       make install
 174
 175 #. Use cxgbtool to load the firmware config file onto the card:
 176
 177    .. code-block:: console
 178
 179       cxgbtool p1p1 loadcfg <path_to_uwire>/src/network/firmware/t5-config.txt
 180
 181 #. Use cxgbtool to load the firmware image onto the card:
 182
 183    .. code-block:: console
 184
 185       cxgbtool p1p1 loadfw <path_to_uwire>/src/network/firmware/t5fw-*.bin
 186
 187 #. Unload and reload the kernel module:
 188
 189    .. code-block:: console
 190
 191       modprobe -r cxgb4
 192       modprobe cxgb4
 193
 194 #. Verify with ethtool:
 195
 196    .. code-block:: console
 197
 198       ethtool -i p1p1 | grep "firmware"
 199
 200    Example output:
 201
 202    .. code-block:: console
 203
 204       firmware-version: 1.17.14.0, TP 0.1.4.9
 205
 206 Running testpmd
 207 ~~~~~~~~~~~~~~~
 208
 209 This section demonstrates how to launch **testpmd** with Chelsio
 210 devices managed by librte_pmd_cxgbe in Linux operating system.
 211
 212 #. Load the kernel module:
 213
 214    .. code-block:: console
 215
 216       modprobe cxgb4
 217
 218 #. Get the PCI bus addresses of the interfaces bound to cxgb4 driver:
 219
 220    .. code-block:: console
 221
 222       dmesg | tail -2
 223
 224    Example output:
 225
 226    .. code-block:: console
 227
 228       cxgb4 0000:02:00.4 p1p1: renamed from eth0
 229       cxgb4 0000:02:00.4 p1p2: renamed from eth1
 230
 231    .. note::
 232
 233       Both the interfaces of a Chelsio 2-port adapter are bound to the
 234       same PCI bus address.
 235
 236 #. Unload the kernel module:
 237
 238    .. code-block:: console
 239
 240       modprobe -ar cxgb4 csiostor
 241
 242 #. Running testpmd
 243
 244    Follow instructions available in the document
 245    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 246    to run testpmd.
 247
 248    .. note::
 249
 250       Currently, CXGBE PMD only supports the binding of PF4 for Chelsio NICs.
 251
 252    Example output:
 253
 254    .. code-block:: console
 255
 256       [...]
 257       EAL: PCI device 0000:02:00.4 on NUMA socket -1
 258       EAL:   probe driver: 1425:5401 rte_cxgbe_pmd
 259       EAL:   PCI memory mapped at 0x7fd7c0200000
 260       EAL:   PCI memory mapped at 0x7fd77cdfd000
 261       EAL:   PCI memory mapped at 0x7fd7c10b7000
 262       PMD: rte_cxgbe_pmd: fw: 1.17.14.0, TP: 0.1.4.9
 263       PMD: rte_cxgbe_pmd: Coming up as MASTER: Initializing adapter
 264       Interactive-mode selected
 265       Configuring Port 0 (socket 0)
 266       Port 0: 00:07:43:2D:EA:C0
 267       Configuring Port 1 (socket 0)
 268       Port 1: 00:07:43:2D:EA:C8
 269       Checking link statuses...
 270       PMD: rte_cxgbe_pmd: Port0: passive DA port module inserted
 271       PMD: rte_cxgbe_pmd: Port1: passive DA port module inserted
 272       Port 0 Link Up - speed 10000 Mbps - full-duplex
 273       Port 1 Link Up - speed 10000 Mbps - full-duplex
 274       Done
 275       testpmd>
 276
 277    .. note::
 278
 279       Flow control pause TX/RX is disabled by default and can be enabled via
 280       testpmd. Refer section :ref:`flow-control` for more details.
 281
 282 Configuring SR-IOV Virtual Functions
 283 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 284
 285 This section demonstrates how to enable SR-IOV virtual functions
 286 on Chelsio NICs and demonstrates how to run testpmd with SR-IOV
 287 virtual functions.
 288
 289 #. Load the kernel module:
 290
 291    .. code-block:: console
 292
 293       modprobe cxgb4
 294
 295 #. Get the PCI bus addresses of the interfaces bound to cxgb4 driver:
 296
 297    .. code-block:: console
 298
 299       dmesg | tail -2
 300
 301    Example output:
 302
 303    .. code-block:: console
 304
 305       cxgb4 0000:02:00.4 p1p1: renamed from eth0
 306       cxgb4 0000:02:00.4 p1p2: renamed from eth1
 307
 308    .. note::
 309
 310       Both the interfaces of a Chelsio 2-port adapter are bound to the
 311       same PCI bus address.
 312
 313 #. Use ifconfig to get the interface name assigned to Chelsio card:
 314
 315    .. code-block:: console
 316
 317       ifconfig -a | grep "00:07:43"
 318
 319    Example output:
 320
 321    .. code-block:: console
 322
 323       p1p1      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C0
 324       p1p2      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C8
 325
 326 #. Bring up the interfaces:
 327
 328    .. code-block:: console
 329
 330       ifconfig p1p1 up
 331       ifconfig p1p2 up
 332
 333 #. Instantiate SR-IOV Virtual Functions. PF0..3 can be used for
 334    SR-IOV VFs. Multiple VFs can be instantiated on each of PF0..3.
 335    To instantiate one SR-IOV VF on each PF0 and PF1:
 336
 337    .. code-block:: console
 338
 339       echo 1 > /sys/bus/pci/devices/0000\:02\:00.0/sriov_numvfs
 340       echo 1 > /sys/bus/pci/devices/0000\:02\:00.1/sriov_numvfs
 341
 342 #. Get the PCI bus addresses of the virtual functions:
 343
 344    .. code-block:: console
 345
 346       lspci | grep -i "Chelsio" | grep -i "VF"
 347
 348    Example output:
 349
 350    .. code-block:: console
 351
 352       02:01.0 Ethernet controller: Chelsio Communications Inc T540-CR Unified Wire Ethernet Controller [VF]
 353       02:01.1 Ethernet controller: Chelsio Communications Inc T540-CR Unified Wire Ethernet Controller [VF]
 354
 355 #. Running testpmd
 356
 357    Follow instructions available in the document
 358    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 359    to bind virtual functions and run testpmd.
 360
 361    Example output:
 362
 363    .. code-block:: console
 364
 365       [...]
 366       EAL: PCI device 0000:02:01.0 on NUMA socket 0
 367       EAL:   probe driver: 1425:5803 net_cxgbevf
 368       PMD: rte_cxgbe_pmd: Firmware version: 1.17.14.0
 369       PMD: rte_cxgbe_pmd: TP Microcode version: 0.1.4.9
 370       PMD: rte_cxgbe_pmd: Chelsio rev 0
 371       PMD: rte_cxgbe_pmd: No bootstrap loaded
 372       PMD: rte_cxgbe_pmd: No Expansion ROM loaded
 373       PMD: rte_cxgbe_pmd:  0000:02:01.0 Chelsio rev 0 1G/10GBASE-SFP
 374       EAL: PCI device 0000:02:01.1 on NUMA socket 0
 375       EAL:   probe driver: 1425:5803 net_cxgbevf
 376       PMD: rte_cxgbe_pmd: Firmware version: 1.17.14.0
 377       PMD: rte_cxgbe_pmd: TP Microcode version: 0.1.4.9
 378       PMD: rte_cxgbe_pmd: Chelsio rev 0
 379       PMD: rte_cxgbe_pmd: No bootstrap loaded
 380       PMD: rte_cxgbe_pmd: No Expansion ROM loaded
 381       PMD: rte_cxgbe_pmd:  0000:02:01.1 Chelsio rev 0 1G/10GBASE-SFP
 382       Configuring Port 0 (socket 0)
 383       Port 0: 06:44:29:44:40:00
 384       Configuring Port 1 (socket 0)
 385       Port 1: 06:44:29:44:40:10
 386       Checking link statuses...
 387       Done
 388       testpmd>
 389
 390 FreeBSD
 391 -------
 392
 393 .. _freebsd-installation:
 394
 395 FreeBSD Installation
 396 ~~~~~~~~~~~~~~~~~~~~
 397
 398 Steps to manually install the latest firmware from the downloaded Chelsio
 399 Unified Wire package for FreeBSD operating system are as follows:
 400
 401 #. Load the kernel module:
 402
 403    .. code-block:: console
 404
 405       kldload if_cxgbe
 406
 407 #. Use dmesg to get the t5nex instance assigned to the Chelsio card:
 408
 409    .. code-block:: console
 410
 411       dmesg | grep "t5nex"
 412
 413    Example output:
 414
 415    .. code-block:: console
 416
 417       t5nex0: <Chelsio T520-CR> irq 16 at device 0.4 on pci2
 418       cxl0: <port 0> on t5nex0
 419       cxl1: <port 1> on t5nex0
 420       t5nex0: PCIe x8, 2 ports, 14 MSI-X interrupts, 31 eq, 13 iq
 421
 422    In the example above, a Chelsio T520-CR card is bound to a t5nex0 instance.
 423
 424 #. Install cxgbetool from FreeBSD source repository:
 425
 426    .. code-block:: console
 427
 428       cd <path_to_FreeBSD_source>/tools/tools/cxgbetool/
 429       make && make install
 430
 431 #. Use cxgbetool to load the firmware image onto the card:
 432
 433    .. code-block:: console
 434
 435       cxgbetool t5nex0 loadfw <path_to_uwire>/src/network/firmware/t5fw-*.bin
 436
 437 #. Unload and reload the kernel module:
 438
 439    .. code-block:: console
 440
 441       kldunload if_cxgbe
 442       kldload if_cxgbe
 443
 444 #. Verify with sysctl:
 445
 446    .. code-block:: console
 447
 448       sysctl -a | grep "t5nex" | grep "firmware"
 449
 450    Example output:
 451
 452    .. code-block:: console
 453
 454       dev.t5nex.0.firmware_version: 1.17.14.0
 455
 456 Running testpmd
 457 ~~~~~~~~~~~~~~~
 458
 459 This section demonstrates how to launch **testpmd** with Chelsio
 460 devices managed by librte_pmd_cxgbe in FreeBSD operating system.
 461
 462 #. Change to DPDK source directory where the target has been compiled in
 463    section :ref:`driver-compilation`:
 464
 465    .. code-block:: console
 466
 467       cd <DPDK-source-directory>
 468
 469 #. Copy the contigmem kernel module to /boot/kernel directory:
 470
 471    .. code-block:: console
 472
 473       cp x86_64-native-bsdapp-clang/kmod/contigmem.ko /boot/kernel/
 474
 475 #. Add the following lines to /boot/loader.conf:
 476
 477    .. code-block:: console
 478
 479       # reserve 2 x 1G blocks of contiguous memory using contigmem driver
 480       hw.contigmem.num_buffers=2
 481       hw.contigmem.buffer_size=1073741824
 482       # load contigmem module during boot process
 483       contigmem_load="YES"
 484
 485    The above lines load the contigmem kernel module during boot process and
 486    allocate 2 x 1G blocks of contiguous memory to be used for DPDK later on.
 487    This is to avoid issues with potential memory fragmentation during later
 488    system up time, which may result in failure of allocating the contiguous
 489    memory required for the contigmem kernel module.
 490
 491 #. Restart the system and ensure the contigmem module is loaded successfully:
 492
 493    .. code-block:: console
 494
 495       reboot
 496       kldstat | grep "contigmem"
 497
 498    Example output:
 499
 500    .. code-block:: console
 501
 502       2    1 0xffffffff817f1000 3118     contigmem.ko
 503
 504 #. Repeat step 1 to ensure that you are in the DPDK source directory.
 505
 506 #. Load the cxgbe kernel module:
 507
 508    .. code-block:: console
 509
 510       kldload if_cxgbe
 511
 512 #. Get the PCI bus addresses of the interfaces bound to t5nex driver:
 513
 514    .. code-block:: console
 515
 516       pciconf -l | grep "t5nex"
 517
 518    Example output:
 519
 520    .. code-block:: console
 521
 522       t5nex0@pci0:2:0:4: class=0x020000 card=0x00001425 chip=0x54011425 rev=0x00
 523
 524    In the above example, the t5nex0 is bound to 2:0:4 bus address.
 525
 526    .. note::
 527
 528       Both the interfaces of a Chelsio 2-port adapter are bound to the
 529       same PCI bus address.
 530
 531 #. Unload the kernel module:
 532
 533    .. code-block:: console
 534
 535       kldunload if_cxgbe
 536
 537 #. Set the PCI bus addresses to hw.nic_uio.bdfs kernel environment parameter:
 538
 539    .. code-block:: console
 540
 541       kenv hw.nic_uio.bdfs="2:0:4"
 542
 543    This automatically binds 2:0:4 to nic_uio kernel driver when it is loaded in
 544    the next step.
 545
 546    .. note::
 547
 548       Currently, CXGBE PMD only supports the binding of PF4 for Chelsio NICs.
 549
 550 #. Load nic_uio kernel driver:
 551
 552    .. code-block:: console
 553
 554       kldload ./x86_64-native-bsdapp-clang/kmod/nic_uio.ko
 555
 556 #. Start testpmd with basic parameters:
 557
 558    .. code-block:: console
 559
 560       ./x86_64-native-bsdapp-clang/app/testpmd -l 0-3 -n 4 -w 0000:02:00.4 -- -i
 561
 562    Example output:
 563
 564    .. code-block:: console
 565
 566       [...]
 567       EAL: PCI device 0000:02:00.4 on NUMA socket 0
 568       EAL:   probe driver: 1425:5401 rte_cxgbe_pmd
 569       EAL:   PCI memory mapped at 0x8007ec000
 570       EAL:   PCI memory mapped at 0x842800000
 571       EAL:   PCI memory mapped at 0x80086c000
 572       PMD: rte_cxgbe_pmd: fw: 1.17.14.0, TP: 0.1.4.9
 573       PMD: rte_cxgbe_pmd: Coming up as MASTER: Initializing adapter
 574       Interactive-mode selected
 575       Configuring Port 0 (socket 0)
 576       Port 0: 00:07:43:2D:EA:C0
 577       Configuring Port 1 (socket 0)
 578       Port 1: 00:07:43:2D:EA:C8
 579       Checking link statuses...
 580       PMD: rte_cxgbe_pmd: Port0: passive DA port module inserted
 581       PMD: rte_cxgbe_pmd: Port1: passive DA port module inserted
 582       Port 0 Link Up - speed 10000 Mbps - full-duplex
 583       Port 1 Link Up - speed 10000 Mbps - full-duplex
 584       Done
 585       testpmd>
 586
 587 .. note::
 588
 589    Flow control pause TX/RX is disabled by default and can be enabled via
 590    testpmd. Refer section :ref:`flow-control` for more details.
 591
 592 Sample Application Notes
 593 ------------------------
 594
 595 .. _flow-control:
 596
 597 Enable/Disable Flow Control
 598 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 599
 600 Flow control pause TX/RX is disabled by default and can be enabled via
 601 testpmd as follows:
 602
 603 .. code-block:: console
 604
 605    testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 0
 606    testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 1
 607
 608 To disable again, run:
 609
 610 .. code-block:: console
 611
 612    testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 0
 613    testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 1
 614
 615 Jumbo Mode
 616 ~~~~~~~~~~
 617
 618 There are two ways to enable sending and receiving of jumbo frames via testpmd.
 619 One method involves using the **mtu** command, which changes the mtu of an
 620 individual port without having to stop the selected port. Another method
 621 involves stopping all the ports first and then running **max-pkt-len** command
 622 to configure the mtu of all the ports with a single command.
 623
 624 - To configure each port individually, run the mtu command as follows:
 625
 626   .. code-block:: console
 627
 628      testpmd> port config mtu 0 9000
 629      testpmd> port config mtu 1 9000
 630
 631 - To configure all the ports at once, stop all the ports first and run the
 632   max-pkt-len command as follows:
 633
 634   .. code-block:: console
 635
 636      testpmd> port stop all
 637      testpmd> port config all max-pkt-len 9000