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 (BCM5719 and BCM5720 only),
  74 up to 4 transmission queues
  75 .El
  76 .Pp
  77 By default,
  78 the
  79 .Nm
  80 driver will try enabling as many reception queues as are allowed
  81 by the number of CPUs in the system.
  82 For BCM5719 and BCM5720,
  83 in addition to the reception queues,
  84 by default,
  85 the
  86 .Nm
  87 driver will try enabling as many transmission queues as are allowed
  88 by the number of CPUs in the system
  89 and the number of enabled reception queues.
  90 .Pp
  91 The
  92 .Nm
  93 driver supports the following
  94 .Ar media
  95 types:
  96 .Pp
  97 .Bl -tag -width 10baseT/UTP -compact
  98 .It Cm autoselect
  99 Enable autoselection of the media types and options
 100 .Pp
 101 .It Cm 10baseT/UTP
 102 Set 10Mbps operation.
 103 The
 104 .Ar mediaopt
 105 option can also be used to select either
 106 .Ar full-duplex
 107 or
 108 .Ar half-duplex
 109 modes.
 110 .Pp
 111 .It Cm 100baseTX
 112 Set 100Mbps (Fast Ethernet) operation.
 113 The
 114 .Ar mediaopt
 115 option can also be used to select either
 116 .Ar full-duplex
 117 or
 118 .Ar half-duplex
 119 modes.
 120 .Pp
 121 .It Cm 1000baseT
 122 Set 1000Mbps (Gigabit Ethernet) operation.
 123 The
 124 .Ar mediaopt
 125 option can only be set
 126 .Ar full-duplex
 127 mode.
 128 .El
 129 .Pp
 130 The
 131 .Nm
 132 driver supports the following
 133 .Ar media
 134 options:
 135 .Pp
 136 .Bl -tag -width full-duplex -compact
 137 .It Cm full-duplex
 138 Force full duplex operation.
 139 .Pp
 140 .It Cm half-duplex
 141 Force half duplex operation.
 142 .El
 143 .Pp
 144 Note that the 1000baseT media type is only available
 145 if it is supported by the adapter.
 146 For more information on configuring this device,
 147 see
 148 .Xr ifconfig 8 .
 149 The
 150 .Nm
 151 driver supports
 152 .Xr polling 4 .
 153 .Sh TUNABLES
 154 .Em X
 155 is the device unit number.
 156 .Bl -tag -width ".Va hw.bnxX.npoll.offset"
 157 .It Va hw.bnx.rx_rings Va hw.bnxX.rx_rings
 158 If MSI-X is used,
 159 this tunable specifies the number of reception queues to be enabled.
 160 Maximum allowed value for these tunables is 4 and
 161 it must be power of 2 aligned.
 162 Setting these tunables to 0 allows the driver to enable as many reception queues
 163 as allowed by the number of CPUs.
 164 .It Va hw.bnx.tx_rings Va hw.bnxX.tx_rings
 165 For BCM5719 and BCM5720,
 166 if MSI-X is used,
 167 this tunable specifies the number of transmission queues to be enabled.
 168 Maximum allowed value for these tunables is 4,
 169 it must be power of 2 aligned
 170 and it must be less than or equal to the number of reception queues enabled.
 171 Setting these tunables to 0 allows the driver to enable as many transmission queues
 172 as allowed by the number of CPUs and number reception queues enabled.
 173 .It Va hw.bnx.msix.enable Va hw.bnxX.msix.enable
 174 By default,
 175 the driver will use MSI-X
 176 if it is supported.
 177 This behaviour can be turned off by setting this tunable to 0.
 178 .It Va hw.bnxX.msix.offset
 179 For BCM5719 and BCM5720,
 180 if more than 1 reception queues
 181 and more than 1 transmission queues are enabled,
 182 this tunable specifies the leading target CPU for transmission
 183 and reception queues processing.
 184 The value specificed must be aligned to the number of reception queues
 185 enabled and must be less than the power of 2 number of CPUs.
 186 .It Va hw.bnxX.msix.txoff
 187 If more than 1 reception queues are enabled
 188 and only 1 transmission queue is enabled,
 189 this tunable specifies the target CPU for transmission queue processing.
 190 The value specificed must be less than the power of 2 number of CPUs.
 191 .It Va hw.bnxX.msix.rxoff
 192 If more than 1 reception queues are enabled
 193 and only 1 transmission queue is enabled,
 194 this tunable specifies the leading target CPU for reception queues processing.
 195 The value specificed must be aligned to the number of reception queues
 196 enabled and must be less than the power of 2 number of CPUs.
 197 .It Va hw.bnx.msi.enable Va hw.bnxX.msi.enable
 198 If MSI-X is disabled and MSI is supported,
 199 the driver will use MSI.
 200 This behavior can be turned off by setting this tunable to 0.
 201 .It Va hw.bnxX.msi.cpu
 202 If MSI is used, it specifies the MSI's target CPU.
 203 .It Va hw.bnxX.npoll.offset
 204 If only 1 reception queue and only 1 transmission queue are enabled
 205 or more than 1 reception queues and more than 1 transmission queues are enabled,
 206 this tunable specifies the leading target CPU for transmission and reception
 207 queues
 208 .Xr polling 4
 209 processing.
 210 The value specificed must be aligned to the number of reception queues
 211 enabled and must be less than the power of 2 number of CPUs.
 212 .It Va hw.bnxX.npoll.txoff
 213 If more than 1 reception queues are enabled
 214 and only 1 transmission queue is enabled,
 215 this tunable specifies the target CPU for transmission queue
 216 .Xr polling 4
 217 processing.
 218 The value specificed must be less than the power of 2 number of CPUs.
 219 .It Va hw.bnxX.npoll.rxoff
 220 If more than 1 reception queues are enabled
 221 and only 1 transmission queue is enabled,
 222 this tunable specifies the leading target CPU for reception queue
 223 .Xr polling 4
 224 processing.
 225 The value specificed must be aligned to the number of reception queues
 226 enabled and must be less than the power of 2 number of CPUs.
 227 .El
 228 .Sh MIB Variables
 229 A number of per-interface variables are implemented in the
 230 .Va hw.bnx Ns Em X
 231 branch of the
 232 .Xr sysctl 3
 233 MIB.
 234 .Bl -tag -width "rx_coal_bds_poll"
 235 .It Va rx_rings
 236 Number of reception queues enabled (read-only).
 237 Use the tunable
 238 .Va hw.bnx.rx_rings
 239 or
 240 .Va hw.bnxX.rx_rings
 241 to configure it.
 242 .It Va tx_rings
 243 Number of transmission queues enabled (read-only).
 244 Use the tunable
 245 .Va hw.bnx.tx_rings
 246 or
 247 .Va hw.bnxX.tx_rings
 248 to configure it.
 249 .It Va rx_coal_ticks
 250 How often status block should be updated and interrupt should be generated
 251 by the device,
 252 due to receiving packets.
 253 It is used together with
 254 .Va rx_coal_bds
 255 to achieve RX interrupt moderation.
 256 Default value is 150 (microseconds).
 257 .It Va tx_coal_ticks
 258 How often status block should be updated and interrupt should be generated
 259 by the device,
 260 due to sending packets.
 261 It is used together with
 262 .Va tx_coal_bds
 263 to achieve TX interrupt moderation.
 264 Default value is 1023 (microseconds).
 265 .It Va rx_coal_bds
 266 Maximum number of BDs which must be received by the device
 267 before the device updates the status block and generates interrupt.
 268 It is used together with
 269 .Va rx_coal_ticks
 270 to achieve RX interrupt moderation.
 271 Default value is 0 (disabled).
 272 .It Va rx_coal_bds_poll
 273 Maximum number of BDs which must be received by the device
 274 before the device updates the status block during
 275 .Xr polling 4 .
 276 It is used together with
 277 .Va rx_coal_ticks
 278 to reduce the frequency of status block updating due to RX.
 279 Default value is 32.
 280 .It Va tx_coal_bds
 281 Maximum number of sending BDs which must be processed by the device
 282 before the device updates the status block and generates interrupt.
 283 It is used together with
 284 .Va tx_coal_ticks
 285 to achieve TX interrupt moderation.
 286 Default value is 128.
 287 .It Va tx_coal_bds_poll
 288 Maximum number of sending BDs which must be processed by the device
 289 before the device updates the status block during
 290 .Xr polling 4 .
 291 It is used together with
 292 .Va tx_coal_ticks
 293 to reduce the frequency of status block updating due to TX.
 294 Default value is 64.
 295 .It Va force_defrag
 296 Force defragment the sending mbuf chains,
 297 if the mbuf chain is not a TSO segment and contains more than 1 mbufs.
 298 This improves transmission performance on certain low end chips,
 299 however,
 300 this also increases CPU load.
 301 Default value is 0 (disabled).
 302 .It Va tx_wreg
 303 The number of transmission descriptors should be setup before the hardware
 304 register is written.
 305 Setting this value too high will have negative effect
 306 on transmission timeliness.
 307 Setting this value too low will hurt overall transmission performance
 308 due to the frequent hardware register writing.
 309 Default value is 8.
 310 .It Va std_refill
 311 Number of packets should be received
 312 before the standard reception producer ring is refilled.
 313 Setting this value too low will cause extra thread scheduling cost.
 314 Setting this value too high will make chip drop incoming packets.
 315 Default value is 128 / number of reception queues.
 316 .It Va rx_coal_bds_int
 317 Maximum number of BDs which must be received by the device
 318 before the device updates the status block
 319 during host interrupt processing.
 320 Default value is 80.
 321 .It Va tx_coal_bds_int
 322 Maximum number of sending BDs which must be processed by the device
 323 before the device updates the status block
 324 during host interrupt processing.
 325 Default value is 64.
 326 .It Va npoll_offset
 327 See the tunable
 328 .Va hw.bnxX.npoll.offset .
 329 The set value will take effect the next time
 330 .Xr polling 4
 331 is enabled on the device.
 332 .It Va npoll_txoff
 333 See the tunable
 334 .Va hw.bnxX.npoll.txoff .
 335 The set value will take effect the next time
 336 .Xr polling 4
 337 is enabled on the device.
 338 .It Va npoll_rxoff
 339 See the tunable
 340 .Va hw.bnxX.npoll.rxoff .
 341 The set value will take effect the next time
 342 .Xr polling 4
 343 is enabled on the device.
 344 .It Va norxbds
 345 Number of times the standard reception producer ring is short
 346 of reception BDs.
 347 If this value grows fast,
 348 it is usually an indication that
 349 .Va std_refill
 350 is set too high.
 351 .It Va errors
 352 Number of errors, both critical and non-critical, happened.
 353 .El
 354 .Sh SEE ALSO
 355 .Xr arp 4 ,
 356 .Xr bge 4 ,
 357 .Xr ifmedia 4 ,
 358 .Xr miibus 4 ,
 359 .Xr netintro 4 ,
 360 .Xr ng_ether 4 ,
 361 .Xr polling 4 ,
 362 .Xr vlan 4 ,
 363 .Xr ifconfig 8
 364 .Sh HISTORY
 365 The
 366 .Nm
 367 device driver first appeared in
 368 .Dx 3.1 .
 369 .Sh AUTHORS
 370 .An -nosplit
 371 The
 372 .Nm
 373 driver was based on
 374 .Xr bge 4
 375 written by
 376 .An Bill Paul
 377 .Aq wpaul@windriver.com .
 378 Sepherosa Ziehau added receive side scaling,
 379 multiple transmission queues
 380 and multiple MSI-X support to
 381 .Dx .