doc/guides/nics/cxgbe.rst

   1 ..  BSD LICENSE
   2     Copyright 2015 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 T5** 10/40 Gbps family of adapters.
  36
  37 More information can be found at `Chelsio Communications
  38 <http://www.chelsio.com>`_.
  39
  40 Features
  41 --------
  42
  43 CXGBE PMD has the support for:
  44
  45 - Multiple queues for TX and RX.
  46 - Receiver Side Steering (RSS).
  47 - VLAN filtering.
  48 - Checksum offload.
  49 - Promiscuous mode.
  50 - All multicast mode.
  51 - Port hardware statistics.
  52
  53 Limitations
  54 -----------
  55
  56 The Chelsio T5 devices provide two/four ports but expose a single PCI bus
  57 address, thus, librte_pmd_cxgbe registers itself as a
  58 PCI driver that allocates one Ethernet device per detected port.
  59
  60 For this reason, one cannot white/blacklist a single port without also
  61 white/blacklisting the others on the same device.
  62
  63 Configuration
  64 -------------
  65
  66 Compiling CXGBE PMD
  67 ~~~~~~~~~~~~~~~~~~~
  68
  69 These options can be modified in the ``.config`` file.
  70
  71 - ``CONFIG_RTE_LIBRTE_CXGBE_PMD`` (default **y**)
  72
  73   Toggle compilation of librte_pmd_cxgbe driver.
  74
  75 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG`` (default **n**)
  76
  77   Toggle debugging code. Enabling this option adds additional generic debugging
  78   messages at the cost of lower performance.
  79
  80 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_REG`` (default **n**)
  81
  82   Toggle debugging code. Enabling this option adds additional registers related
  83   run-time checks and debugging messages at the cost of lower performance.
  84
  85 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_MBOX`` (default **n**)
  86
  87   Toggle debugging code. Enabling this option adds additional firmware mailbox
  88   related run-time checks and debugging messages at the cost of lower
  89   performance.
  90
  91 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_TX`` (default **n**)
  92
  93   Toggle debugging code. Enabling this option adds additional transmission data
  94   path run-time checks and debugging messages at the cost of lower performance.
  95
  96 - ``CONFIG_RTE_LIBRTE_CXGBE_DEBUG_RX`` (default **n**)
  97
  98   Toggle debugging code. Enabling this option adds additional receiving data
  99   path run-time checks and debugging messages at the cost of lower performance.
 100
 101 Prerequisites
 102 -------------
 103
 104 - Requires firmware version **1.13.32.0** and higher. Visit
 105   `Chelsio Communications <http://www.chelsio.com>`_ to get latest firmware.
 106
 107 Sample Application Notes
 108 -------------------------
 109
 110 This section demonstrates how to launch **testpmd** with Chelsio T5
 111 devices managed by librte_pmd_cxgbe.
 112
 113 #. Load the kernel module:
 114
 115    .. code-block:: console
 116
 117       modprobe cxgb4
 118
 119 #. Get the PCI bus addresses of the interfaces bound to cxgb4 driver:
 120
 121    .. code-block:: console
 122
 123       dmesg | tail -2
 124
 125    Example output:
 126
 127    .. code-block:: console
 128
 129       cxgb4 0000:02:00.4 p1p1: renamed from eth0
 130       cxgb4 0000:02:00.4 p1p2: renamed from eth1
 131
 132    .. note::
 133
 134       Both the interfaces of a Chelsio T5 2-port adapter are bound to the
 135       same PCI bus address.
 136
 137 #. Unload the kernel module:
 138
 139    .. code-block:: console
 140
 141       modprobe -ar cxgb4 csiostor
 142
 143 #. Request huge pages:
 144
 145    .. code-block:: console
 146
 147       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
 148
 149 #. Load igb_uio or vfio-pci driver:
 150
 151    .. code-block:: console
 152
 153       insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
 154
 155    or
 156
 157    .. code-block:: console
 158
 159       modprobe vfio-pci
 160
 161 #. Bind the Chelsio T5 adapters to igb_uio or vfio-pci loaded in the previous
 162    step:
 163
 164    .. code-block:: console
 165
 166       ./tools/dpdk_nic_bind.py --bind igb_uio 0000:02:00.4
 167
 168    or
 169
 170    Setup VFIO permissions for regular users and then bind to vfio-pci:
 171
 172    .. code-block:: console
 173
 174       sudo chmod a+x /dev/vfio
 175
 176       sudo chmod 0666 /dev/vfio/*
 177
 178       ./tools/dpdk_nic_bind.py --bind vfio-pci 0000:02:00.4
 179
 180 #. Start testpmd with basic parameters:
 181
 182    .. code-block:: console
 183
 184       ./x86_64-native-linuxapp-gcc/app/testpmd -c 0xf -n 4 -w 0000:02:00.4 -- -i
 185
 186    Example output:
 187
 188    .. code-block:: console
 189
 190       [...]
 191       EAL: PCI device 0000:02:00.4 on NUMA socket -1
 192       EAL:   probe driver: 1425:5401 rte_cxgbe_pmd
 193       EAL:   PCI memory mapped at 0x7fd7c0200000
 194       EAL:   PCI memory mapped at 0x7fd77cdfd000
 195       EAL:   PCI memory mapped at 0x7fd7c10b7000
 196       PMD: rte_cxgbe_pmd: fw: 1.13.33.0, TP: 0.1.4.8
 197       PMD: rte_cxgbe_pmd: Coming up as MASTER: Initializing adapter
 198       Interactive-mode selected
 199       Configuring Port 0 (socket 0)
 200       Port 0: 00:07:43:2D:EA:C0
 201       Configuring Port 1 (socket 0)
 202       Port 1: 00:07:43:2D:EA:C8
 203       Checking link statuses...
 204       PMD: rte_cxgbe_pmd: Port0: passive DA port module inserted
 205       PMD: rte_cxgbe_pmd: Port1: passive DA port module inserted
 206       Port 0 Link Up - speed 10000 Mbps - full-duplex
 207       Port 1 Link Up - speed 10000 Mbps - full-duplex
 208       Done
 209       testpmd>