share/man/man4/bnx.4

   1 .\"
   2 .\" Copyright (c) 2012 The DragonFly Project.  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
   6 .\" are met:
   7 .\"
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in
  12 .\"    the documentation and/or other materials provided with the
  13 .\"    distribution.
  14 .\" 3. Neither the name of The DragonFly Project nor the names of its
  15 .\"    contributors may be used to endorse or promote products derived
  16 .\"    from this software without specific, prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  21 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  22 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  24 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .Dd June 16, 2013
  32 .Dt BNX 4
  33 .Os
  34 .Sh NAME
  35 .Nm bnx
  36 .Nd "Broadcom BCM57785/BCM5718 families 10/100/Gigabit Ethernet device"
  37 .Sh SYNOPSIS
  38 .Cd "device miibus"
  39 .Cd "device bnx"
  40 .Pp
  41 Alternatively, to load the driver as a module at boot time, place the
  42 following line in
  43 .Pa /boot/loader.conf :
  44 .Bd -literal -offset indent
  45 if_bnx_load="YES"
  46 .Ed
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 driver supports the PCIe Ethernet adapters based on
  51 Broadcom BCM57785/BCM5718 families chips.
  52 .Pp
  53 The following features are supported in the
  54 .Nm
  55 driver:
  56 .Pp
  57 .Bl -item -offset indent -compact
  58 .It
  59 IP/TCP/UDP checksum offloading
  60 .It
  61 TCP segmentation offloading (TSO)
  62 .It
  63 VLAN tag stripping and inserting
  64 .It
  65 Interrupt coalescing
  66 .It
  67 Receive Side Scaling (RSS),
  68 up to 4 reception queues
  69 .It
  70 Multiple vector MSI-X
  71 .It
  72 Multiple transmission queues
  73 (BCM5717C,
  74 BCM5719 and BCM5720 only),
  75 up to 4 transmission queues
  76 .El
  77 .Pp
  78 By default,
  79 the
  80 .Nm
  81 driver will try enabling as many reception queues as are allowed
  82 by the number of CPUs in the system.
  83 For BCM5717C,
  84 BCM5719 and BCM5720,
  85 in addition to the reception queues,
  86 by default,
  87 the
  88 .Nm
  89 driver will try enabling as many transmission queues as are allowed
  90 by the number of CPUs in the system
  91 and the number of enabled reception queues.
  92 If multiple transmission queues are enabled,
  93 the round-robin arbitration is performed among the transmission queues.
  94 It should be noted that
  95 if both TSO and multiple transmission queues are enabled,
  96 the round-robin arbitration between transmission queues is done
  97 at the TSO packet boundary.
  98 .Pp
  99 The
 100 .Nm
 101 driver supports the following
 102 .Ar media
 103 types:
 104 .Pp
 105 .Bl -tag -width 10baseT/UTP -compact
 106 .It Cm autoselect
 107 Enable autoselection of the media types and options
 108 .Pp
 109 .It Cm 10baseT/UTP
 110 Set 10Mbps operation.
 111 The
 112 .Ar mediaopt
 113 option can also be used to select either
 114 .Ar full-duplex
 115 or
 116 .Ar half-duplex
 117 modes.
 118 .Pp
 119 .It Cm 100baseTX
 120 Set 100Mbps (Fast Ethernet) operation.
 121 The
 122 .Ar mediaopt
 123 option can also be used to select either
 124 .Ar full-duplex
 125 or
 126 .Ar half-duplex
 127 modes.
 128 .Pp
 129 .It Cm 1000baseT
 130 Set 1000Mbps (Gigabit Ethernet) operation.
 131 The
 132 .Ar mediaopt
 133 option can only be set
 134 .Ar full-duplex
 135 mode.
 136 .El
 137 .Pp
 138 The
 139 .Nm
 140 driver supports the following
 141 .Ar media
 142 options:
 143 .Pp
 144 .Bl -tag -width full-duplex -compact
 145 .It Cm full-duplex
 146 Force full duplex operation.
 147 .Pp
 148 .It Cm half-duplex
 149 Force half duplex operation.
 150 .El
 151 .Pp
 152 Note that the 1000baseT media type is only available
 153 if it is supported by the adapter.
 154 For more information on configuring this device,
 155 see
 156 .Xr ifconfig 8 .
 157 The
 158 .Nm
 159 driver supports
 160 .Xr polling 4 .
 161 .Sh HARDWARE
 162 The
 163 .Nm
 164 driver supports Gigabit Ethernet adapters and Fast Ethernet adapters based on
 165 the Broadcom BCM57785/BCM5718 families chips:
 166 .Pp
 167 .Bl -bullet -compact
 168 .It
 169 Broadcom BCM5717 Gigabit Ethernet
 170 .It
 171 Broadcom BCM5717C Gigabit Ethernet
 172 .It
 173 Broadcom BCM5718 Gigabit Ethernet
 174 .It
 175 Broadcom BCM5719 Gigabit Ethernet
 176 .It
 177 Broadcom BCM5720 Gigabit Ethernet
 178 .It
 179 Broadcom BCM5725 Gigabit Ethernet
 180 .It
 181 Broadcom BCM5727 Gigabit Ethernet
 182 .It
 183 Broadcom BCM5762 Gigabit Ethernet
 184 .It
 185 Broadcom BCM57761 Gigabit Ethernet
 186 .It
 187 Broadcom BCM57762 Gigabit Ethernet
 188 .It
 189 Broadcom BCM57765 Gigabit Ethernet
 190 .It
 191 Broadcom BCM57766 Gigabit Ethernet
 192 .It
 193 Broadcom BCM57781 Gigabit Ethernet
 194 .It
 195 Broadcom BCM57782 Gigabit Ethernet
 196 .It
 197 Broadcom BCM57785 Gigabit Ethernet
 198 .It
 199 Broadcom BCM57786 Gigabit Ethernet
 200 .It
 201 Broadcom BCM57791 Fast Ethernet
 202 .It
 203 Broadcom BCM57795 Fast Ethernet
 204 .El
 205 .Sh TUNABLES
 206 .Em X
 207 is the device unit number.
 208 .Bl -tag -width ".Va hw.bnxX.npoll.offset"
 209 .It Va hw.bnx.rx_rings Va hw.bnxX.rx_rings
 210 If MSI-X is used,
 211 this tunable specifies the number of reception queues to be enabled.
 212 Maximum allowed value for these tunables is 4 and
 213 it must be power of 2 aligned.
 214 Setting these tunables to 0 allows the driver to enable as many reception queues
 215 as allowed by the number of CPUs.
 216 .It Va hw.bnx.tx_rings Va hw.bnxX.tx_rings
 217 For BCM5717C,
 218 BCM5719 and BCM5720,
 219 if MSI-X is used,
 220 this tunable specifies the number of transmission queues to be enabled.
 221 Maximum allowed value for these tunables is 4,
 222 it must be power of 2 aligned
 223 and it must be less than or equal to the number of reception queues enabled.
 224 Setting these tunables to 0 allows the driver to enable as many transmission queues
 225 as allowed by the number of CPUs and number reception queues enabled.
 226 .It Va hw.bnx.msix.enable Va hw.bnxX.msix.enable
 227 By default,
 228 the driver will use MSI-X
 229 if it is supported.
 230 This behaviour can be turned off by setting this tunable to 0.
 231 .It Va hw.bnxX.msix.offset
 232 For BCM5717C,
 233 BCM5719 and BCM5720,
 234 if more than 1 reception queues
 235 and more than 1 transmission queues are enabled,
 236 this tunable specifies the leading target CPU for transmission
 237 and reception queues processing.
 238 The value specificed must be aligned to the number of reception queues
 239 enabled and must be less than the power of 2 number of CPUs.
 240 .It Va hw.bnxX.msix.txoff
 241 If more than 1 reception queues are enabled
 242 and only 1 transmission queue is enabled,
 243 this tunable specifies the target CPU for transmission queue processing.
 244 The value specificed must be less than the power of 2 number of CPUs.
 245 .It Va hw.bnxX.msix.rxoff
 246 If more than 1 reception queues are enabled
 247 and only 1 transmission queue is enabled,
 248 this tunable specifies the leading target CPU for reception queues processing.
 249 The value specificed must be aligned to the number of reception queues
 250 enabled and must be less than the power of 2 number of CPUs.
 251 .It Va hw.bnx.msi.enable Va hw.bnxX.msi.enable
 252 If MSI-X is disabled and MSI is supported,
 253 the driver will use MSI.
 254 This behavior can be turned off by setting this tunable to 0.
 255 .It Va hw.bnxX.msi.cpu
 256 If MSI is used, it specifies the MSI's target CPU.
 257 .It Va hw.bnxX.npoll.offset
 258 If only 1 reception queue and only 1 transmission queue are enabled
 259 or more than 1 reception queues and more than 1 transmission queues are enabled,
 260 this tunable specifies the leading target CPU for transmission and reception
 261 queues
 262 .Xr polling 4
 263 processing.
 264 The value specificed must be aligned to the number of reception queues
 265 enabled and must be less than the power of 2 number of CPUs.
 266 .It Va hw.bnxX.npoll.txoff
 267 If more than 1 reception queues are enabled
 268 and only 1 transmission queue is enabled,
 269 this tunable specifies the target CPU for transmission queue
 270 .Xr polling 4
 271 processing.
 272 The value specificed must be less than the power of 2 number of CPUs.
 273 .It Va hw.bnxX.npoll.rxoff
 274 If more than 1 reception queues are enabled
 275 and only 1 transmission queue is enabled,
 276 this tunable specifies the leading target CPU for reception queue
 277 .Xr polling 4
 278 processing.
 279 The value specificed must be aligned to the number of reception queues
 280 enabled and must be less than the power of 2 number of CPUs.
 281 .El
 282 .Sh MIB Variables
 283 A number of per-interface variables are implemented in the
 284 .Va hw.bnx Ns Em X
 285 branch of the
 286 .Xr sysctl 3
 287 MIB.
 288 .Bl -tag -width "rx_coal_bds_poll"
 289 .It Va rx_rings
 290 Number of reception queues enabled (read-only).
 291 Use the tunable
 292 .Va hw.bnx.rx_rings
 293 or
 294 .Va hw.bnxX.rx_rings
 295 to configure it.
 296 .It Va tx_rings
 297 Number of transmission queues enabled (read-only).
 298 Use the tunable
 299 .Va hw.bnx.tx_rings
 300 or
 301 .Va hw.bnxX.tx_rings
 302 to configure it.
 303 .It Va rx_coal_ticks
 304 How often status block should be updated and interrupt should be generated
 305 by the device,
 306 due to receiving packets.
 307 It is used together with
 308 .Va rx_coal_bds
 309 to achieve RX interrupt moderation.
 310 Default value is 150 (microseconds).
 311 .It Va tx_coal_ticks
 312 How often status block should be updated and interrupt should be generated
 313 by the device,
 314 due to sending packets.
 315 It is used together with
 316 .Va tx_coal_bds
 317 to achieve TX interrupt moderation.
 318 Default value is 1023 (microseconds).
 319 .It Va rx_coal_bds
 320 Maximum number of BDs which must be received by the device
 321 before the device updates the status block and generates interrupt.
 322 It is used together with
 323 .Va rx_coal_ticks
 324 to achieve RX interrupt moderation.
 325 Default value is 0 (disabled).
 326 .It Va rx_coal_bds_poll
 327 Maximum number of BDs which must be received by the device
 328 before the device updates the status block during
 329 .Xr polling 4 .
 330 It is used together with
 331 .Va rx_coal_ticks
 332 to reduce the frequency of status block updating due to RX.
 333 Default value is 32.
 334 .It Va tx_coal_bds
 335 Maximum number of sending BDs which must be processed by the device
 336 before the device updates the status block and generates interrupt.
 337 It is used together with
 338 .Va tx_coal_ticks
 339 to achieve TX interrupt moderation.
 340 Default value is 128.
 341 .It Va tx_coal_bds_poll
 342 Maximum number of sending BDs which must be processed by the device
 343 before the device updates the status block during
 344 .Xr polling 4 .
 345 It is used together with
 346 .Va tx_coal_ticks
 347 to reduce the frequency of status block updating due to TX.
 348 Default value is 64.
 349 .It Va force_defrag
 350 Force defragment the sending mbuf chains,
 351 if the mbuf chain is not a TSO segment and contains more than 1 mbufs.
 352 This improves transmission performance on certain low end chips,
 353 however,
 354 this also increases CPU load.
 355 Default value is 0 (disabled).
 356 .It Va tx_wreg
 357 The number of transmission descriptors should be setup before the hardware
 358 register is written.
 359 Setting this value too high will have negative effect
 360 on transmission timeliness.
 361 Setting this value too low will hurt overall transmission performance
 362 due to the frequent hardware register writing.
 363 Default value is 8.
 364 .It Va std_refill
 365 Number of packets should be received
 366 before the standard reception producer ring is refilled.
 367 Setting this value too low will cause extra thread scheduling cost.
 368 Setting this value too high will make chip drop incoming packets.
 369 Default value is 128 / number of reception queues.
 370 .It Va rx_coal_bds_int
 371 Maximum number of BDs which must be received by the device
 372 before the device updates the status block
 373 during host interrupt processing.
 374 Default value is 80.
 375 .It Va tx_coal_bds_int
 376 Maximum number of sending BDs which must be processed by the device
 377 before the device updates the status block
 378 during host interrupt processing.
 379 Default value is 64.
 380 .It Va npoll_offset
 381 See the tunable
 382 .Va hw.bnxX.npoll.offset .
 383 The set value will take effect the next time
 384 .Xr polling 4
 385 is enabled on the device.
 386 .It Va npoll_txoff
 387 See the tunable
 388 .Va hw.bnxX.npoll.txoff .
 389 The set value will take effect the next time
 390 .Xr polling 4
 391 is enabled on the device.
 392 .It Va npoll_rxoff
 393 See the tunable
 394 .Va hw.bnxX.npoll.rxoff .
 395 The set value will take effect the next time
 396 .Xr polling 4
 397 is enabled on the device.
 398 .It Va norxbds
 399 Number of times the standard reception producer ring is short
 400 of reception BDs.
 401 If this value grows fast,
 402 it is usually an indication that
 403 .Va std_refill
 404 is set too high.
 405 .It Va errors
 406 Number of errors, both critical and non-critical, happened.
 407 .El
 408 .Sh SEE ALSO
 409 .Xr arp 4 ,
 410 .Xr bge 4 ,
 411 .Xr ifmedia 4 ,
 412 .Xr miibus 4 ,
 413 .Xr netintro 4 ,
 414 .Xr ng_ether 4 ,
 415 .Xr polling 4 ,
 416 .Xr vlan 4 ,
 417 .Xr ifconfig 8
 418 .Sh HISTORY
 419 The
 420 .Nm
 421 device driver first appeared in
 422 .Dx 3.1 .
 423 .Sh AUTHORS
 424 .An -nosplit
 425 The
 426 .Nm
 427 driver was based on
 428 .Xr bge 4
 429 written by
 430 .An Bill Paul Aq Mt wpaul@windriver.com .
 431 .An Sepherosa Ziehau
 432 added receive side scaling,
 433 multiple transmission queues
 434 and multiple MSI-X support to
 435 .Dx .