doc/guides/nics/ixgbe.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   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 Intel Corporation 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 IXGBE Driver
  32 ============
  33
  34 Vector PMD for IXGBE
  35 --------------------
  36
  37 Vector PMD uses Intel® SIMD instructions to optimize packet I/O.
  38 It improves load/store bandwidth efficiency of L1 data cache by using a wider SSE/AVX register 1 (1).
  39 The wider register gives space to hold multiple packet buffers so as to save instruction number when processing bulk of packets.
  40
  41 There is no change to PMD API. The RX/TX handler are the only two entries for vPMD packet I/O.
  42 They are transparently registered at runtime RX/TX execution if all condition checks pass.
  43
  44 1.  To date, only an SSE version of IX GBE vPMD is available.
  45     To ensure that vPMD is in the binary code, ensure that the option CONFIG_RTE_IXGBE_INC_VECTOR=y is in the configure file.
  46
  47 Some constraints apply as pre-conditions for specific optimizations on bulk packet transfers.
  48 The following sections explain RX and TX constraints in the vPMD.
  49
  50 RX Constraints
  51 ~~~~~~~~~~~~~~
  52
  53 Prerequisites and Pre-conditions
  54 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  55
  56 The following prerequisites apply:
  57
  58 *   To enable vPMD to work for RX, bulk allocation for Rx must be allowed.
  59
  60 *   The RTE_LIBRTE_IXGBE_RX_ALLOW_BULK_ALLOC=y configuration MACRO must be set before compiling the code.
  61
  62 Ensure that the following pre-conditions are satisfied:
  63
  64 *   rxq->rx_free_thresh >= RTE_PMD_IXGBE_RX_MAX_BURST
  65
  66 *   rxq->rx_free_thresh < rxq->nb_rx_desc
  67
  68 *   (rxq->nb_rx_desc % rxq->rx_free_thresh) == 0
  69
  70 *   rxq->nb_rx_desc  < (IXGBE_MAX_RING_DESC - RTE_PMD_IXGBE_RX_MAX_BURST)
  71
  72 These conditions are checked in the code.
  73
  74 Scattered packets are not supported in this mode.
  75 If an incoming packet is greater than the maximum acceptable length of one "mbuf" data size (by default, the size is 2 KB),
  76 vPMD for RX would be disabled.
  77
  78 By default, IXGBE_MAX_RING_DESC is set to 4096 and RTE_PMD_IXGBE_RX_MAX_BURST is set to 32.
  79
  80 Feature not Supported by RX Vector PMD
  81 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  82
  83 Some features are not supported when trying to increase the throughput in vPMD.
  84 They are:
  85
  86 *   IEEE1588
  87
  88 *   FDIR
  89
  90 *   Header split
  91
  92 *   RX checksum off load
  93
  94 Other features are supported using optional MACRO configuration. They include:
  95
  96 *   HW VLAN strip
  97
  98 *   HW extend dual VLAN
  99
 100 *   Enabled by RX_OLFLAGS (RTE_IXGBE_RX_OLFLAGS_DISABLE=n)
 101
 102
 103 To guarantee the constraint, configuration flags in dev_conf.rxmode will be checked:
 104
 105 *   hw_vlan_strip
 106
 107 *   hw_vlan_extend
 108
 109 *   hw_ip_checksum
 110
 111 *   header_split
 112
 113 *   dev_conf
 114
 115 fdir_conf->mode will also be checked.
 116
 117 RX Burst Size
 118 ^^^^^^^^^^^^^
 119
 120 As vPMD is focused on high throughput, it assumes that the RX burst size is equal to or greater than 32 per burst.
 121 It returns zero if using nb_pkt < 32 as the expected packet number in the receive handler.
 122
 123 TX Constraint
 124 ~~~~~~~~~~~~~
 125
 126 Prerequisite
 127 ^^^^^^^^^^^^
 128
 129 The only prerequisite is related to tx_rs_thresh.
 130 The tx_rs_thresh value must be greater than or equal to RTE_PMD_IXGBE_TX_MAX_BURST,
 131 but less or equal to RTE_IXGBE_TX_MAX_FREE_BUF_SZ.
 132 Consequently, by default the tx_rs_thresh value is in the range 32 to 64.
 133
 134 Feature not Supported by RX Vector PMD
 135 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 136
 137 TX vPMD only works when txq_flags is set to IXGBE_SIMPLE_FLAGS.
 138
 139 This means that it does not support TX multi-segment, VLAN offload and TX csum offload.
 140 The following MACROs are used for these three features:
 141
 142 *   ETH_TXQ_FLAGS_NOMULTSEGS
 143
 144 *   ETH_TXQ_FLAGS_NOVLANOFFL
 145
 146 *   ETH_TXQ_FLAGS_NOXSUMSCTP
 147
 148 *   ETH_TXQ_FLAGS_NOXSUMUDP
 149
 150 *   ETH_TXQ_FLAGS_NOXSUMTCP
 151
 152
 153 Sample Application Notes
 154 ~~~~~~~~~~~~~~~~~~~~~~~~
 155
 156 testpmd
 157 ^^^^^^^
 158
 159 By default, using CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=n:
 160
 161 .. code-block:: console
 162
 163     ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01
 164
 165 When CONFIG_RTE_IXGBE_RX_OLFLAGS_DISABLE=y, better performance can be achieved:
 166
 167 .. code-block:: console
 168
 169     ./x86_64-native-linuxapp-gcc/app/testpmd -c 300 -n 4 -- -i --burst=32 --rxfreet=32 --mbcache=250 --txpt=32 --rxht=8 --rxwt=0 --txfreet=32 --txrst=32 --txqflags=0xf01 --disable-hw-vlan
 170
 171 l3fwd
 172 ^^^^^
 173
 174 When running l3fwd with vPMD, there is one thing to note.
 175 In the configuration, ensure that port_conf.rxmode.hw_ip_checksum=0.
 176 Otherwise, by default, RX vPMD is disabled.
 177
 178 load_balancer
 179 ^^^^^^^^^^^^^
 180
 181 As in the case of l3fwd, set configure port_conf.rxmode.hw_ip_checksum=0 to enable vPMD.
 182 In addition, for improved performance, use -bsz "(32,32),(64,64),(32,32)" in load_balancer to avoid using the default burst size of 144.