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