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