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