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 May 30, 2013
  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 .Pp
 103 The
 104 .Nm
 105 driver supports the following media types:
 106 .Bl -tag -width ".Cm 10baseT/UTP"
 107 .It Cm autoselect
 108 Enable autoselection of the media type and options.
 109 The user can manually override
 110 the autoselected mode by adding media options to
 111 .Xr rc.conf 5 .
 112 .It Cm 10baseT/UTP
 113 Set 10Mbps operation.
 114 The
 115 .Xr ifconfig 8
 116 .Cm mediaopt
 117 option can also be used to select either
 118 .Cm full-duplex
 119 or
 120 .Cm half-duplex
 121 modes.
 122 .It Cm 100baseTX
 123 Set 100Mbps (Fast Ethernet) operation.
 124 The
 125 .Xr ifconfig 8
 126 .Cm mediaopt
 127 option can also be used to select either
 128 .Cm full-duplex
 129 or
 130 .Cm half-duplex
 131 modes.
 132 .It Cm 1000baseT
 133 Set 1000baseT operation over twisted pair.
 134 Only
 135 .Cm full-duplex
 136 mode is supported.
 137 .El
 138 .Pp
 139 The
 140 .Nm
 141 driver supports the following media options:
 142 .Bl -tag -width ".Cm full-duplex"
 143 .It Cm full-duplex
 144 Force full duplex operation.
 145 .It Cm half-duplex
 146 Force half duplex operation.
 147 .El
 148 .Pp
 149 For more information on configuring this device, see
 150 .Xr ifconfig 8 .
 151 The
 152 .Nm
 153 driver supports
 154 .Xr polling 4 .
 155 .Sh TUNABLES
 156 .Em X
 157 is the device unit number.
 158 .Bl -tag -width ".Va hw.bceX.npoll.offset"
 159 .It Va hw.bce.tx_bds
 160 Maximum number of sending BDs which must be processed by the device
 161 before the device updates the status block and generates interrupt.
 162 It is used together with
 163 .Va hw.bce.tx_ticks
 164 to achieve TX interrupt moderation.
 165 Default value is 255.
 166 .It Va hw.bce.tx_bds_int
 167 Maximum number of sending BDs which must be processed by the device
 168 before the device updates the status block
 169 during host interrupt processing.
 170 Default value is 255.
 171 .It Va hw.bce.tx_ticks
 172 How often status block should be updated and interrupt should be generated
 173 by the device,
 174 due to sending packets.
 175 It is used together with
 176 .Va hw.bce.tx_bds
 177 to achieve TX interrupt moderation.
 178 Default value is 1022 (microseconds).
 179 .It Va hw.bce.tx_ticks_int
 180 How often status block should be updated by the device
 181 during host interrupt processing,
 182 due to sending packets.
 183 Default value is 1022 (microseconds).
 184 .It Va hw.bce.rx_bds
 185 Maximum number of BDs which must be received by the device
 186 before the device updates the status block and generates interrupt.
 187 It is used together with
 188 .Va hw.bce.rx_ticks
 189 to achieve RX interrupt moderation.
 190 Default value is 0.
 191 .It Va hw.bce.rx_bds_int
 192 Maximum number of BDs which must be received by the device
 193 before the device updates the status block
 194 during host interrupt processing.
 195 Default value is 128.
 196 .It Va hw.bce.rx_ticks
 197 How often status block should be updated and interrupt should be generated
 198 by the device,
 199 due to receiving packets.
 200 It is used together with
 201 .Va hw.bce.rx_bds
 202 to achieve RX interrupt moderation.
 203 Default value is 150 (microseconds).
 204 .It Va hw.bce.rx_ticks_int
 205 How often status block should be updated by the device
 206 during host interrupt processing,
 207 due to receiving packets.
 208 Default value is 150 (microseconds).
 209 .It Va hw.bce.msi.enable Va hw.bceX.msi.enable
 210 For BCM5706 and BCM5708,
 211 by default,
 212 the driver will use MSI if it is supported.
 213 This behavior can be turned off by setting this tunable to 0.
 214 .It Va hw.bceX.msi.cpu
 215 If MSI is used, it specifies the MSI's target CPU.
 216 .It Va hw.bce.msix.enable Va hw.bceX.msix.enable
 217 For BCM5709 and BCM5716,
 218 by default,
 219 the driver will use MSI-X if it is supported.
 220 This behavior can be turned off by setting this tunable to 0.
 221 .It Va hw.bce.rx_pages Va hw.bceX.rx_pages
 222 How many reception descriptor pages should be used.
 223 One reception descriptor page holds 256 reception descriptors.
 224 Default value is 2.
 225 .It Va hw.bce.tx_pages Va hw.bceX.tx_pages
 226 How many transmission descriptor pages should be used.
 227 One transmission descriptor page holds 256 transmission descriptors.
 228 Default value is 2.
 229 .It Va hw.bceX.msix.offset
 230 For BCM5709 and BCM5716,
 231 if MSI-X is used,
 232 this tunable specifies the leading target CPU for transmission and reception
 233 queues processing.
 234 The value specificed must be aligned to the number of reception queues
 235 enabled and must be less than the power of 2 number of CPUs.
 236 .It Va hw.bceX.npoll.offset
 237 This tunable specifies the leading target CPU for transmission and reception
 238 queues
 239 .Xr polling 4
 240 processing.
 241 The value specificed must be aligned to the number of reception queues
 242 enabled and must be less than the power of 2 number of CPUs.
 243 .It Va hw.bce.rx_rings Va hw.bceX.rx_rings
 244 For BCM5709 and BCM5716,
 245 if MSI-X is used,
 246 this tunable specifies the number of reception queues to be enabled.
 247 Maximum allowed value for these tunables is 8 and
 248 it must be power of 2 aligned.
 249 Setting these tunables to 0 allows the driver to enable as many reception queues
 250 as allowed by the number of CPUs.
 251 .It Va hw.bce.tx_rings Va hw.bceX.tx_rings
 252 For BCM5709 and BCM5716,
 253 if MSI-X is used,
 254 this tunable specifies the number of transmission queues to be enabled.
 255 Maximum allowed value for these tunables is 8,
 256 it must be power of 2 aligned
 257 and it must be less than or equal to the number of reception queues enabled.
 258 Setting these tunables to 0 allows the driver to enable as many transmission queues
 259 as allowed by the number of CPUs and number reception queues enabled.
 260 .It Va hw.bce.tx_wreg
 261 The number of transmission descriptors should be setup before the hardware
 262 register is written.
 263 Setting this value too high will have negative effect
 264 on transmission timeliness.
 265 Setting this value too low will hurt overall transmission due to the frequent
 266 hardware register writing.
 267 Default value is 8.
 268 .El
 269 .Sh MIB Variables
 270 A number of per-interface variables are implemented in the
 271 .Va hw.bce Ns Em X
 272 branch of the
 273 .Xr sysctl 3
 274 MIB.
 275 .Bl -tag -width "tx_ticks_int"
 276 .It Va tx_bds_int
 277 See the tunable
 278 .Va hw.bce.tx_bds_int .
 279 .It Va tx_bds
 280 See the tunable
 281 .Va hw.bce.tx_bds .
 282 .It Va tx_ticks_int
 283 See the tunable
 284 .Va hw.bce.tx_ticks_int .
 285 .It Va tx_ticks
 286 See the tunable
 287 .Va hw.bce.tx_ticks .
 288 .It Va rx_bds_int
 289 See the tunable
 290 .Va hw.bce.rx_bds_int .
 291 .It Va rx_bds
 292 See the tunable
 293 .Va hw.bce_rx_bds .
 294 .It Va rx_ticks_int
 295 See the tunable
 296 .Va hw.bce.rx_ticks_int .
 297 .It Va rx_ticks
 298 See the tunable
 299 .Va hw.bce.rx_ticks .
 300 .It Va rx_rings
 301 Number of reception queues actually enabled (read-only).
 302 For BCM5709 and BCM5716,
 303 if MSI-X is enabled,
 304 the enabled reception queues will be one more than the
 305 value specified in the tunable
 306 .Va hw.bce.rx_rings
 307 or
 308 .Va hw.bceX.rx_rings .
 309 The extra reception queue is for the packets whose RSS hash
 310 could not be calculated by the hardware.
 311 .It Va tx_rings
 312 Number of transmission queues enable (read-only).
 313 For BCM5709 and BCM5716,
 314 if MSI-X is enabled,
 315 use the tunable
 316 .Va hw.bce.tx_rings
 317 or
 318 .Va hw.bceX.tx_rings
 319 to configure it.
 320 .It Va rx_pages
 321 Number of reception descriptor pages enabled (read-only).
 322 Use the tunable
 323 .Va hw.bce.rx_pages
 324 or
 325 .Va hw.bceX.rx_pages
 326 to configure it.
 327 .It Va tx_pages
 328 Number of transmission descriptor pages enabled (read-only).
 329 Use the tunable
 330 .Va hw.bce.tx_pages
 331 or
 332 .Va hw.bceX.tx_pages
 333 to configure it.
 334 .It Va tx_wreg
 335 See the tunable
 336 .Va hw.bce.tx_wreg .
 337 .It Va npoll_offset
 338 .Xr polling 4
 339 reception and transmission queues' leading target CPU.
 340 It has the same constraints as the tunable
 341 .Va hw.bceX.npoll.offset .
 342 The set value will take effect the next time
 343 .Xr polling 4
 344 is enabled on the device.
 345 .It Va stat_*
 346 Various hardware statistics.
 347 .El
 348 .Sh SEE ALSO
 349 .Xr altq 4 ,
 350 .Xr arp 4 ,
 351 .Xr ifmedia 4 ,
 352 .Xr miibus 4 ,
 353 .Xr netintro 4 ,
 354 .Xr ng_ether 4 ,
 355 .Xr polling 4 ,
 356 .Xr vlan 4 ,
 357 .Xr ifconfig 8
 358 .Sh HISTORY
 359 The
 360 .Nm
 361 device driver first appeared in
 362 .Fx 6.1 .
 363 .Sh AUTHORS
 364 The
 365 .Nm
 366 driver was written by
 367 .An David Christensen Aq Mt davidch@broadcom.com .
 368 .An Sepherosa Ziehau
 369 added receive side scaling,
 370 multiple transmission queues
 371 and multiple vector MSI-X support to
 372 .Dx .