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 November 28, 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 if both TSO and multiple tranmission queues are used,
  98 the round-robin arbitration between transmission queues is done at the
  99 TCP segment boundary after the hardware segmentation is performed.
 100 .Pp
 101 82598 supports 16 reception queues and 32 transmission queues.
 102 MSI-X is not enabled due to hardware errata.
 103 Under MSI or legacy interrupt mode,
 104 2 reception queues are enabled for hardware RSS hash
 105 and only 1 transmission queue is enable.
 106 .Pp
 107 82599 and X540 supports 16 reception queues and 64 transmission queues.
 108 MSI-X is enable by default.
 109 However,
 110 due to the number of MSI-X vectors is 64,
 111 at most 16 reception queues and 32 transmission queues will be enabled
 112 under MSI-X mode.
 113 .Pp
 114 For more information on configuring this device, see
 115 .Xr ifconfig 8 .
 116 The
 117 .Nm
 118 driver supports
 119 .Xr polling 4 .
 120 .Sh HARDWARE
 121 The
 122 .Nm
 123 driver supports Gigabit Ethernet adapters based on the Intel
 124 82598,
 125 82599,
 126 and
 127 X540
 128 controller chips:
 129 .Pp
 130 .Bl -bullet -compact
 131 .It
 132 Intel 10 Gigabit AF DA Dual Port Server Adapter
 133 .It
 134 Intel 10 Gigabit AT Server Adapter
 135 .It
 136 Intel 10 Gigabit AT2 Server Adapter
 137 .It
 138 Intel 10 Gigabit CX4 Dual Port Server Adapter
 139 .It
 140 Intel 10 Gigabit XF LR Server Adapter
 141 .It
 142 Intel 10 Gigabit XF SR Dual Port Server Adapter
 143 .It
 144 Intel 10 Gigabit XF SR Server Adapter
 145 .It
 146 Intel 82598 10 Gigabit Ethernet Controller
 147 .It
 148 Intel 82599 10 Gigabit Ethernet Controller
 149 .It
 150 Intel Ethernet Controller X540-AT2
 151 .It
 152 Intel Ethernet Converged Network Adapter X520 Series
 153 .It
 154 Intel Ethernet Converged Network Adapter X540-T1
 155 .It
 156 Intel Ethernet Converged Network Adapter X540-T2
 157 .It
 158 Intel Ethernet Server Adapter X520 Series
 159 .It
 160 Intel Ethernet Server Adapter X520-DA2
 161 .It
 162 Intel Ethernet Server Adapter X520-LR1
 163 .It
 164 Intel Ethernet Server Adapter X520-SR1
 165 .It
 166 Intel Ethernet Server Adapter X520-SR2
 167 .It
 168 Intel Ethernet Server Adapter X520-T2
 169 .El
 170 .Sh TUNABLES
 171 Tunables can be set at the
 172 .Xr loader 8
 173 prompt before booting the kernel or stored in
 174 .Xr loader.conf 5 .
 175 .Em X
 176 is the device unit number.
 177 .Bl -tag -width ".Va hw.ixX.unsupported_sfp"
 178 .It Va hw.ix.rxd Va hw.ixX.rxd
 179 Number of receive descriptors allocated by the driver.
 180 The default value is 2048.
 181 The minimum is 64,
 182 and the maximum is 4096.
 183 .It Va hw.ix.txd Va hw.ixX.txd
 184 Number of transmit descriptors allocated by the driver.
 185 The default value is 2048.
 186 The minimum is 64,
 187 and the maximum is 4096.
 188 .It Va hw.ix.rxr Va hw.ixX.rxr
 189 This tunable specifies the number of reception queues could be enabled.
 190 Maximum allowed value for these tunables is device specific
 191 and it must be power of 2 aligned.
 192 Setting these tunables to 0 allows the driver to make
 193 as many reception queues ready-for-use as allowed by the number of CPUs.
 194 .It Va hw.ix.txr Va hw.ixX.txr
 195 This tunable specifies the number of transmission queues could be enabled.
 196 Maximum allowed value for these tunables is device specific
 197 and it must be power of 2 aligned.
 198 Setting these tunables to 0 allows the driver to make
 199 as many transmission queues ready-for-use as allowed by the number of CPUs.
 200 .It Va hw.ix.msix.enable Va hw.ixX.msix.enable
 201 By default,
 202 the driver will use MSI-X if it is supported.
 203 This behaviour can be turned off by setting this tunable to 0.
 204 .It Va hw.ix.msix.agg_rxtx Va hw.ixX.msix.agg_rxtx
 205 If MSI-X is used,
 206 the driver aggregates transmission queue and reception queue processing
 207 by default.
 208 This behaviour could be turned off by setting this tunable to 0.
 209 If the number of MSI-X vectors is not enough to
 210 put transmission queue processing and reception queue processing
 211 onto independent MSI-X vector,
 212 then transmission queue and reception queue processing are always
 213 aggregated.
 214 .It Va hw.ixX.msix.off
 215 If MSI-X is used,
 216 and transmission queue and reception queue processing are aggregated,
 217 this tunable specifies the leading target CPU for
 218 transmission and reception queues processing.
 219 The value specificed must be aligned to the maximum of
 220 the number of reception queues
 221 and the number of transmission queues enabled,
 222 and must be less than the power of 2 number of CPUs.
 223 .It Va hw.ixX.msix.rxoff
 224 If MSI-X is used,
 225 and transmission queue and reception queue processing are not aggregated,
 226 this tunable specifies the leading target CPU for reception queues processing.
 227 The value specificed must be aligned to the number of reception queues enabled
 228 and must be less than the power of 2 number of CPUs.
 229 .It Va hw.ixX.msix.txoff
 230 If MSI-X is used,
 231 and transmission queue and reception queue processing are not aggregated,
 232 this tunable specifies the leading target CPU
 233 for transmission queues processing.
 234 The value specificed must be aligned to
 235 the number of transmission queues enabled
 236 and must be less than the power of 2 number of CPUs.
 237 .It Va hw.ix.msi.enable Va hw.ixX.msi.enable
 238 If MSI-X is disabled and MSI is supported,
 239 the driver will use MSI.
 240 This behavior can be turned off by setting this tunable to 0.
 241 .It Va hw.ixX.msi.cpu
 242 If MSI is used,
 243 it specifies the MSI's target CPU.
 244 .It Va hw.ixX.npoll.txoff
 245 This tunable specifies the leading target CPU for
 246 transmission queue
 247 .Xr polling 4
 248 processing.
 249 The value specificed must be aligned to the number of transmission queues
 250 enabled and must be less than the power of 2 number of CPUs.
 251 .It Va hw.ixX.npoll.rxoff
 252 This tunable specifies the leading target CPU for
 253 reception queue
 254 .Xr polling 4
 255 processing.
 256 The value specificed must be aligned to the number of reception queues
 257 enabled and must be less than the power of 2 number of CPUs.
 258 .It Va hw.ix.unsupported_sfp
 259 By default,
 260 this driver does not allow "unsupported" SFP modules.
 261 This behavior can be changed by setting this tunable to 1.
 262 .El
 263 .Sh MIB Variables
 264 A number of per-interface variables are implemented in the
 265 .Va dev.ix. Ns Em X
 266 branch of the
 267 .Xr sysctl 3
 268 MIB.
 269 .Bl -tag -width "rxtx_intr_rate"
 270 .It Va rxr
 271 Number of reception queues could be enabled (read-only).
 272 Use the tunable
 273 .Va hw.ix.rxr
 274 or
 275 .Va hw.ixX.rxr
 276 to configure it.
 277 .It Va rxr_inuse
 278 Number of reception queues being used (read-only).
 279 .It Va txr
 280 Number of transmission queues could be enabled (read-only).
 281 Use the tunable
 282 .Va hw.ix.txr
 283 or
 284 .Va hw.ixX.txr
 285 to configure it.
 286 .It Va txr_inuse
 287 Number of transmission queues being used (read-only).
 288 .It Va rxd
 289 Number of descriptors per reception queue (read-only).
 290 Use the tunable
 291 .Va hw.ix.rxd
 292 or
 293 .Va hw.ixX.rxd
 294 to configure it.
 295 .It Va txd
 296 Number of descriptors per transmission queue (read-only).
 297 Use the tunable
 298 .Va hw.ix.txd
 299 or
 300 .Va hw.ixX.txd
 301 to configure it.
 302 .It Va rxtx_intr_rate
 303 If MSI or legacy interrupt is used,
 304 this sysctl controls the highest possible frequency
 305 that interrupt could be generated by the device.
 306 If MSI-X is used,
 307 this sysctl controls the highest possible frequency
 308 that interrupt could be generated by the MSI-X vectors,
 309 which aggregate transmission queue and reception queue procecssing.
 310 It is 8000 by default (125us).
 311 .It Va rx_intr_rate
 312 If MSI-X is used,
 313 this sysctl controls the highest possible frequency
 314 that interrupt could be generated by the MSI-X vectors,
 315 which only process reception queue.
 316 It is 8000 by default (125us).
 317 .It Va tx_intr_rate
 318 If MSI-X is used,
 319 this sysctl controls the highest possible frequency
 320 that interrupt could be generated by the MSI-X vectors,
 321 which only process transmission queue.
 322 It is 6000 by default (~150us).
 323 .It Va sts_intr_rate
 324 If MSI-X is used,
 325 this sysctl controls the highest possible frequency
 326 that interrupt could be generated by the MSI-X vectors,
 327 which only process chip status changes.
 328 It is 8000 by default (125us).
 329 .It Va tx_intr_nsegs
 330 Transmission interrupt is asked to be generated upon every
 331 .Va tx_intr_nsegs
 332 transmission descritors having been setup.
 333 The default value is 1/16 of the number of transmission descriptors per queue.
 334 .It Va tx_wreg_nsegs
 335 The number of transmission descriptors should be setup
 336 before the hardware register is written.
 337 Setting this value too high will have negative effect
 338 on transmission timeliness.
 339 Setting this value too low will hurt overall transmission performance
 340 due to the frequent hardware register writing.
 341 The default value is 8.
 342 .It Va rx_wreg_nsegs
 343 The number of reception descriptors should be setup
 344 before the hardware register is written.
 345 Setting this value too high will make device drop incoming packets.
 346 Setting this value too low will hurt overall reception performance
 347 due to the frequent hardware register writing.
 348 The default value is 32.
 349 .It Va npoll_rxoff
 350 See the tunable
 351 .Va hw.ixX.npoll.rxoff .
 352 The set value will take effect the next time
 353 .Xr polling 4
 354 is enabled on the device.
 355 .It Va npoll_txoff
 356 See the tunable
 357 .Va hw.ixX.npoll.txoff .
 358 The set value will take effect the next time
 359 .Xr polling 4
 360 is enabled on the device.
 361 .It Va flowctrl
 362 Flow control setting.
 363 Set it to 0 to turn off flow control.
 364 Set it to 1 to enable only the reception of pause frames.
 365 Set it to 2 to enable only the generation of pause frames.
 366 Set it to 3 to enable both the reception of pause frames
 367 and generation of pause frames,
 368 i.e. full flow control.
 369 .El
 370 .Sh SEE ALSO
 371 .Xr altq 4 ,
 372 .Xr arp 4 ,
 373 .Xr ifmedia 4 ,
 374 .Xr netintro 4 ,
 375 .Xr ng_ether 4 ,
 376 .Xr polling 4 ,
 377 .Xr vlan 4 ,
 378 .Xr ifconfig 8
 379 .Sh HISTORY
 380 The
 381 .Nm
 382 device driver first appeared in
 383 .Dx 3.1 .
 384 .Sh AUTHORS
 385 The
 386 .Nm
 387 driver was written by
 388 .An Intel Corporation Aq Mt freebsdnic@mailbox.intel.com .