Back to Contents

# Linux Driver Software: Broadcom NetXtreme™ 57XX User Guide

This document describes the installation and configuration of the Linux driver software for the Broadcom NetLink™ Gigabit Ethernet Controller and includes the following sections:

Linux Driver Software

# Linux Driver Software

Introduction
Limitations
Packaging
Installing Linux Driver Software
Patching PCI Files
Patching Driver Into Kernel
Network Installation
Removing Linux Driver
Module Parameters
Driver Messages
Statistics

## Introduction

This section describes the Linux driver for the Broadcom NetLink BCM5700 series 10/100/1000 Mbps Ethernet Network Controllers.

## Limitations

The current version of the Linux driver has been tested on the latest Red Hat and United Linux distributions, as well as other similar Linux distributions for i386, ia64, and x86_64 CPU architecture using 2.4.x kernels. The driver has been tested up to kernel version 2.4.20.

| NOTE: It is possible to have Turbo Teaming enabled on the BCM5704 card, but this feature is not supported in Linux.

Back to Top

## Packaging

The Linux driver is released in two packaging formats: source RPM and compressed tar formats. The file names for the two packages are bcm5700-<version>.src.rpm and bcm5700-<version>.tar.gz. Identical source files to build the driver are included in both RPM and TAR source packages. The tar file contains additional utilities such as patches and driver diskette images for network installation.

Back to Top

## Installing Linux Driver Software

The section describes the following Linux driver installations:

- Installing Source RPM Package
- Building Driver from a TAR file
- Removing the tg3 Driver

| NOTE: On newer Distributions and Kernels, it may be necessary to remove the tg3 driver before loading the Broadcom BCM5700 driver. Follow the instructions in the “Removing the tg3 Driver” section.

### Installing Source RPM Package

1. Install the source RPM package:

   rpm -ivh bcm5700-<version>.src.rpm

2. Change the directory to the RPM path and build the binary driver for your kernel:

   cd /usr/src/{redhat,OpenLinux,turbo,packages,rpm ..}
   rpm -bb SPECS/bcm5700.spec or rpmbuild -bb SPECS/bcm5700.spec

   Note that the RPM path is different for different Linux distributions.

3. Install the newly built package (driver and man page):

   rpm -ivh RPMS/i386/bcm5700-<version>.i386.rpm

   Note that the --force option is needed if installing on some distributions that may already contain an older version of the driver.

   The driver will be installed in one of the following paths:

   - 2.2.x kernels:

   > /lib/modules/<kernel_version>/net/bcm5700.o

- 2.4.x kernels:

> /lib/modules/<kernel_version>/kernel/drivers/net/bcm5700.o

- 2.4.x kernels with BCM5700 driver patched in:

> /lib/modules/<kernel_version>/kernel/drivers/net/bcm/bcm5700.o

> or

> /lib/modules/<kernel_version>/kernel/drivers/addon/bcm5700/bcm5700.o

4. Load the driver:

   insmod bcm5700

5. To configure the network protocol and address, refer to Linux-specific documentation.

### Building Driver From TAR File

1. Create a directory and extract the TAR files:

> tar xvzf bcm5700-<version>.tar.gz

1. Build the driver bcm5700.o as a loadable module for the running kernel:

   cd src
   make

2. Test the driver by loading it:

   insmod bcm5700.o

3. Install the driver and man page:

   make install

   | NOTE: See the RPM instructions above for the location of the installed driver.

4. To configure network protocol and address, refer to the manuals supplied with your operating system.

### Removing the tg3 Driver

If loading the BCM5700 driver on more recent Red Hat distributions and other new kernels and patches, it may be necessary to unload the tg3 driver first if it is loaded. While tg3 is a fully functioning driver written by Red Hat et al, Broadcom recommends users to use the BCM5700 driver written and tested by Broadcom. Use ifconfig to bring down all eth# interfaces used by tg3 and do the following to unload the tg3 driver.

> rmmod tg3

It may also be necessary to manually edit the file /etc/modules.conf to change the interface alias name from tg3 to bcm5700. Example:

> alias eth0 tg3

Replace tg3 with bcm5700

> alias eth0 bcm5700

For more detailed Linux specific information on ifconfig, rmmod, or modules.conf, please see the respective man pages.

Back to Top

## Patching PCI Files (Optional)

To use the Red Hat kudzu hardware detection utility, a number of files containing PCI vendor and device information need to be patched with information on the BCM570x series NICs. The most recent Red Hat distributions are included. Apply the appropriate patch by running the patch command. For example, on Red Hat 8.0 for i386, apply the patch by doing the following:

> > patch -N -p1 -d /usr < pci-rh80-i386.patch

> Run kudzu:

> > kudzu

Back to Top

## Patching Driver Into Kernel (Optional)

Patch files are included for patching the driver into some of the latest 2.4.x kernel source trees. This step is optional and should only be done by users familiar with configuring and building the kernel. The patch will modify the original kernel's source code.

Follow the following steps to patch the driver into kernel:

1. Select the patch file that matches your kernel and apply the patch:

> patch -p1 -d <kernel_src_root> < bcm5700-<version>-2.4.<x>.patch

> where <version> is the version of the BCM570x driver and 2.4.<x> is the version of the kernel to patch (e.g., 2.4.10).

> | NOTE: <kernel_src_root> is usually /usr/src/linux or /usr/src/linux-2.4.<x>

1. Configure the kernel to include the BCM570x driver. It can be found under Network Device Support > Ethernet (1000 Mbit) > Broadcom BCM5700 support when make menuconfig is run. Select built-in or module for the driver:

> cd <kernel_src_root>
> make menuconfig

2. Compile the kernel:

   > make dep
   > make clean
   > ....
   > ....

Back to Top

## Network Installation

For network installations through NFS, FTP, or HTTP (using a network boot disk or PXE), a driver diskette that contains the BCM570x driver may be needed. The driver diskette images for the most recent Red Hat versions are included. Boot drivers for other Linux versions can be compiled by modifying the Makefile and the make environment. Further information is available from Red Hat's website, http://www.redhat.com.

To create the driver diskette, select the appropriate image file and do the following:

> dd if=dd.img of=/dev/fd0H1440.

Back to Top

## Removing the Linux Driver

The section describes Removing of the following Linux drivers:

- Removing the Driver from an RPM Installation
- Removing the Driver from a TAR Installation

### Removing the Driver from an RPM Installation

To unload the driver, use ifconfig to bring down all eth# interfaces opened by the driver, then do the following:

> rmmod bcm5700

If the driver was installed using rpm, do the following to remove it:

> rpm -e bcm5700

### Removing the Driver from a TAR Installation

If the driver was installed using make install from the tar file, the driver bcm5700.o has to be manually deleted from the system. Refer to the section Installing Source RPM Package for the location of the installed driver.

Back to Top

## Module Parameters

Optional parameters for the driver can be supplied as command line arguments to the insmod command. Typically, these parameters are set in the file /etc/modules.conf (see the man page for modules.conf). These parameters take the form

> <parameter>=value[,value,...]

> where the multiple values for the same parameter are for multiple NICs installed in the system.

> | NOTE: The default or other meaningful values will be used when invalid values are selected. Some combinations of parameter values may conflict and lead to failures. The driver cannot detect all such conflicting combinations.

All the module parameters are listed below.

- line_speed

  Selects the line speed of the link. This parameter is used together with full-duplex and auto-speed to select the speed and duplex operation of the link and the setting of auto-negotiation The valid values are:

  - 0 - Autonegotiate for highest speed supported by link partner (default)
  - 10 - 10 Mbps
  - 100 - 100 Mbps
  - 1000 - 1000 Mbps

> If line-speed is set to 10, 100, or 1000, the NIC will auto-negotiate for the selected speed (and selected duplexity) if auto-speed is set to 1. If auto-speed is set to 0, the selected speed and duplexity will be set without auto-negotiation Note that 1000 Mbps must be negotiated for copper twisted pair links.

- auto-speed

  Enables or disables auto-negotiation The valid values are:

  - 0 - Auto-negotiation disabled
  - 1 - Auto-negotiation enabled (default)

> Note that this parameter is ignored and assumed 1 if line-speed is set to 0.

- full-duplex

  Selects the duplexity of the link. This parameter is used together with line-speed to select the speed and duplexity of the link. Note that this parameter is ignored if line-speed is 0. The valid values are:

  - 0 - half-duplex
  - 1 - full-duplex (default)
- rx_flow_control

  Enables or disables receiving flow control (pause) frames. This parameter is used together with auto_flow_control. The valid values are:

  - 0 - pause receive disabled
  - 1 - pause receive enabled if auto_flow_control is set to 0, or pause receive advertised if auto_flow_control is set to 1 (default)
- tx_flow_control

  Enables or disables transmitting flow control (pause) frames. This parameter is used together with auto_flow_control. The valid values are:

  - 0 - pause transmit disabled
  - 1 - pause transmit enabled if auto_flow_control is set to 0, or pause transmit advertised if auto_flow_control is set to 1 (default)
- auto_flow_control

  Enables or disables auto-negotiation of flow control. This parameter is used together with rx_flow_control and tx_flow_control to determine the advertised flow control capability. The valid values are:

  - 0 - flow control auto-negotiation disabled
  - 1 - flow control auto-negotiation enabled with capability specified in rx_flow_control and tx_flow_control (only valid if line-speed is set to 0 or auto-speed is set to 1) (default)
- mtu

  Enables jumbo frames up to the specified MTU size. The valid range for this parameter is 1500 to 9000. Default is 1500 which is standard ethernet (non-jumbo) MTU size. Note that the MTU size excludes the ethernet header size of 14 bytes. Actual frame size is MTU size + 14 bytes. Jumbo MTU sizes are not supported on BCM5705, BCM5782, and BCM5788 chips.

  The MTU size can also be changed using ifconfig after the driver is loaded. See the ifconfig man page for details.

- tx_checksum

  Enables or disables hardware transmit TCP/UDP checksum. The valid values are:

  - 0 - checksum disabled
  - 1 - checksum enabled (default)
- rx_checksum

  Enables or disables hardware receive TCP/UDP checksum validation. The valid values are:

  - 0 - checksum disabled
  - 1 - checksum enabled (default)
- scatter_gather

  Enables or disables scatter-gather and 64-bit DMA on x86. This option is only useful when running on TUX-enabled kernels or kernels with zero-copy TCP. The valid values are:

  - 0 - scatter-gather and 64-bit DMA on x86 disabled
  - 1 - scatter-gather and 64-bit DMA on x86 enabled (default)
- tx_pkt_desc_cnt

  Configures the number of transmit descriptors. Default is 100. The valid range is from 1 to 600. Depending on kernel and system architecture, the driver may require up to 268 bytes per descriptor. Note that the driver may not be able to allocate the required amount of memory if this parameter is set too high. This parameter should not be set less than 80 if daptive_coalesce (see below) is enabled.

- rx_std_desc_cnt

  Configures the number of receive descriptors for frames up to 1528 bytes. Default is 200. The valid range is from 1 to 511. This parameter should not be set less than 80 on systems with high network traffic. Setting this parameter higher allows the NIC to buffer larger bursts of network traffic without dropping frames, especially on slower systems. Note that the driver may not be able to allocate the required amount of memory if this parameter is set too high. This parameter should not be set less than 50 if adaptive_coalesce (see below) is enabled.

- rx_jumbo_desc_cnt

  Configures the number of receive descriptors for jumbo frames larger than 1528 bytes. Default is 128 and valid range is from 1 to 255. When jumbo frames larger than 1528 bytes are used, this parameter should not be set lower than 60 on systems with high network traffic. Setting this parameter higher allows the NIC to buffer larger bursts of jumbo traffic without dropping frames, especially on slower systems. Depending on kernel and system architecture, the driver may require up to 268 bytes per descriptor. Note that each descriptor will also require a buffer the size of a maximum jumbo frame. Note that each descriptor requires a buffer the size of a maximum jumbo frame.On systems with insufficient memory, it may be necessary to reduce this parameter. When the maximum frame size is less than 1528 (MTU size less than 1514), this parameter is not used and is always 0.

- adaptive_coalesce

  Enables or disables adaptive adjustments to the various interrupt coalescing parameters. Enabling it allows the driver to dynamically adjust the interrupt coalescing parameters to achieve high throughput during heavy traffic and low latency during light traffic. rx_std_desc_cnt, (and rx_jumbo_desc_cnt if using jumbo frames) should not be set less than 50, and tx_pkt_desc_cnt should not be set less than 80 when this parameter is enabled. The valid values are:

  - 0 - disabled
  - 1 - enabled (default)
- rx_coalesce_ticks

  Configures the number of 1 usec ticks before the NIC generates receive interrupt after receiving a frame. This parameter works in conjunction with the rx_max_coalesce_frames parameter. Interrupt will be generated when either of these thresholds is exceeded. 0 means this parameter is ignored and interrupt will be generated when the rx_max_coalesce_frames threshold is reached. The valid range is from 0 to 500, and default is 80. This parameter is not used and will be adjusted automatically if adaptive_coalesce is set to 1.

- rx_max_coalesce_frames

  Configures the number of received frames before the NIC generates receive interrupt. The valid range is from 0 to 100, and default is 15. This parameter and rx_coalesce_ticks cannot be both 0, otherwise no receive interrupts will be generated. It should also be set significantly lower than rx_std_desc_cnt (and rx_jumbo_desc_cnt if using jumbo frames). This parameter is not used and will be adjusted automatically if adaptive_coalesce is set to 1.

- tx_coalesce_ticks

  Configures the number of 1 usec ticks before the NIC generates transmit interrupt after transmitting a frame. This parameter works in conjunction with the tx_max_coalesce_frames parameter. Interrupt will be generated when either of these thresholds is exceeded. 0 means this parameter is ignored and interrupt will be generated when the tx_max_coalesce_frames threshold is reached. The valid range is from 0 to 500, and default is 200. This parameter is not used and will be adjusted automatically if adaptive_coalesce is set to 1.

- tx_max_coalesce_frames

  Configures the number of transmitted frames before the NIC generates transmit interrupt. The valid range is from 0 to 100, and default is 35. This parameter and tx_coalesce_ticks cannot be both 0, otherwise no transmit completion interrupt will be generated. This parameter should always be set lower than tx_pkt_desc_cnt. This parameter is not used and will be adjusted automatically if adaptive_coalesce is set to 1.

- stats_coalesce_ticks

  Configures the number of 1 usec ticks between periodic statistics block DMAs. The valid range is from 0 to 3600000000, and default is 1000000 (1 sec.). Set to 0 to disable statistics updates. This parameter is not used and will be set to default if rx_adaptive_coalesce is set to 1.

- enable_wol

  Enables or disables magic packet Wake-On-LAN when the system is shutdown. Note that not all systems support Wake-On-LAN. The valid values are:

  - 0 magic packet Wake-On-LAN disabled (default)
  - 1 magic packet Wake-On-LAN enabled
- enable_tso

> Enables or disables TCP Segmentation Option (TSO) when using kernels that support it.

- TSO disabled (default)
- TSO enabled

Back to Top

## Driver Messages

The following are the most common sample messages that may be logged in the file /var/log/messages. Use dmesg -n <level> to control the level at which messages will appear on the console. Most systems are set to level 6 by default.

> Broadcom Gigabit Ethernet Driver bcm5700 with Broadcom NIC Extension (NICE) ver. 5.0.17 (01/10/03)

> > Driver signon

> eth#: Broadcom BCM5701 1000Base-T found at mem faff0000, IRQ 16, node addr 0010180402d8
> eth#: Broadcom BCM5701 Integrated Copper transceiver found
> eth#: Scatter-gather ON, 64-bit DMA ON, Tx Checksum ON, Rx Checksum ON

> > NIC detected

> bcm5700: eth# NIC Link is Up, 1000 Mbps full-duplex

> > Link up and speed indication

> bcm5700: eth# NIC Link is Down

> > Link down indication

Back to Top

## Statistics

Detailed statistics and configuration information can be viewed in the file /proc/net/nicinfo/eth#.info.

Back to Contents