share/man/man4/bce.4

   1 .\" Copyright (c) 2006 Broadcom Corporation
   2 .\"  David Christensen <davidch@broadcom.com>.  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 the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. Neither the name of Broadcom Corporation nor the name of its contributors
  14 .\"    may be used to endorse or promote products derived from this software
  15 .\"    without specific prior written consent.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS'
  18 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
  21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  27 .\" THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD: src/share/man/man4/bce.4,v 1.7 2007/02/09 18:26:13 brueffer Exp $
  30 .\"
  31 .Dd November 28, 2014
  32 .Dt BCE 4
  33 .Os
  34 .Sh NAME
  35 .Nm bce
  36 .Nd "Broadcom NetXtreme II PCIe Gigabit Ethernet adapter driver"
  37 .Sh SYNOPSIS
  38 To compile this driver into the kernel,
  39 place the following lines in your
  40 kernel configuration file:
  41 .Bd -ragged -offset indent
  42 .Cd "device miibus"
  43 .Cd "device bce"
  44 .Ed
  45 .Pp
  46 Alternatively, to load the driver as a
  47 module at boot time, place the following line in
  48 .Xr loader.conf 5 :
  49 .Bd -literal -offset indent
  50 if_bce_load="YES"
  51 .Ed
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 driver supports Broadcom's NetXtreme II product family, including the
  56 BCM5706, BCM5708, BCM5709 and BCM5716 Ethernet controllers.
  57 .Pp
  58 The NetXtreme II product family is composed of various Converged NIC (or CNIC)
  59 Ethernet controllers which support a TCP Offload Engine (TOE), Remote DMA (RDMA),
  60 and iSCSI acceleration, in addition to standard L2 Ethernet traffic, all on the
  61 same controller.
  62 The following features are supported in the
  63 .Nm
  64 driver:
  65 .Pp
  66 .Bl -item -offset indent -compact
  67 .It
  68 .\"IP/TCP/UDP checksum offload
  69 TCP/UDP checksum offload
  70 .\".It
  71 .\"Jumbo frames (up to 9022 bytes)
  72 .It
  73 TCP segmentation offloading (TSO)
  74 .It
  75 VLAN tag stripping and inserting
  76 .It
  77 Interrupt coalescing
  78 .It
  79 10/100/1000Mbps operation in full-duplex mode
  80 .It
  81 10/100Mbps operation in half-duplex mode
  82 .El
  83 .Pp
  84 The following features are supported in the
  85 .Nm
  86 driver for BCM5709 and BCM5716:
  87 .Pp
  88 .Bl -item -offset indent -compact
  89 .It
  90 Receive side scaling (RSS), up to 8 reception queues
  91 .It
  92 Multiple tranmission queues, up to 8 transmission queues
  93 .It
  94 Multiple vector MSI-X
  95 .El
  96 .Pp
  97 For BCM5709 and BCM5716,
  98 by default, the
  99 .Nm
 100 driver will try enabling as many reception and transmission queues
 101 as are allowed by the number of CPUs in the system.
 102 If multiple transmission queues are enabled,
 103 the round-robin arbitration is performed among the transmission queues.
 104 It should be noted that
 105 if both TSO and multiple transmission queues are enabled,
 106 the round-robin arbitration between transmission queues is done
 107 at the TSO packet boundary.
 108 .Pp
 109 The
 110 .Nm
 111 driver supports the following media types:
 112 .Bl -tag -width ".Cm 10baseT/UTP"
 113 .It Cm autoselect
 114 Enable autoselection of the media type and options.
 115 The user can manually override
 116 the autoselected mode by adding media options to
 117 .Xr rc.conf 5 .
 118 .It Cm 10baseT/UTP
 119 Set 10Mbps operation.
 120 The
 121 .Xr ifconfig 8
 122 .Cm mediaopt
 123 option can also be used to select either
 124 .Cm full-duplex
 125 or
 126 .Cm half-duplex
 127 modes.
 128 .It Cm 100baseTX
 129 Set 100Mbps (Fast Ethernet) operation.
 130 The
 131 .Xr ifconfig 8
 132 .Cm mediaopt
 133 option can also be used to select either
 134 .Cm full-duplex
 135 or
 136 .Cm half-duplex
 137 modes.
 138 .It Cm 1000baseT
 139 Set 1000baseT operation over twisted pair.
 140 Only
 141 .Cm full-duplex
 142 mode is supported.
 143 .El
 144 .Pp
 145 The
 146 .Nm
 147 driver supports the following media options:
 148 .Bl -tag -width ".Cm full-duplex"
 149 .It Cm full-duplex
 150 Force full duplex operation.
 151 .It Cm half-duplex
 152 Force half duplex operation.
 153 .El
 154 .Pp
 155 For more information on configuring this device, see
 156 .Xr ifconfig 8 .
 157 The
 158 .Nm
 159 driver supports
 160 .Xr polling 4 .
 161 .Sh TUNABLES
 162 .Em X
 163 is the device unit number.
 164 .Bl -tag -width ".Va hw.bceX.npoll.offset"
 165 .It Va hw.bce.tx_bds
 166 Maximum number of sending BDs which must be processed by the device
 167 before the device updates the status block and generates interrupt.
 168 It is used together with
 169 .Va hw.bce.tx_ticks
 170 to achieve TX interrupt moderation.
 171 Default value is 255.
 172 .It Va hw.bce.tx_bds_int
 173 Maximum number of sending BDs which must be processed by the device
 174 before the device updates the status block
 175 during host interrupt processing.
 176 Default value is 255.
 177 .It Va hw.bce.tx_ticks
 178 How often status block should be updated and interrupt should be generated
 179 by the device,
 180 due to sending packets.
 181 It is used together with
 182 .Va hw.bce.tx_bds
 183 to achieve TX interrupt moderation.
 184 Default value is 1022 (microseconds).
 185 .It Va hw.bce.tx_ticks_int
 186 How often status block should be updated by the device
 187 during host interrupt processing,
 188 due to sending packets.
 189 Default value is 1022 (microseconds).
 190 .It Va hw.bce.rx_bds
 191 Maximum number of BDs which must be received by the device
 192 before the device updates the status block and generates interrupt.
 193 It is used together with
 194 .Va hw.bce.rx_ticks
 195 to achieve RX interrupt moderation.
 196 Default value is 0.
 197 .It Va hw.bce.rx_bds_int
 198 Maximum number of BDs which must be received by the device
 199 before the device updates the status block
 200 during host interrupt processing.
 201 Default value is 128.
 202 .It Va hw.bce.rx_ticks
 203 How often status block should be updated and interrupt should be generated
 204 by the device,
 205 due to receiving packets.
 206 It is used together with
 207 .Va hw.bce.rx_bds
 208 to achieve RX interrupt moderation.
 209 Default value is 150 (microseconds).
 210 .It Va hw.bce.rx_ticks_int
 211 How often status block should be updated by the device
 212 during host interrupt processing,
 213 due to receiving packets.
 214 Default value is 150 (microseconds).
 215 .It Va hw.bce.msi.enable Va hw.bceX.msi.enable
 216 For BCM5706 and BCM5708,
 217 by default,
 218 the driver will use MSI if it is supported.
 219 This behavior can be turned off by setting this tunable to 0.
 220 .It Va hw.bceX.msi.cpu
 221 If MSI is used, it specifies the MSI's target CPU.
 222 .It Va hw.bce.msix.enable Va hw.bceX.msix.enable
 223 For BCM5709 and BCM5716,
 224 by default,
 225 the driver will use MSI-X if it is supported.
 226 This behavior can be turned off by setting this tunable to 0.
 227 .It Va hw.bce.rx_pages Va hw.bceX.rx_pages
 228 How many reception descriptor pages should be used.
 229 One reception descriptor page holds 256 reception descriptors.
 230 Default value is 2.
 231 .It Va hw.bce.tx_pages Va hw.bceX.tx_pages
 232 How many transmission descriptor pages should be used.
 233 One transmission descriptor page holds 256 transmission descriptors.
 234 Default value is 2.
 235 .It Va hw.bceX.msix.offset
 236 For BCM5709 and BCM5716,
 237 if MSI-X is used,
 238 this tunable specifies the leading target CPU for transmission and reception
 239 queues processing.
 240 The value specificed must be aligned to the number of reception queues
 241 enabled and must be less than the power of 2 number of CPUs.
 242 .It Va hw.bceX.npoll.offset
 243 This tunable specifies the leading target CPU for transmission and reception
 244 queues
 245 .Xr polling 4
 246 processing.
 247 The value specificed must be aligned to the number of reception queues
 248 enabled and must be less than the power of 2 number of CPUs.
 249 .It Va hw.bce.rx_rings Va hw.bceX.rx_rings
 250 For BCM5709 and BCM5716,
 251 if MSI-X is used,
 252 this tunable specifies the number of reception queues to be enabled.
 253 Maximum allowed value for these tunables is 8 and
 254 it must be power of 2 aligned.
 255 Setting these tunables to 0 allows the driver to enable as many reception queues
 256 as allowed by the number of CPUs.
 257 .It Va hw.bce.tx_rings Va hw.bceX.tx_rings
 258 For BCM5709 and BCM5716,
 259 if MSI-X is used,
 260 this tunable specifies the number of transmission queues to be enabled.
 261 Maximum allowed value for these tunables is 8,
 262 it must be power of 2 aligned
 263 and it must be less than or equal to the number of reception queues enabled.
 264 Setting these tunables to 0 allows the driver to enable as many transmission queues
 265 as allowed by the number of CPUs and number reception queues enabled.
 266 .It Va hw.bce.tx_wreg
 267 The number of transmission descriptors should be setup before the hardware
 268 register is written.
 269 Setting this value too high will have negative effect
 270 on transmission timeliness.
 271 Setting this value too low will hurt overall transmission due to the frequent
 272 hardware register writing.
 273 Default value is 8.
 274 .El
 275 .Sh MIB Variables
 276 A number of per-interface variables are implemented in the
 277 .Va dev.bce. Ns Em X
 278 branch of the
 279 .Xr sysctl 3
 280 MIB.
 281 .Bl -tag -width "tx_ticks_int"
 282 .It Va tx_bds_int
 283 See the tunable
 284 .Va hw.bce.tx_bds_int .
 285 .It Va tx_bds
 286 See the tunable
 287 .Va hw.bce.tx_bds .
 288 .It Va tx_ticks_int
 289 See the tunable
 290 .Va hw.bce.tx_ticks_int .
 291 .It Va tx_ticks
 292 See the tunable
 293 .Va hw.bce.tx_ticks .
 294 .It Va rx_bds_int
 295 See the tunable
 296 .Va hw.bce.rx_bds_int .
 297 .It Va rx_bds
 298 See the tunable
 299 .Va hw.bce_rx_bds .
 300 .It Va rx_ticks_int
 301 See the tunable
 302 .Va hw.bce.rx_ticks_int .
 303 .It Va rx_ticks
 304 See the tunable
 305 .Va hw.bce.rx_ticks .
 306 .It Va rx_rings
 307 Number of reception queues actually enabled (read-only).
 308 For BCM5709 and BCM5716,
 309 if MSI-X is enabled,
 310 the enabled reception queues will be one more than the
 311 value specified in the tunable
 312 .Va hw.bce.rx_rings
 313 or
 314 .Va hw.bceX.rx_rings .
 315 The extra reception queue is for the packets whose RSS hash
 316 could not be calculated by the hardware.
 317 .It Va tx_rings
 318 Number of transmission queues enable (read-only).
 319 For BCM5709 and BCM5716,
 320 if MSI-X is enabled,
 321 use the tunable
 322 .Va hw.bce.tx_rings
 323 or
 324 .Va hw.bceX.tx_rings
 325 to configure it.
 326 .It Va rx_pages
 327 Number of reception descriptor pages enabled (read-only).
 328 Use the tunable
 329 .Va hw.bce.rx_pages
 330 or
 331 .Va hw.bceX.rx_pages
 332 to configure it.
 333 .It Va tx_pages
 334 Number of transmission descriptor pages enabled (read-only).
 335 Use the tunable
 336 .Va hw.bce.tx_pages
 337 or
 338 .Va hw.bceX.tx_pages
 339 to configure it.
 340 .It Va tx_wreg
 341 See the tunable
 342 .Va hw.bce.tx_wreg .
 343 .It Va npoll_offset
 344 .Xr polling 4
 345 reception and transmission queues' leading target CPU.
 346 It has the same constraints as the tunable
 347 .Va hw.bceX.npoll.offset .
 348 The set value will take effect the next time
 349 .Xr polling 4
 350 is enabled on the device.
 351 .It Va stat_*
 352 Various hardware statistics.
 353 .El
 354 .Sh SEE ALSO
 355 .Xr altq 4 ,
 356 .Xr arp 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 .Fx 6.1 .
 369 .Sh AUTHORS
 370 The
 371 .Nm
 372 driver was written by
 373 .An David Christensen Aq Mt davidch@broadcom.com .
 374 .An Sepherosa Ziehau
 375 added receive side scaling,
 376 multiple transmission queues
 377 and multiple vector MSI-X support to
 378 .Dx .