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