drivers/net/bcm5700/README.TXT

   1
   2                            Installation Notes
   3                        Broadcom BCM5700 Linux Driver
   4                               Version 8.3.17c
   5                                 03/10/2006
   6
   7                           Broadcom Corporation
   8                           16215 Alton Parkway,
   9                           Irvine, CA 92619-7013
  10
  11                 Copyright (c) 2000-2006 Broadcom Corporation
  12                            All rights reserved
  13
  14
  15 Table of Contents
  16 =================
  17
  18   Introduction
  19   Limitations
  20   Packaging
  21   Installing Source RPM Package
  22   Building Driver From TAR File
  23   Patching Driver Into Kernel
  24   Unloading and Removing Driver
  25   Module Parameters
  26   Driver Messages
  27   Statistics
  28
  29
  30 Introduction
  31 ============
  32
  33 This file describes the Linux driver for the Broadcom NetXtreme BCM5700
  34 series 10/100/1000 Mbps PCI/PCI-X/PCI Express Ethernet Network Controllers.
  35
  36
  37 Limitations
  38 ===========
  39
  40 The current version of the driver has been tested on the latest Red Hat, SuSE,
  41 and other Linux distributions for i386, ia64, and x86_64 CPU architectures
  42 using 2.4.x and 2.6.x kernels. The driver has been tested up to kernel
  43 version 2.4.31 and 2.6.13.
  44
  45 The driver should work on other little endian or big endian CPU architectures,
  46 but only very limited testing has been done on some of these machines. The
  47 Makefile may have to be modified to include architecture specific compile
  48 switches, and some minor changes in the source files may also be required.
  49 On these machines, patching the driver into the kernel is recommended (see
  50 below for instructions).
  51
  52
  53 Packaging
  54 =========
  55
  56 The driver is released in two packaging formats: source RPM and compressed tar
  57 formats. The file names for the two packages are bcm5700-<version>.src.rpm and
  58 bcm5700-<version>.tar.gz respectively. Identical source files to build the
  59 driver are included in both packages. bcm_sup-<version> is a seperate tar file
  60 that contains additional utilities such as patches and driver diskette images
  61 for network installation.
  62
  63
  64 Installing Source RPM Package
  65 =============================
  66
  67 The following are general guidelines for installing the driver. Refer to
  68 DISTRIB.TXT for additional installation notes for various Linux distributions.
  69
  70 1. Install the source RPM package:
  71
  72    rpm -ivh bcm5700-<version>.src.rpm
  73
  74 2. CD to the RPM path and build the binary driver for your kernel:
  75
  76    cd /usr/src/{redhat,OpenLinux,turbo,packages,rpm ..}
  77
  78    rpm -bb SPECS/bcm5700.spec
  79
  80 or
  81
  82    rpmbuild -bb SPECS/bcm5700.spec (for RPM version 4.x.x)
  83
  84 Note that the RPM path is different for different Linux distributions.
  85
  86 3. Install the newly built package (driver and man page):
  87
  88    rpm -ivh RPMS/i386/bcm5700-<version>.i386.rpm
  89
  90 Note that the --force option is needed if installing on Red Hat 7.2, 7.3,
  91 2.1AS and others that already contain an older version of the driver.
  92
  93 The driver will be installed in the following path:
  94
  95 2.2.x kernels:
  96
  97     /lib/modules/<kernel_version>/net/bcm5700.o
  98
  99 2.4.x kernels:
 100
 101     /lib/modules/<kernel_version>/kernel/drivers/net/bcm5700.o
 102
 103 2.4.x kernels with bcm5700 as an addon driver (e.g. Red Hat 7.3, 2.1AS):
 104
 105     /lib/modules/<kernel_version>/kernel/drivers/net/bcm/bcm5700.o
 106
 107 or
 108
 109     /lib/modules/<kernel_version>/kernel/drivers/addon/bcm5700/bcm5700.o
 110
 111 2.6.x kernels:
 112
 113     /lib/modules/<kernel_version>/kernel/drivers/net/bcm5700.ko
 114
 115 2.6.x kernels with bcm5700 as an addon driver (e.g. SuSE 9 SLES):
 116
 117     /lib/modules/<kernel_version>/kernel/drivers/net/bcm/bcm5700.ko
 118
 119 4. Load the driver:
 120
 121    modprobe bcm5700
 122
 123 If loading the driver on Red Hat 3 update 4, 2.1 AS or other newer kernels with the
 124 tg3 driver, refer to the "Removing tg3 Driver" in DISTRIB.TXT before loading
 125 the driver.
 126
 127 5. To configure network protocol and address, refer to various Linux
 128 documentations.
 129
 130
 131 Building Driver From TAR File
 132 =============================
 133
 134 The following are general guidelines for installing the driver. Refer to
 135 DISTRIB.TXT for additional installation notes for various Linux distributions.
 136
 137 1. Create a directory and extract the files:
 138
 139    tar xvzf bcm5700-<version>.tar.gz
 140
 141 2. Build the driver bcm5700.o as a loadable module for the running kernel:
 142
 143    cd src
 144    make
 145
 146 3. Test the driver by loading it:
 147
 148    insmod bcm5700.o
 149 or
 150    insmod bcm5700.ko (on 2.6.x kernels)
 151
 152 If loading the driver on Red Hat 3 update 4, 2.1 AS or other newer kernels with the
 153 tg3 driver, refer to the "Removing tg3 Driver" in DISTRIB.TXT before loading
 154 the driver.
 155
 156 4. Install the driver and man page:
 157
 158    make install
 159
 160 See RPM instructions above for the location of the installed driver.
 161
 162 5. To configure network protocol and address, refer to various Linux
 163 documentations.
 164
 165
 166 Patching Driver Into Kernel (Optional)
 167 ======================================
 168
 169 Patch files are included for patching the driver into some of the latest
 170 2.4.x and 2.6.x kernel source trees. This step is optional and can be done
 171 by users familiar with configuring and building the kernel. The patch
 172 will modify the orginal kernel's source code.
 173
 174 The following steps may allow you to patch the driver into a kernel:
 175
 176 1. Select the patch file that matches your kernel and apply the patch:
 177
 178    patch -p1 -d <kernel_src_root> < bcm5700-<version>-2.4.<x>.patch
 179    patch -p1 -d <kernel_src_root> < bcm5700-<version>-2.6.<x>.patch
 180
 181 where <version> is the version of the bcm5700 driver and 2.4.<x> is the
 182 version of the kernel to patch (e.g. 2.4.31).
 183
 184 Note: <kernel_src_root> is usually /usr/src/linux or /usr/src/linux-2.4.<x>
 185 Note: <kernel_src_root> is usually /usr/src/linux or /usr/src/linux-2.6.<x>
 186
 187 2. Configure the kernel to include the bcm5700 driver. It can be found
 188 under Network Device Support ---> Ethernet (1000 Mbit) ---> Broadcom BCM5700
 189 support when make menuconfig is run. Select built-in or module for the driver:
 190
 191    cd <kernel_src_root>
 192    make menuconfig
 193
 194 3. Compile the kernel:
 195
 196    make dep
 197    make clean
 198    ....
 199    ....
 200
 201
 202 Unloading and Removing Driver
 203 =============================
 204
 205 To unload the driver, use ifconfig to bring down all eth# interfaces opened
 206 by the driver, then do the following:
 207
 208 rmmod bcm5700
 209
 210
 211 If the driver was installed using rpm, do the following to remove it:
 212
 213 rpm -e bcm5700
 214
 215
 216 If the driver was installed using make install from the tar file, the driver
 217 bcm5700.o has to be manually deleted from the system. Refer to the section
 218 "Installing Source RPM Package" for the location of the installed driver.
 219
 220
 221 Module Parameters
 222 =================
 223
 224 Optional parameters for the driver can be supplied as command line arguments
 225 to the insmod command. Typically, these parameters are set in the file
 226 /etc/modules.conf (see the man page for modules.conf). These parameters take
 227 the form
 228
 229     <parameter>=value[,value,...]
 230
 231 where the multiple values for the same parameter are for multiple NICs
 232 installed in the system.
 233
 234 Note that default or other meaningful values will be used when invalid values
 235 are selected. Some combinations of parameter values may conflict and lead to
 236 failures. The driver cannot detect all such conflicting combinations.
 237
 238 All the parameters are listed below.
 239
 240 line_speed
 241
 242     Selects the line speed of the link. This parameter is used together with
 243     full_duplex and auto_speed to select the speed and duplexity of the link
 244     and the setting of autonegotiation.
 245
 246     The valid values are:
 247
 248     0      Autonegotiate for highest speed supported by link partner (default)
 249     10     10 Mbps
 250     100    100 Mbps
 251     1000   1000 Mbps
 252
 253     If line_speed is set to 10, 100, or 1000, the NIC will autonegotiate for
 254     the selected speed (and selected duplexity) if auto_speed is set to 1.
 255     If auto_speed is set to 0, the selected speed and duplexity will be
 256     set without autonegotiation. Note that 1000 Mbps must be negotiated for
 257     copper twisted pair links.
 258
 259 auto_speed
 260
 261     Enables or disables autonegotiation. The valid values are:
 262
 263     0      Autonegotiation disabled
 264     1      Autonegotiation enabled (default)
 265
 266     Note that this parameter is ignored and assumed 1 if line_speed is set
 267     to 0.
 268
 269 full_duplex
 270
 271     Selects the duplexity of the link. This paramter is used together with
 272     line_speed to select the speed and duplexity of the link. Note that this
 273     parameter is ignored if line_speed is 0.
 274
 275     The valid values are:
 276
 277     0      half duplex
 278     1      full duplex (default)
 279
 280
 281 rx_flow_control
 282
 283     Enables or disables receiving flow control (pause) frames. This parameter
 284     is used together with auto_flow_control. The valid values are:
 285
 286     0      pause receive disabled
 287     1      pause receive enabled if auto_flow_control is set to 0, or
 288            pause receive advertised if auto_flow_control is set to 1 (default)
 289
 290 tx_flow_control
 291
 292     Enables or disables transmitting flow control (pause) frames. This parameter
 293     is used together with auto_flow_control. The valid values are:
 294
 295     0      pause transmit disabled
 296     1      pause transmit enabled if auto_flow_control is set to 0, or
 297            pause transmit advertised if auto_flow_control is set to 1 (default)
 298
 299 auto_flow_control
 300
 301     Enables or disables autonegotiation of flow control. This parameter is used
 302     together with rx_flow_control and tx_flow_control to determine the
 303     advertised flow control capability. The valid values are:
 304
 305     0      flow control autonegotiation disabled
 306     1      flow control autonegotiation enabled with capability specified in
 307            rx_flow_control and tx_flow_control (only valid if line_speed is
 308            set to 0 or auto_speed is set to 1) (default)
 309
 310 mtu
 311
 312     Enables jumbo frames up to the specified MTU size. The valid range for
 313     this parameter is 1500 to 9000. Default is 1500 which is standard
 314     ethernet (non-jumbo) MTU size. Note that the MTU size excludes the
 315     ethernet header size of 14 bytes. Actual frame size is MTU size + 14 bytes.
 316     Jumbo MTU sizes are not supported on BCM5705 chips.
 317
 318     The MTU size can also be changed using ifconfig after the driver is loaded.
 319     See the ifconfig man page for details.
 320
 321 tx_checksum
 322
 323     Enables or disables hardware transmit TCP/UDP checksum. The valid values
 324     are:
 325
 326     0      checksum disabled
 327     1      checksum enabled (default)
 328
 329 rx_checksum
 330
 331     Enables or disables hardware receive TCP/UDP checksum validation. The
 332     valid values are:
 333
 334     0      checksum disabled
 335     1      checksum enabled (default)
 336
 337 scatter_gather
 338
 339     Enables or disables scatter-gather and 64-bit DMA on x86. This option is
 340     only useful when running on TUX-enabled kernels or newer kernels with
 341     zero-copy TCP. The valid values are:
 342
 343     0      scatter-gather and 64-bit DMA on x86 disabled
 344     1      scatter-gather and 64-bit DMA on x86 enabled (default)
 345
 346 nic_tx_bd
 347
 348     Enables either NIC based or host based transmit buffer descriptors (Tx BDs).
 349     NIC based Tx BDs may be slightly faster on certain machines on earlier
 350     2.4 kernels where each transmit packet is usually entirely contiguous. On
 351     later kernels with scatter-gather and TCP segmentation option, host based
 352     Tx BDs using DMA transfer are usually faster. NIC based Tx BDs are not
 353     supported on 5705 and later family controllers. The valid values are:
 354
 355     0      NIC based transmit buffer descriptors disabled (using host based
 356            transmit buffer descriptors) (default)
 357     1      NIC based transmit buffer descriptors enabled (not supported
 358            on 5705 family controllers)
 359
 360 tx_pkt_desc_cnt
 361
 362     Configures the number of transmit descriptors. Default is 120. The
 363     valid range is from 1 to 511. Note that the driver may not be able to
 364     allocate the required amount of memory if this parameter is set too high.
 365     Depending on kernel and CPU architecture, each descriptor may require up
 366     to about 268 bytes. This parameter should not be set less than 80 if
 367     adaptive_coalesce (see below) is enabled.
 368
 369 rx_std_desc_cnt
 370
 371     Configures the number of receive descriptors for frames up to 1528 bytes.
 372     Default is 200. The valid range is from 1 to 511. This parameter should
 373     not be set less than 80 on systems with high network traffic. Setting this
 374     parameter higher allows the NIC to buffer larger bursts of network
 375     traffic without dropping frames, especially on slower systems. Note that
 376     the driver may not be able to allocate the required amount of memory if
 377     this parameter is set too high. Depending on kernel and CPU architecture,
 378     each descriptor may require up to about 268 bytes. Each descriptor also
 379     requires a socket buffer of at least 1536 bytes. This parameter should not
 380     be set less than 50 if adaptive_coalesce (see below) is enabled.
 381
 382 rx_jumbo_desc_cnt
 383
 384     Configures the number of receive descriptors for jumbo frames larger
 385     than 1528 bytes. Default is 128 and valid range is from 1 to 255.
 386     When jumbo frames larger than 1528 bytes are used, this parameter should
 387     not be set lower than 60 on systems with high network traffic. Setting
 388     this parameter higher allows the NIC to buffer larger bursts of jumbo
 389     traffic without dropping frames, especially on slower systems. Depending
 390     on kernel and CPU architecture, each descriptor may require up to about
 391     268 bytes. Each descriptor also requires a socket buffer the size of a
 392     maximum jumbo frame. On systems with insufficient memory, it may be
 393     necessary to reduce this parameter. This parameter should not be set less
 394     than 50 if adaptive_coalesce (see below) is enabled. When the maximum
 395     frame size is 1528 or smaller (MTU size 1514 or smaller), this parameter
 396     is not used and is always 0.
 397
 398 adaptive_coalesce
 399
 400     Enables or disables adaptive adjustments to the various interrupt
 401     coalescing parameters. Enabling it allows the driver to dynamically
 402     adjust the interrupt coalescing parameters to achieve high throughput
 403     during heavy traffic and low latency during light traffic.
 404     rx_std_desc_cnt, (and rx_jumbo_desc_cnt if using jumbo frames) should not
 405     be set less than 50, and tx_pkt_desc_cnt should not be set less than 80
 406     when this parameter is enabled. Note that if the kernel supports the NAPI
 407     receive polling mode, interrupt coalescing will be handled in a different
 408     way and this parameter will not be used. The valid values are:
 409
 410     0      disabled (always disabled in NAPI mode)
 411     1      enabled (default)
 412
 413 rx_coalesce_ticks
 414
 415     Configures the number of 1 usec ticks before the NIC generates receive
 416     interrupt after receiving a frame. This parameter works in conjunction
 417     with the rx_max_coalesce_frames parameter. Interrupt will be generated
 418     when either of these thresholds is exceeded. 0 means this parameter is
 419     ignored and interrupt will be generated when the rx_max_coalesce_frames
 420     threshold is reached. The valid range is from 0 to 500, and default is
 421     60 (18 if using NAPI mode). This parameter is not used and will be
 422     adjusted automatically if adaptive_coalesce is set to 1.
 423
 424 rx_max_coalesce_frames
 425
 426     Configures the number of received frames before the NIC generates receive
 427     interrupt. The valid range is from 0 to 100, and default is 15 (6 if using
 428     NAPI mode). This parameter and rx_coalesce_ticks cannot be both 0,
 429     otherwise no receive interrupts will be generated. It should also be set
 430     lower than rx_std_desc_cnt (and rx_jumbo_desc_cnt if using jumbo frames).
 431     This parameter is not used and will be adjusted automatically if
 432     adaptive_coalesce is set to 1.
 433
 434 tx_coalesce_ticks
 435
 436     Configures the number of 1 usec ticks before the NIC generates transmit
 437     interrupt after transmitting a frame. This parameter works in conjunction
 438     with the tx_max_coalesce_frames parameter. Interrupt will be generated
 439     when either of these thresholds is exceeded. 0 means this
 440     parameter is ignored and interrupt will be generated when the
 441     tx_max_coalesce_frames threshold is reached. The valid range is from 0 to
 442     500, and default is 200. This parameter is not used and will be adjusted
 443     automatically if adaptive_coalesce is set to 1.
 444
 445 tx_max_coalesce_frames
 446
 447     Configures the number of transmitted frames before the NIC generates
 448     transmit interrupt. The valid range is from 0 to 100, and default is 35.
 449     This parameter and tx_coalesce_ticks cannot be both 0, otherwise no
 450     transmit completion interrupt will be generated. This parameter should
 451     always be set lower than tx_pkt_desc_cnt. This parameter is not used and
 452     will be adjusted automatically if adaptive_coalesce is set to 1.
 453
 454 stats_coalesce_ticks
 455
 456     Configures the number of 1 usec ticks between periodic statistics updates
 457     (DMAs). The valid range is from 100 to 3600000000, and default is 1000000
 458     (1 sec.). 0 is also valid and is used to disable statistics updates.
 459     This parameter is not used and will be set to default if adaptive_coalesce
 460     is set to 1. Please note that the valid range may vary by kernel version.
 461
 462 enable_wol
 463
 464     Enables or disables magic packet Wake-On-LAN when the system is shutdown.
 465     Note that not all systems support Wake-On-LAN. The valid values are:
 466
 467     0    magic packet Wake-On-LAN disabled (default)
 468     1    magic packet Wake-On-LAN enabled
 469
 470 enable_tso
 471
 472     Enables or disables TCP Segmentation Option (TSO) when using kernels that
 473     support it. This parameter is only defined on newer kernels that support
 474     TSO. The valid values are:
 475
 476     0    TSO disabled
 477     1    TSO enabled (default)
 478
 479 disable_msi
 480
 481     Enables or disables message signal interrupts (MSI) when using kernels that
 482     support it. This parameter is only defined on newer kernels that support
 483     MSI. The valid values are:
 484
 485     1    MSI disabled
 486     0    MSI enabled (default)
 487     Note: Only applies to the latest devices.
 488
 489 vlan_tag_mode
 490
 491     This parameter controls the stripping of VLAN tags on incoming packets,
 492     and is used to allow VLAN tagged ASF or IPMI packets to be received
 493     properly. The valid values are:
 494
 495     0    Auto mode (default)
 496     1    Normal strip mode
 497     2    Forced strip mode
 498
 499     In normal mode, VLAN tags are only stripped if VLANs are registered
 500     by the 802.1q VLAN module or BASP. In forced strip mode, VLAN tags
 501     are always stripped. Auto mode will select normal strip mode if ASF/IPMI
 502     is disabled, or forced strip mode if ASF/IPMI is enabled.
 503
 504 delay_link
 505
 506     If set to 1, this parameter will cause the driver to return
 507     -EOPNOTSUPP when the SIOCGMIIREG or ETHTOOL_GLINK ioctls are called
 508     during the first 6 seconds after driver reset. When the driver resets
 509     the NIC during ifconfig, the link will drop and it may take several
 510     seconds for the link to come up after autonegotiation completes. Some
 511     applications, such as ifup, may not wait long enough for the link
 512     before giving up. Setting this parameter to 1 may get around such
 513     problems. The default value is 0, which means that the driver will
 514     always return true link states to all ioctl calls, when applicable.
 515
 516 disable_d3hot
 517
 518     If set to 1, this parameter will cause the driver to never
 519     put the device in D3Hot power state when the NIC is shutdown or
 520     suspended. If set, this parameter will also disable the Wake-On-Lan
 521     setting. A rare D3Hot related problem was seen during repeated
 522     shutdown of PCI Express devices on systems running 2.6 kernels.
 523
 524 Driver Messages
 525 ===============
 526
 527 The following are the most common sample messages that may be logged in the file
 528 /var/log/messages. Use dmesg -n <level> to control the level at which messages
 529 will appear on the console. Most systems are set to level 6 by default.
 530
 531 Broadcom Gigabit Ethernet Driver bcm5700 with Broadcom NIC Extension (NICE)
 532 ver. 8.3.17c (03/10/06)
 533
 534     Driver signon
 535
 536
 537 eth#: Broadcom BCM5704 1000Base-T found at mem faff0000, IRQ 16, node addr 0010180402d8
 538 eth#: Broadcom BCM5704 Integrated Copper transceiver found
 539 eth#: Scatter-gather ON, 64-bit DMA ON, Tx Checksum ON, Rx Checksum ON, 802.1Q VLAN ON, TSO ON, NAPI ON
 540
 541     NIC detected
 542
 543
 544 bcm5700: eth# NIC Link is Up, 1000 Mbps full duplex, receive and transmit flow control ON
 545
 546     Link up and speed indication
 547
 548
 549 bcm5700: eth# NIC Link is Down
 550
 551     Link down indication
 552
 553 bcm5700: eth# Using Message Signaled Interrupt (MSI)
 554
 555     The driver is in MSI mode
 556
 557 bcm5700: eth# Using PCI INTX interrupt
 558
 559     The driver is in IRQ mode
 560
 561 Statistics
 562 ==========
 563
 564 Detailed statistics and configuration information can be viewed in the file
 565 /proc/net/nicinfo/eth#.info.
 566