doc/guides/nics/cxgbe.rst

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