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 June 1, 2017
  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.bce.rx_rings Va hw.bceX.rx_rings
 236 For BCM5709 and BCM5716,
 237 if MSI-X is used,
 238 this tunable specifies the number of reception queues to be enabled.
 239 Maximum allowed value for these tunables is 8.
 240 Setting these tunables to 0 allows the driver to enable as many reception queues
 241 as allowed by the number of CPUs.
 242 .It Va hw.bce.tx_rings Va hw.bceX.tx_rings
 243 For BCM5709 and BCM5716,
 244 if MSI-X is used,
 245 this tunable specifies the number of transmission queues to be enabled.
 246 Maximum allowed value for these tunables is 8,
 247 and it must be less than or equal to the number of reception queues enabled.
 248 Setting these tunables to 0 allows the driver to enable as many transmission queues
 249 as allowed by the number of CPUs and number reception queues enabled.
 250 .It Va hw.bce.tx_wreg
 251 The number of transmission descriptors should be setup before the hardware
 252 register is written.
 253 Setting this value too high will have negative effect
 254 on transmission timeliness.
 255 Setting this value too low will hurt overall transmission due to the frequent
 256 hardware register writing.
 257 Default value is 8.
 258 .El
 259 .Sh MIB Variables
 260 A number of per-interface variables are implemented in the
 261 .Va dev.bce. Ns Em X
 262 branch of the
 263 .Xr sysctl 3
 264 MIB.
 265 .Bl -tag -width "tx_ticks_int"
 266 .It Va tx_bds_int
 267 See the tunable
 268 .Va hw.bce.tx_bds_int .
 269 .It Va tx_bds
 270 See the tunable
 271 .Va hw.bce.tx_bds .
 272 .It Va tx_ticks_int
 273 See the tunable
 274 .Va hw.bce.tx_ticks_int .
 275 .It Va tx_ticks
 276 See the tunable
 277 .Va hw.bce.tx_ticks .
 278 .It Va rx_bds_int
 279 See the tunable
 280 .Va hw.bce.rx_bds_int .
 281 .It Va rx_bds
 282 See the tunable
 283 .Va hw.bce_rx_bds .
 284 .It Va rx_ticks_int
 285 See the tunable
 286 .Va hw.bce.rx_ticks_int .
 287 .It Va rx_ticks
 288 See the tunable
 289 .Va hw.bce.rx_ticks .
 290 .It Va rx_rings
 291 Number of reception queues actually enabled (read-only).
 292 For BCM5709 and BCM5716,
 293 if MSI-X is enabled,
 294 the enabled reception queues will be one more than the
 295 value specified in the tunable
 296 .Va hw.bce.rx_rings
 297 or
 298 .Va hw.bceX.rx_rings .
 299 The extra reception queue is for the packets whose RSS hash
 300 could not be calculated by the hardware.
 301 .It Va tx_rings
 302 Number of transmission queues enable (read-only).
 303 For BCM5709 and BCM5716,
 304 if MSI-X is enabled,
 305 use the tunable
 306 .Va hw.bce.tx_rings
 307 or
 308 .Va hw.bceX.tx_rings
 309 to configure it.
 310 .It Va rx_pages
 311 Number of reception descriptor pages enabled (read-only).
 312 Use the tunable
 313 .Va hw.bce.rx_pages
 314 or
 315 .Va hw.bceX.rx_pages
 316 to configure it.
 317 .It Va tx_pages
 318 Number of transmission descriptor pages enabled (read-only).
 319 Use the tunable
 320 .Va hw.bce.tx_pages
 321 or
 322 .Va hw.bceX.tx_pages
 323 to configure it.
 324 .It Va tx_wreg
 325 See the tunable
 326 .Va hw.bce.tx_wreg .
 327 .It Va stat_*
 328 Various hardware statistics.
 329 .El
 330 .Sh SEE ALSO
 331 .Xr altq 4 ,
 332 .Xr arp 4 ,
 333 .Xr ifmedia 4 ,
 334 .Xr miibus 4 ,
 335 .Xr netintro 4 ,
 336 .Xr ng_ether 4 ,
 337 .Xr polling 4 ,
 338 .Xr vlan 4 ,
 339 .Xr ifconfig 8
 340 .Sh HISTORY
 341 The
 342 .Nm
 343 device driver first appeared in
 344 .Fx 6.1 .
 345 .Sh AUTHORS
 346 The
 347 .Nm
 348 driver was written by
 349 .An David Christensen Aq Mt davidch@broadcom.com .
 350 .An Sepherosa Ziehau
 351 added receive side scaling,
 352 multiple transmission queues
 353 and multiple vector MSI-X support to
 354 .Dx .