share/man/man4/bxe.4

   1 .\" Copyright (c) 2013 Broadcom Corporation. All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\"
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of Broadcom Corporation nor the name of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written consent.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS'
  17 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
  20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  26 .\" THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd April 29, 2012
  31 .Dt BXE 4
  32 .Os
  33 .Sh NAME
  34 .Nm bxe
  35 .Nd Broadcom NetXtreme II Ethernet 10Gb PCIe adapter driver
  36 .Sh SYNOPSIS
  37 To compile this driver into the kernel,
  38 place the following lines in your
  39 kernel configuration file:
  40 .Bd -ragged -offset indent
  41 .Cd "device bxe"
  42 .Ed
  43 .Pp
  44 Alternatively, to load the driver as a module at boot time, place the
  45 following line in
  46 .Xr loader.conf 5 :
  47 .Bd -literal -offset indent
  48 if_bxe_load="YES"
  49 .Ed
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 driver provides support for PCIe 10Gb Ethernet adapters based on the Broadcom
  54 NetXtreme II family of 10Gb chips.
  55 The driver supports Jumbo Frames, VLAN
  56 tagging, checksum offload (IPv4, TCP, UDP, IPv6-TCP, IPv6-UDP), MSI-X
  57 interrupts, TCP Segmentation Offload (TSO), Large Receive Offload (LRO), and
  58 Receive Side Scaling (RSS).
  59 .Sh HARDWARE
  60 The
  61 .Nm
  62 driver provides support for various NICs based on the Broadcom NetXtreme II
  63 family of 10Gb Ethernet controller chips, including the following:
  64 .Pp
  65 .Bl -bullet -compact
  66 .It
  67 Broadcom NetXtreme II BCM57710 10Gb
  68 .It
  69 Broadcom NetXtreme II BCM57711 10Gb
  70 .It
  71 Broadcom NetXtreme II BCM57711E 10Gb
  72 .It
  73 Broadcom NetXtreme II BCM57712 10Gb
  74 .It
  75 Broadcom NetXtreme II BCM57712-MF 10Gb
  76 .It
  77 Broadcom NetXtreme II BCM57800 10Gb
  78 .It
  79 Broadcom NetXtreme II BCM57800-MF 10Gb
  80 .It
  81 Broadcom NetXtreme II BCM57810 10Gb
  82 .It
  83 Broadcom NetXtreme II BCM57810-MF 10Gb
  84 .It
  85 Broadcom NetXtreme II BCM57840 10Gb / 20Gb
  86 .It
  87 Broadcom NetXtreme II BCM57840-MF 10Gb
  88 .El
  89 .Sh CONFIGURATION
  90 There a number of configuration parameters that can be set to tweak the
  91 driver's behavior.
  92 These parameters can be set via the
  93 .Xr loader.conf 5
  94 file to take affect during the next system boot.
  95 The following parameters affect
  96 ALL instances of the driver.
  97 .Bl -tag -width indent
  98 .It Va hw.bxe.debug
  99 DEFAULT = 0
 100 .br
 101 Sets the default logging level of the driver.
 102 See the Diagnostics and Debugging
 103 section below for more details.
 104 .It Va hw.bxe.interrupt_mode
 105 DEFAULT = 2
 106 .br
 107 Sets the default interrupt mode: 0=IRQ, 1=MSI, 2=MSIX.
 108 If set to MSIX and
 109 allocation fails, the driver will roll back and attempt MSI allocation.
 110 If MSI
 111 allocation fails, the driver will roll back and attempt fixed level IRQ
 112 allocation.
 113 If IRQ allocation fails, then the driver load fails.
 114 With MSI/MSIX,
 115 the driver attempts to allocate a vector for each queue in addition to one more
 116 for default processing.
 117 .It Va hw.bxe.queue_count
 118 DEFAULT = 4
 119 .br
 120 Sets the default number of fast path packet processing queues.
 121 Note that one
 122 MSI/MSIX interrupt vector is allocated per-queue.
 123 .It Va hw.bxe.max_rx_bufs
 124 DEFAULT = 0
 125 .br
 126 Sets the maximum number of receive buffers to allocate per-queue.
 127 Zero(0) means
 128 to allocate a receive buffer for every buffer descriptor.
 129 By default this
 130 equates to 4080 buffers per-queue which is the maximum value for this config
 131 parameter.
 132 .It Va hw.bxe.hc_rx_ticks
 133 DEFAULT = 25
 134 .br
 135 Sets the number of ticks for host interrupt coalescing in the receive path.
 136 .It Va hw.bxe.hc_tx_ticks
 137 DEFAULT = 50
 138 .br
 139 Sets the number of ticks for host interrupt coalescing in the transmit path.
 140 .It Va hw.bxe.rx_budget
 141 DEFAULT = 0xffffffff
 142 .br
 143 Sets the maximum number of receive packets to process in an interrupt.
 144 If the
 145 budget is reached then the remaining/pending packets will be processed in a
 146 scheduled taskqueue.
 147 .It Va hw.bxe.max_aggregation_size
 148 DEFAULT = 32768
 149 .br
 150 Sets the maximum LRO aggregration byte size.
 151 The higher the value the more
 152 packets the hardware will aggregate.
 153 Maximum is 65K.
 154 .It Va hw.bxe.mrrs
 155 DEFAULT = -1
 156 .br
 157 Sets the PCI MRRS: -1=Auto, 0=128B, 1=256B, 2=512B, 3=1KB
 158 .It Va hw.bxe.autogreeen
 159 DEFAULT = 0
 160 .br
 161 Set AutoGrEEEN: 0=HW_DEFAULT, 1=FORCE_ON, 2=FORCE_OFF
 162 .It Va hw.bxe.udp_rss
 163 DEFAULT = 0
 164 .br
 165 Enable/Disable 4-tuple RSS for UDP: 0=DISABLED, 1=ENABLED
 166 .El
 167 .Pp
 168 Special care must be taken when modifying the number of queues and receive
 169 buffers.
 170 FreeBSD imposes a limit on the maximum number of
 171 .Xr mbuf 9
 172 allocations.
 173 If buffer allocations fail, the interface initialization will fail
 174 and the interface will not be usable.
 175 The driver does not make a best effort
 176 for buffer allocations.
 177 It is an all or nothing effort.
 178 .Pp
 179 You can tweak the
 180 .Xr mbuf 9
 181 allocation limit using
 182 .Xr sysctl 8
 183 and view the current usage with
 184 .Xr netstat 1
 185 as follows:
 186 .Bd -literal -offset indent
 187 # netstat -m
 188 # sysctl kern.ipc.nmbclusters
 189 # sysctl kern.ipc.nmbclusters=<#>
 190 .Ed
 191 .Pp
 192 There are additional configuration parameters that can be set on a per-instance
 193 basis to dynamically override the default configuration.
 194 The '#' below must be
 195 replaced with the driver instance / interface unit number:
 196 .Bl -tag -width indent
 197 .It Va dev.bxe.#.debug
 198 DEFAULT = 0
 199 .br
 200 Sets the default logging level of the driver instance.
 201 See
 202 .Va hw.bxe.debug
 203 above and
 204 the Diagnostics and Debugging section below for more details.
 205 .It Va dev.bxe.#.rx_budget
 206 DEFAULT = 0xffffffff
 207 .br
 208 Sets the maximum number of receive packets to process in an interrupt for the
 209 driver instance.
 210 See
 211 .Va hw.bxe.rx_budget
 212 above for more details.
 213 .El
 214 .Pp
 215 Additional items can be configured using
 216 .Xr ifconfig 8 :
 217 .Bl -tag -width indent
 218 .It Va MTU - Maximum Transmission Unit
 219 DEFAULT = 1500
 220 .br
 221 RANGE = 46-9184
 222 .br
 223 # ifconfig bxe# mtu <n>
 224 .It Va Promiscuous Mode
 225 DEFAULT = OFF
 226 .br
 227 # ifconfig bxe# [ promisc | -promisc ]
 228 .It Va Rx/Tx Checksum Offload
 229 DEFAULT = RX/TX CSUM ON
 230 .br
 231 Note that the Rx and Tx settings are not independent.
 232 .br
 233 # ifconfig bxe# [ rxcsum | -rxcsum | txcsum | -txcsum ]
 234 .It Va TSO - TCP Segmentation Offload
 235 DEFAULT = ON
 236 .br
 237 # ifconfig bxe# [ tso | -tso | tso6 | -tso6 ]
 238 .It Va LRO - TCP Large Receive Offload
 239 DEFAULT = ON
 240 .br
 241 # ifconfig bxe# [ lro | -lro ]
 242 .El
 243 .Sh DIAGNOSTICS AND DEBUGGING
 244 There are many statistics exposed by
 245 .Nm
 246 via
 247 .Xr sysctl 8 .
 248 .Pp
 249 To dump the default driver configuration:
 250 .Bd -literal -offset indent
 251 # sysctl -a | grep hw.bxe
 252 .Ed
 253 .Pp
 254 To dump every instance's configuration and detailed statistics:
 255 .Bd -literal -offset indent
 256 # sysctl -a | grep dev.bxe
 257 .Ed
 258 .Pp
 259 To dump information for a single instance (replace the '#' with the driver
 260 instance / interface unit number):
 261 .Bd -literal -offset indent
 262 # sysctl -a | grep dev.bxe.#
 263 .Ed
 264 .Pp
 265 To dump information for all the queues of a single instance:
 266 .Bd -literal -offset indent
 267 # sysctl -a | grep dev.bxe.#.queue
 268 .Ed
 269 .Pp
 270 To dump information for a single queue of a single instance (replace the
 271 additional '#' with the queue number):
 272 .Bd -literal -offset indent
 273 # sysctl -a | grep dev.bxe.#.queue.#
 274 .Ed
 275 .Pp
 276 The
 277 .Nm
 278 driver has the ability to dump a ton of debug messages to the system
 279 log.
 280 The default level of logging can be set with the
 281 .Va hw.bxe.debug
 282 .Xr sysctl 8 .
 283 Take care with this setting as it can result in too
 284 many logs being dumped.
 285 Since this parameter is the default one, it affects
 286 every instance and will dramatically change the timing in the driver.
 287 A better
 288 alternative to aid in debugging is to dynamically change the debug level of a
 289 specific instance with the
 290 .Va dev.bxe.#.debug
 291 .Xr sysctl 8 .
 292 This allows
 293 you to turn on/off logging of various debug groups on-the-fly.
 294 .Pp
 295 The different debug groups that can be toggled are:
 296 .Bd -literal -offset indent
 297 DBG_LOAD   0x00000001 /* load and unload    */
 298 DBG_INTR   0x00000002 /* interrupt handling */
 299 DBG_SP     0x00000004 /* slowpath handling  */
 300 DBG_STATS  0x00000008 /* stats updates      */
 301 DBG_TX     0x00000010 /* packet transmit    */
 302 DBG_RX     0x00000020 /* packet receive     */
 303 DBG_PHY    0x00000040 /* phy/link handling  */
 304 DBG_IOCTL  0x00000080 /* ioctl handling     */
 305 DBG_MBUF   0x00000100 /* dumping mbuf info  */
 306 DBG_REGS   0x00000200 /* register access    */
 307 DBG_LRO    0x00000400 /* lro processing     */
 308 DBG_ASSERT 0x80000000 /* debug assert       */
 309 DBG_ALL    0xFFFFFFFF /* flying monkeys     */
 310 .Ed
 311 .Pp
 312 For example, to debug an issue in the receive path on bxe0:
 313 .Bd -literal -offset indent
 314 # sysctl dev.bxe.0.debug=0x22
 315 .Ed
 316 .Pp
 317 When finished turn the logging back off:
 318 .Bd -literal -offset indent
 319 # sysctl dev.bxe.0.debug=0
 320 .Ed
 321 .Sh SEE ALSO
 322 .Xr netstat 1 ,
 323 .Xr altq 4 ,
 324 .Xr arp 4 ,
 325 .Xr netintro 4 ,
 326 .Xr ng_ether 4 ,
 327 .Xr vlan 4 ,
 328 .Xr ifconfig 8
 329 .Sh HISTORY
 330 The
 331 .Nm
 332 device driver first appeared in
 333 .Fx 9.0 .
 334 .Sh AUTHORS
 335 The
 336 .Nm
 337 driver was written by
 338 .An Eric Davis Aq edavis@broadcom.com ,
 339 .An David Christensen Aq davidch@broadcom.com ,
 340 and
 341 .An Gary Zambrano Aq zambrano@broadcom.com .