Linux Ethercard Status, Diagnostic and Setup Utilities

This is a collections of user-level programs to report the status of and verify the basic functionality of an ethercard. Most programs report the link status and interface configuration. The chip-specific programs can read (and sometimes write) the EEPROM setup table of software-configured cards.

These program also provide example code for accessing hardware device from a user-level program in Linux. All of them enable access to I/O space registers using ioperm() or iopl() . The PCI diagnostic programs demonstrate user-level access to PCI configuration information. Several ISA diagnostics (e.g. e21.c) demonstrate access to ISA shared memory regions using mmap() .

Quick Index

MII link status report and diagnostics

The MII diagnostic program reports the link status as read from the MII transceiver management registers. It works with many (but not all) of the Fast Ethernet device drivers. The link status may be monitored by non-root users, with root or network administration privileges required to modify the transceiver settings.

When run as mii-diag -w the program continuously monitors the link status, emitting a time-stamped report of link changes.

Extensive details about the meaning of the MII status registers are available from the Understanding the MII Status Info page.

When run with root permission or CAP_NET_ADMIN (Linux 2.2.0 and later only) capabilities additional link configuration options are available. The -A mediatype (set the advertised autonegotiation capabilities) and -F mediatype (set forced media type, necessarily disabling autonegotiation) options are usable. See the MII options section for more details.

You may link this program against the libmii.c library for more detailed information about the transceiver and vendor-specific extended information.

Note: Many additional advanced features exist. See the source code for details.

Diagnostic Programs

PCI Configuration and Power Setting

The pci-config program reports many details about PCI configuration space registers. Most casual users will be interested only in the following options.
-# N Describe or perform operations only the the Nth adapter found.
-S Put the device to sleep i.e. change to ACPI D3 state.
-W Wake the device up i.e. change to ACPI D0 state.

PCI adapters

The following diagnostics are available for PCI and CardBus devices. All are distributed as C source code, and must be compiled using the compile-command at the end of the file.
eepro100-diag.c
Intel EtherExpress PCI Pro/100 series (including the PCI Pro10+).
epic-diag.c
SMC SMC83c170 "EPIC" series.
hamachi-diag.c
Packet Engines GNIC-II "Hamachi".
natsemi-diag.c
National Semiconductor DP83810 series.
ne2k-pci-diag.c
PCI NE2000 clone diagnostics
This diagnostic works with many different board types, notably those based on the Winbond '940 and RealTek RTL8029 chips. EEPROM programming is available with only a few of the types.
pcnet-diag.c
AMD PCNet/PCI 79c970 series.
rtl8139-diag.c
RealTek RTL8129/8139 series.
Note: Use ne2k-pci-diag for the RTL8029.
starfire-diag.c
Adaptec "Starfire" DuraLAN.
sundance-diag.c
Sundance Technology ST201 "Alta" chip.
tulip-diag.c
Intel/Digital Tulip (DC21040 series) and the many Tulip work-alikes: Lite-On PNIC, STMicro, ADMtek Comet, Macronix MXIC, Davicom DM9101.
via-diag.c
VIA Rhine and Rhine-II, VT3043 and VT86c100A.
vortex-diag.c
3Com 3c590 Vortex, and 3c900 Boomerang/Cyclone/Hurricane series.
winbond-diag.c
Winbond W89c840.
Note: Use ne2k-pci-diag for the W89c940.
yellowfin-diag.c
Packet Engines "Yellowfin" and Symbios '885.

ISA and Other Non-PCI adapters

3Com 3c509 ISA EtherLink III diagnostics, C source code.
This program tests the detection and activation of the ISA card only. The setup program is available separately.
3Com 3c515 ISA Fast EtherLink diagnostics, C source code.
This program reports the registers of the ISA card only.
HP PCLAN+ diagnostics, C source code.
NE2000 detection, diagnostics, and setup.
This program can configure certain ISA NE2000 clones, such as the RealTek RTL8019. C source code.
NE2000 diagnostics, C source code (old version).
This is a smaller program that duplicates the kernel's probe routine.
AT-Lan-Tec/RealTek diagnostics, C source code.
And if you don't have the kernel source, you'll need the header file.
Cabletron E21xx diagnostics, C source code.
AT1700 diagnostics and setup.
C source code for a program that extensively tests the multicast filter (-m) and can write the EEPROM configuration register (-P -Q ).
Intel Ethernet Express diagnostics, C source code.

Setup Programs

Most of the programs above have some EEPROM configuration ability. However a few board designs require special setup programs.
National Semiconductor DP83905 AT/Lantic setup program, C source code.
The AT/Lantic chip is used in the NE2000+ and many other software-configured ISA NE2000 clones.
3Com EtherLink III family (3c509, 3c529, 3c579, and 3c589) setup program.
This program displays the registers and currently programmed settings. It allows the base I/O address, IRQ, and transceiver port settings to be changed.

Compiling the Diagnostic and Setup Programs

All source code files have the suggested compile command at the end of the file. In most cases the only requirement is that the program must be compiled with the '-O' flag so that I/O operations are properly inlined.

All source files are stand-alone, with one exception and two extensions:

I recommend that you retrive C source files using FTP from ftp://cesdis.gsfc.nasa.gov/pub/linux/diag/ rather than hoping that your web browers won't corrupt them.

Using the PCI Diagnostic programs

The PCI diagnostic programs have a consistent basic interface, with extensions as needed for special functionality. The /proc/pci pseudo-file is read to determine the cards installed, and they are checked the order listed. That means that the currently running kernel must be compiled with PCI, and the /proc pseudo-file-system must be mounted. Most Linux distributions do this by default.

Basic diagnostic options

The following options are implemented with all diagnostic programs:

-# N
Describe or perform operations only the the Nth adapter found.
-a
Show all registers
-D
Increase the debugging level.
-e
Show the EEPROM contents. With some diagnostic programs, "-ee" shows additional details.
-E
Do an Emergency rewrite of a completely corrupted EEPROM. This option is not actually implemented for most adapter types, and should never be used.
-f
Force operations. This option causes the diagnostic program to proceed even if it detects that the adapter is currently active.
-F media-type
Set the transceiver selection to the specified type. Valid media types are 10baseT, 10base2, 10base5, AUI.
-m
Show MII registers. With many diagnostic programs "-mm" shows additional details or polls the MII registers for one minute, reporting any status changes.
-p I/O-port
Specify the I/O port at which to find a single card. This option is primarily for ISA and CardBus adapters, but may be useful when a PCI adapter is not recognized. This option is usually used with '-t chip-type'.
-q
Quiet mode. But diagnostic program tend to be verbose anyway.
-t
Specify the chip type when it cannot be detected. Using an invalid index e.g. '-1' will cause a list of chip types to be emitted. This option is usually used with '-p port-base'.
-T
Run a functionality test appropriate to the chip, typically a memory or loopback test.
-v
Increase the verbosity level. Additional "-v" options increase the level further.
-V
Show the program version information.
-w
Write the EEPROM with the specified updated values.
-?
Emit usage information.

MII diagnostic basic options

Adapters with MII transceivers (all recent adapters running at 100Mbps) support the following options:
-A link-type Set the link capabilities we advertise using autonegotiation. Valid values are 100baseT4, 100baseTx, 100baseTx-FD, 100baseTx-HD, 10baseT, 10baseT-FD, and 10baseT-HD. The abbreviations HD and FD stand for full-duplex and half-duplex. The 100baseTx and 10baseT settings advertise both duplex values.

If more detailed control is required, the exact register setting may be specified with as a hexadecimal number e.g. 01e0.

-F link-type Force the transceiver to the fixed link-type. Autonegotiation is implicitly disabled.
-m Show MII registers. With many diagnostic programs -mm shows additional details or polls the MII registers for one minute, reporting any status changes.

Flash Boot ROM Options

The following options are implemented in diagnostic programs for chips that support Flash Boot ROM. In general the diagnostic program must be compiled with the -DLIBFLASH flag and linked against libflash.c.
-B Show the contents of the Flash boot ROM.
-L loadfile Write the Flash boot ROM with the contents of LOADFILE.
-S savefile Save the Flash boot ROM contents into SAVEFILE.

Configuration setup basic options

A few Diagnostics can optionally write the EEPROM configuration. While they have hardware-specific limitations, the typical options are:

-w
Write the EEPROM with the specified updated values. Some programs require "-w -w" to actually write the values. Recommended use is to try the intended settings without "-w", and then appended it to the command line when you are satisfied that the updates are specified correctly.
-F 10baseT|10baseT|10base2|10base5|AUI
Set the default transceiver type. Acceptable values are chip or board specific. "10base5" is an alias for "AUI". 10baseT+ is a 10baseT transceiver with reduced receive squelch threshold, a non-standard setting intended for lossy or overly long cables.
-H 00:11:22:33:44:55
Set the hardware MAC station address to the specified value. This should never be done.
-P I/O-port
Set the card's I/O address to the specified value. This is for ISA cards only. Acceptable values are chip specific.
-Q IRQ
Set the card to use the specified IRQ (interrupt line). This is for ISA cards only. Acceptable values are chip specific. Note: In rare cases a board may not conform to usual pin wiring order and the actual IRQ line used may differ from that specified and reported.
Top
Linux at CESDIS
Author:Donald Becker, becker@cesdis.gsfc.nasa.gov.