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 May 13, 2017
  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.bnx.msi.enable Va hw.bnxX.msi.enable
 232 If MSI-X is disabled and MSI is supported,
 233 the driver will use MSI.
 234 This behavior can be turned off by setting this tunable to 0.
 235 .It Va hw.bnxX.msi.cpu
 236 If MSI is used, it specifies the MSI's target CPU.
 237 .El
 238 .Sh MIB Variables
 239 A number of per-interface variables are implemented in the
 240 .Va dev.bnx. Ns Em X
 241 branch of the
 242 .Xr sysctl 3
 243 MIB.
 244 .Bl -tag -width "rx_coal_bds_poll"
 245 .It Va rx_rings
 246 Number of reception queues enabled (read-only).
 247 Use the tunable
 248 .Va hw.bnx.rx_rings
 249 or
 250 .Va hw.bnxX.rx_rings
 251 to configure it.
 252 .It Va tx_rings
 253 Number of transmission queues enabled (read-only).
 254 Use the tunable
 255 .Va hw.bnx.tx_rings
 256 or
 257 .Va hw.bnxX.tx_rings
 258 to configure it.
 259 .It Va rx_coal_ticks
 260 How often status block should be updated and interrupt should be generated
 261 by the device,
 262 due to receiving packets.
 263 It is used together with
 264 .Va rx_coal_bds
 265 to achieve RX interrupt moderation.
 266 Default value is 150 (microseconds).
 267 .It Va tx_coal_ticks
 268 How often status block should be updated and interrupt should be generated
 269 by the device,
 270 due to sending packets.
 271 It is used together with
 272 .Va tx_coal_bds
 273 to achieve TX interrupt moderation.
 274 Default value is 1023 (microseconds).
 275 .It Va rx_coal_bds
 276 Maximum number of BDs which must be received by the device
 277 before the device updates the status block and generates interrupt.
 278 It is used together with
 279 .Va rx_coal_ticks
 280 to achieve RX interrupt moderation.
 281 Default value is 0 (disabled).
 282 .It Va rx_coal_bds_poll
 283 Maximum number of BDs which must be received by the device
 284 before the device updates the status block during
 285 .Xr polling 4 .
 286 It is used together with
 287 .Va rx_coal_ticks
 288 to reduce the frequency of status block updating due to RX.
 289 Default value is 32.
 290 .It Va tx_coal_bds
 291 Maximum number of sending BDs which must be processed by the device
 292 before the device updates the status block and generates interrupt.
 293 It is used together with
 294 .Va tx_coal_ticks
 295 to achieve TX interrupt moderation.
 296 Default value is 128.
 297 .It Va tx_coal_bds_poll
 298 Maximum number of sending BDs which must be processed by the device
 299 before the device updates the status block during
 300 .Xr polling 4 .
 301 It is used together with
 302 .Va tx_coal_ticks
 303 to reduce the frequency of status block updating due to TX.
 304 Default value is 64.
 305 .It Va force_defrag
 306 Force defragment the sending mbuf chains,
 307 if the mbuf chain is not a TSO segment and contains more than 1 mbufs.
 308 This improves transmission performance on certain low end chips,
 309 however,
 310 this also increases CPU load.
 311 Default value is 0 (disabled).
 312 .It Va tx_wreg
 313 The number of transmission descriptors should be setup before the hardware
 314 register is written.
 315 Setting this value too high will have negative effect
 316 on transmission timeliness.
 317 Setting this value too low will hurt overall transmission performance
 318 due to the frequent hardware register writing.
 319 Default value is 8.
 320 .It Va std_refill
 321 Number of packets should be received
 322 before the standard reception producer ring is refilled.
 323 Setting this value too low will cause extra thread scheduling cost.
 324 Setting this value too high will make chip drop incoming packets.
 325 Default value is 128 / number of reception queues.
 326 .It Va rx_coal_bds_int
 327 Maximum number of BDs which must be received by the device
 328 before the device updates the status block
 329 during host interrupt processing.
 330 Default value is 80.
 331 .It Va tx_coal_bds_int
 332 Maximum number of sending BDs which must be processed by the device
 333 before the device updates the status block
 334 during host interrupt processing.
 335 Default value is 64.
 336 .It Va norxbds
 337 Number of times the standard reception producer ring is short
 338 of reception BDs.
 339 If this value grows fast,
 340 it is usually an indication that
 341 .Va std_refill
 342 is set too high.
 343 .It Va errors
 344 Number of errors, both critical and non-critical, happened.
 345 .El
 346 .Sh SEE ALSO
 347 .Xr arp 4 ,
 348 .Xr bge 4 ,
 349 .Xr ifmedia 4 ,
 350 .Xr miibus 4 ,
 351 .Xr netintro 4 ,
 352 .Xr ng_ether 4 ,
 353 .Xr polling 4 ,
 354 .Xr vlan 4 ,
 355 .Xr ifconfig 8
 356 .Sh HISTORY
 357 The
 358 .Nm
 359 device driver first appeared in
 360 .Dx 3.1 .
 361 .Sh AUTHORS
 362 .An -nosplit
 363 The
 364 .Nm
 365 driver was based on
 366 .Xr bge 4
 367 written by
 368 .An Bill Paul Aq Mt wpaul@windriver.com .
 369 .An Sepherosa Ziehau
 370 added receive side scaling,
 371 multiple transmission queues
 372 and multiple MSI-X support to
 373 .Dx .