share/man/man4/ix.4

   1 .\" Copyright (c) 2001-2008, Intel Corporation
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions are met:
   6 .\"
   7 .\" 1. Redistributions of source code must retain the above copyright notice,
   8 .\"    this list of conditions and the following disclaimer.
   9 .\"
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" 3. Neither the name of the Intel Corporation nor the names of its
  15 .\"    contributors may be used to endorse or promote products derived from
  16 .\"    this software without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  19 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  22 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" * Other names and brands may be claimed as the property of others.
  31 .\"
  32 .\" $FreeBSD: src/share/man/man4/ixgbe.4,v 1.2 2008/06/17 21:14:02 brueffer Exp $
  33 .\"
  34 .Dd May 11, 2014
  35 .Dt IX 4
  36 .Os
  37 .Sh NAME
  38 .Nm ix
  39 .Nd "Intel(R) 10Gb Ethernet driver"
  40 .Sh SYNOPSIS
  41 To compile this driver into the kernel,
  42 place the following line in your
  43 kernel configuration file:
  44 .Bd -ragged -offset indent
  45 .Cd "device ix"
  46 .Ed
  47 .Pp
  48 Alternatively, to load the driver as a
  49 module at boot time, place the following line in
  50 .Xr loader.conf 5 :
  51 .Bd -literal -offset indent
  52 if_ix_load="YES"
  53 .Ed
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 driver provides support for PCI Express 10Gb Ethernet adapters based on
  58 the Intel
  59 82598,
  60 82599,
  61 and
  62 X540
  63 Ethernet controller chips.
  64 The
  65 .Nm
  66 driver supports:
  67 .Pp
  68 .Bl -item -offset indent -compact
  69 .It
  70 Transmit/Receive checksum offload for IP/UDP/TCP.
  71 .\"Jumbo Frames.
  72 .It
  73 Interrupt moderation
  74 .It
  75 TCP segmentation offload (TSO)
  76 .It
  77 Receive side scaling (RSS)
  78 .It
  79 Multiple tranmission queues
  80 .It
  81 Multiple vector MSI-X
  82 .It
  83 VLAN tag stripping and inserting
  84 .El
  85 .Pp
  86 If
  87 .Xr polling 4
  88 or MSI-X is used,
  89 by default,
  90 the
  91 .Nm
  92 driver will try enabling as many reception queues and transmission queues
  93 as are allowed by the number of CPUs in the system.
  94 .Pp
  95 If multiple transmission queues are used,
  96 the round-robin arbitration is performed among the transmission queues.
  97 And the round-robin arbitration between transmission queues is done at the
  98 TCP segment boundary after the hardware segmentation is performed.
  99 .Pp
 100 82598 supports 16 reception queues and 32 transmission queues.
 101 MSI-X is not enabled due to hardware errata.
 102 Under MSI or legacy interrupt mode,
 103 2 reception queues are enabled for hardware RSS hash
 104 and only 1 transmission queue is enable.
 105 .Pp
 106 82599 and X540 supports 16 reception queues and 64 transmission queues.
 107 MSI-X is enable by default.
 108 However,
 109 due to the number of MSI-X vectors is 64,
 110 at most 16 reception queues and 32 transmission queues will be enabled
 111 under MSI-X mode.
 112 .Pp
 113 For more information on configuring this device, see
 114 .Xr ifconfig 8 .
 115 The
 116 .Nm
 117 driver supports
 118 .Xr polling 4 .
 119 .Sh HARDWARE
 120 The
 121 .Nm
 122 driver supports Gigabit Ethernet adapters based on the Intel
 123 82598,
 124 82599,
 125 and
 126 X540
 127 controller chips:
 128 .Pp
 129 .Bl -bullet -compact
 130 .It
 131 Intel 10 Gigabit AF DA Dual Port Server Adapter
 132 .It
 133 Intel 10 Gigabit AT Server Adapter
 134 .It
 135 Intel 10 Gigabit AT2 Server Adapter
 136 .It
 137 Intel 10 Gigabit CX4 Dual Port Server Adapter
 138 .It
 139 Intel 10 Gigabit XF LR Server Adapter
 140 .It
 141 Intel 10 Gigabit XF SR Dual Port Server Adapter
 142 .It
 143 Intel 10 Gigabit XF SR Server Adapter
 144 .It
 145 Intel 82598 10 Gigabit Ethernet Controller
 146 .It
 147 Intel 82599 10 Gigabit Ethernet Controller
 148 .It
 149 Intel Ethernet Controller X540-AT2
 150 .It
 151 Intel Ethernet Converged Network Adapter X520 Series
 152 .It
 153 Intel Ethernet Converged Network Adapter X540-T1
 154 .It
 155 Intel Ethernet Converged Network Adapter X540-T2
 156 .It
 157 Intel Ethernet Server Adapter X520 Series
 158 .It
 159 Intel Ethernet Server Adapter X520-DA2
 160 .It
 161 Intel Ethernet Server Adapter X520-LR1
 162 .It
 163 Intel Ethernet Server Adapter X520-SR1
 164 .It
 165 Intel Ethernet Server Adapter X520-SR2
 166 .It
 167 Intel Ethernet Server Adapter X520-T2
 168 .El
 169 .Sh TUNABLES
 170 Tunables can be set at the
 171 .Xr loader 8
 172 prompt before booting the kernel or stored in
 173 .Xr loader.conf 5 .
 174 .Em X
 175 is the device unit number.
 176 .Bl -tag -width ".Va hw.ixX.unsupported_sfp"
 177 .It Va hw.ix.rxd Va hw.ixX.rxd
 178 Number of receive descriptors allocated by the driver.
 179 The default value is 2048.
 180 The minimum is 64,
 181 and the maximum is 4096.
 182 .It Va hw.ix.txd Va hw.ixX.txd
 183 Number of transmit descriptors allocated by the driver.
 184 The default value is 2048.
 185 The minimum is 64,
 186 and the maximum is 4096.
 187 .It Va hw.ix.rxr Va hw.ixX.rxr
 188 This tunable specifies the number of reception queues could be enabled.
 189 Maximum allowed value for these tunables is device specific
 190 and it must be power of 2 aligned.
 191 Setting these tunables to 0 allows the driver to make
 192 as many reception queues ready-for-use as allowed by the number of CPUs.
 193 .It Va hw.ix.txr Va hw.ixX.txr
 194 This tunable specifies the number of transmission queues could be enabled.
 195 Maximum allowed value for these tunables is device specific
 196 and it must be power of 2 aligned.
 197 Setting these tunables to 0 allows the driver to make
 198 as many transmission queues ready-for-use as allowed by the number of CPUs.
 199 .It Va hw.ix.msix.enable Va hw.ixX.msix.enable
 200 By default,
 201 the driver will use MSI-X if it is supported.
 202 This behaviour can be turned off by setting this tunable to 0.
 203 .It Va hw.ix.msix.agg_rxtx Va hw.ixX.msix.agg_rxtx
 204 If MSI-X is used,
 205 the driver aggregates transmission queue and reception queue processing
 206 by default.
 207 This behaviour could be turned off by setting this tunable to 0.
 208 If the number of MSI-X vectors is not enough to
 209 put transmission queue processing and reception queue processing
 210 onto independent MSI-X vector,
 211 then transmission queue and reception queue processing are always
 212 aggregated.
 213 .It Va hw.ixX.msix.off
 214 If MSI-X is used,
 215 and transmission queue and reception queue processing are aggregated,
 216 this tunable specifies the leading target CPU for
 217 transmission and reception queues processing.
 218 The value specificed must be aligned to the maximum of
 219 the number of reception queues
 220 and the number of transmission queues enabled,
 221 and must be less than the power of 2 number of CPUs.
 222 .It Va hw.ixX.msix.rxoff
 223 If MSI-X is used,
 224 and transmission queue and reception queue processing are not aggregated,
 225 this tunable specifies the leading target CPU for reception queues processing.
 226 The value specificed must be aligned to the number of reception queues enabled
 227 and must be less than the power of 2 number of CPUs.
 228 .It Va hw.ixX.msix.txoff
 229 If MSI-X is used,
 230 and transmission queue and reception queue processing are not aggregated,
 231 this tunable specifies the leading target CPU
 232 for transmission queues processing.
 233 The value specificed must be aligned to
 234 the number of transmission queues enabled
 235 and must be less than the power of 2 number of CPUs.
 236 .It Va hw.ix.msi.enable Va hw.ixX.msi.enable
 237 If MSI-X is disabled and MSI is supported,
 238 the driver will use MSI.
 239 This behavior can be turned off by setting this tunable to 0.
 240 .It Va hw.ixX.msi.cpu
 241 If MSI is used,
 242 it specifies the MSI's target CPU.
 243 .It Va hw.ixX.npoll.txoff
 244 This tunable specifies the leading target CPU for
 245 transmission queue
 246 .Xr polling 4
 247 processing.
 248 The value specificed must be aligned to the number of transmission queues
 249 enabled and must be less than the power of 2 number of CPUs.
 250 .It Va hw.ixX.npoll.rxoff
 251 This tunable specifies the leading target CPU for
 252 reception queue
 253 .Xr polling 4
 254 processing.
 255 The value specificed must be aligned to the number of reception queues
 256 enabled and must be less than the power of 2 number of CPUs.
 257 .It Va hw.ix.unsupported_sfp
 258 By default,
 259 this driver does not allow "unsupported" SFP modules.
 260 This behavior can be changed by setting this tunable to 1.
 261 .El
 262 .Sh MIB Variables
 263 A number of per-interface variables are implemented in the
 264 .Va hw.ix Ns Em X
 265 branch of the
 266 .Xr sysctl 3
 267 MIB.
 268 .Bl -tag -width "rxtx_intr_rate"
 269 .It Va rxr
 270 Number of reception queues could be enabled (read-only).
 271 Use the tunable
 272 .Va hw.ix.rxr
 273 or
 274 .Va hw.ixX.rxr
 275 to configure it.
 276 .It Va rxr_inuse
 277 Number of reception queues being used (read-only).
 278 .It Va txr
 279 Number of transmission queues could be enabled (read-only).
 280 Use the tunable
 281 .Va hw.ix.txr
 282 or
 283 .Va hw.ixX.txr
 284 to configure it.
 285 .It Va txr_inuse
 286 Number of transmission queues being used (read-only).
 287 .It Va rxd
 288 Number of descriptors per reception queue (read-only).
 289 Use the tunable
 290 .Va hw.ix.rxd
 291 or
 292 .Va hw.ixX.rxd
 293 to configure it.
 294 .It Va txd
 295 Number of descriptors per transmission queue (read-only).
 296 Use the tunable
 297 .Va hw.ix.txd
 298 or
 299 .Va hw.ixX.txd
 300 to configure it.
 301 .It Va rxtx_intr_rate
 302 If MSI or legacy interrupt is used,
 303 this sysctl controls the highest possible frequency
 304 that interrupt could be generated by the device.
 305 If MSI-X is used,
 306 this sysctl controls the highest possible frequency
 307 that interrupt could be generated by the MSI-X vectors,
 308 which aggregate transmission queue and reception queue procecssing.
 309 It is 8000 by default (125us).
 310 .It Va rx_intr_rate
 311 If MSI-X is used,
 312 this sysctl controls the highest possible frequency
 313 that interrupt could be generated by the MSI-X vectors,
 314 which only process reception queue.
 315 It is 8000 by default (125us).
 316 .It Va tx_intr_rate
 317 If MSI-X is used,
 318 this sysctl controls the highest possible frequency
 319 that interrupt could be generated by the MSI-X vectors,
 320 which only process transmission queue.
 321 It is 6000 by default (~150us).
 322 .It Va sts_intr_rate
 323 If MSI-X is used,
 324 this sysctl controls the highest possible frequency
 325 that interrupt could be generated by the MSI-X vectors,
 326 which only process chip status changes.
 327 It is 8000 by default (125us).
 328 .It Va tx_intr_nsegs
 329 Transmission interrupt is asked to be generated upon every
 330 .Va tx_intr_nsegs
 331 transmission descritors having been setup.
 332 The default value is 1/16 of the number of transmission descriptors per queue.
 333 .It Va tx_wreg_nsegs
 334 The number of transmission descriptors should be setup
 335 before the hardware register is written.
 336 Setting this value too high will have negative effect
 337 on transmission timeliness.
 338 Setting this value too low will hurt overall transmission performance
 339 due to the frequent hardware register writing.
 340 The default value is 8.
 341 .It Va rx_wreg_nsegs
 342 The number of reception descriptors should be setup
 343 before the hardware register is written.
 344 Setting this value too high will make device drop incoming packets.
 345 Setting this value too low will hurt overall reception performance
 346 due to the frequent hardware register writing.
 347 The default value is 32.
 348 .It Va npoll_rxoff
 349 See the tunable
 350 .Va hw.ixX.npoll.rxoff .
 351 The set value will take effect the next time
 352 .Xr polling 4
 353 is enabled on the device.
 354 .It Va npoll_txoff
 355 See the tunable
 356 .Va hw.ixX.npoll.txoff .
 357 The set value will take effect the next time
 358 .Xr polling 4
 359 is enabled on the device.
 360 .It Va flowctrl
 361 Flow control setting.
 362 Set it to 0 to turn off flow control.
 363 Set it to 1 to enable only the reception of pause frames.
 364 Set it to 2 to enable only the generation of pause frames.
 365 Set it to 3 to enable both the reception of pause frames
 366 and generation of pause frames,
 367 i.e. full flow control.
 368 .El
 369 .Sh SEE ALSO
 370 .Xr altq 4 ,
 371 .Xr arp 4 ,
 372 .Xr ifmedia 4 ,
 373 .Xr netintro 4 ,
 374 .Xr ng_ether 4 ,
 375 .Xr polling 4 ,
 376 .Xr vlan 4 ,
 377 .Xr ifconfig 8
 378 .Sh HISTORY
 379 The
 380 .Nm
 381 device driver first appeared in
 382 .Dx 3.1 .
 383 .Sh AUTHORS
 384 The
 385 .Nm
 386 driver was written by
 387 .An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com .