share/man/man4/bxe.4

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