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