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