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