CRYSTAL LAN CS8900/CS8920 ETHERNET ADAPTERS Linux Network Interface Driver ver. 1.02 =============================================================================== TABLE OF CONTENTS 1.0 CRYSTAL LAN CS8900/CS8920 ETHERNET ADAPTERS 1.1 Product Overview 1.2 Driver Description 1.2.1 Driver Name 1.2.2 File in the Driver Package 1.3 System Requirements 1.4 Licensing Information 2.0 ADAPTER INSTALLATION and CONFIGURATION 2.1 CS8900-based Adapter Configuration 2.2 CS8920-based Adapter Configuration 3.0 LOADING THE DRIVER AS A MODULE 4.0 COMPILING THE DRIVER 4.1 Compiling the Driver As a Loadable Module 4.2 Compiling the Driver Into the Kernel 4.3 Compiling the Driver for a Linux v1.2.13 Kernel 5.0 TESTING AND TROUBLESHOOTING 5.1 Known Defects and Limitations 5.2 Testing the Adapter 5.2.1 Diagnostic Self-Test 5.2.2 Diagnostic Network Test 5.3 Using the Adapter's LEDs 5.4 Resolving I/O Conflicts 6.0 TECHNICAL SUPPORT 6.1 Contacting Crystal's Technical Support 6.2 Information Required Before Contacting Technical Support 6.3 Obtaining the Latest Driver Version 6.3.1 Crystal's Web Site 6.3.2 Crystal's Bulletin Board Service 1.0 CRYSTAL LAN CS8900/CS8920 ETHERNET ADAPTERS =============================================================================== 1.1 PRODUCT OVERVIEW The CS8900-based ISA Ethernet Adapters from Crystal Semiconductor follow IEEE 802.3 standards and support half or full-duplex operation in ISA bus computers on 10 Mbps Ethernet networks. The adapters are designed for operation in 16-bit ISA or EISA bus expansion slots and are available in 10BaseT-only or 3-media configurations (10BaseT, 10Base2, and AUI for 10Base-5 or fiber networks). CS8920-based adapters are similar to the CS8900-based adapter with additional features for Plug and Play (PnP) support and Wakeup Frame recognition. As such, the configuration procedures differ somewhat between the two types of adapters. Refer to the "Adapter Configuration" section for details on configuring both types of adapters. 1.2 DRIVER DESCRIPTION The CS8900/CS8920 Ethernet Adapter driver for Linux supports the Linux v1.2.13 and v2.0 (or greater) kernels. It can be compiled directly into the kernel or loaded at run-time as a device driver module. 1.2.1 Driver Name: cs89x0 1.2.2 Files in the Driver Archive: readme.txt - this file release.txt - known defects and modification log cs89x0.c - driver C code cs89x0.h - driver header file cs89x0.o - pre-compiled module (for v2.0 kernel) 1.3 SYSTEM REQUIREMENTS The following hardware is required: * Crystal LAN (CS8900/20-based) Ethernet ISA Adapter * IBM or IBM-compatible PC with: * An 80386 or higher processor * 16 bytes of contiguous IO space available between 210h - 370h * One available IRQ (5,10,11,or 12 for the CS8900, 3-7,9-15 for CS8920). * Appropriate cable (and connector for AUI, 10BASE-2) for your network topology. The following software is required: * LINUX kernel version 1.2.13 or 2.X * CS8900/20 Setup Utility (DOS-based) * LINUX kernel sources for your kernel (if compiling into kernel) * GNU Toolkit (gcc and make) v2.6 or above (if compiling into kernel or a module) 1.4 LICENSING INFORMATION This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 1. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. For a full copy of the GNU General Public License, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 2.0 ADAPTER INSTALLATION and CONFIGURATION =============================================================================== Both the CS8900 and CS8920-based adapters can be configured using parameters stored in an on-board EEPROM. You must use the DOS-based CS8900/20 Setup Utility if you want to change the adapter's configuration in EEPROM. When loading the driver as a module, you can specify many of the adapter's configuration parameters on the command-line to override the EEPROM's settings or for interface configuration when an EEPROM is not used. (CS8920-based adapters must use an EEPROM.) See Section 3.0 LOADING THE DRIVER AS A MODULE. Since the CS8900/20 Setup Utility is a DOS-based application, you must install and configure the adapter in a DOS-based system using the CS8900/20 Setup Utility before installation in the target LINUX system. (Not required if installing a CS8900-based adapter and the default configuration is acceptable.) 2.1 CS8900-BASED ADAPTER CONFIGURATION CS8900-based adapters shipped from Crystal Semiconductor have been configured with the following "default" settings: Operation Mode: Memory Mode IRQ: 10 Base I/O Address: 300 Memory Base Address: D0000 Optimization: DOS Client Transmission Mode: Half-duplex BootProm: None Media Type: Autodetect (3-media cards) or 10BASE-T (10BASE-T only adapter) You should only change the default configuration settings if conflicts with another adapter exist. To change the adapter's configuration, run the CS8900/20 Setup Utility. 2.2 CS8920-BASED ADAPTER CONFIGURATION CS8920-based adapters are shipped from Crystal Semiconductor configured as Plug and Play (PnP) enabled. However, since Linux is not currently a PnP compatible operating system, you must install the CS8920 adapter in a DOS-based PC and run the CS8900/20 Setup Utility to disable PnP and configure the adapter before installation in the target Linux system. Failure to do this will leave the adapter inactive and the driver will be unable to communicate with the adapter. **************************************************************** * CS8920-BASED ADAPTERS: * * * * CS8920-BASED ADAPTERS ARE PLUG and PLAY ENABLED BY DEFAULT. * * SCO UNIX IS NOT A PnP OPERATING SYSTEM. THEREFORE, YOU MUST * * RUN THE CS8900/20 SETUP UTILITY TO DISABLE PnP SUPPORT AND * * TO ACTIVATE THE ADAPTER. * **************************************************************** 3.0 LOADING THE DRIVER AS A MODULE =============================================================================== If the driver is compiled as a loadable module, you can load the driver module with the 'insmod' command. Many of the adapter's configuration parameters can be specified as command-line arguments to the load command. This facility provides a means to override the EEPROM's settings or for interface configuration when an EEPROM is not used. Example: insmod cs89x0.o io=0x200 irq=0xA media=aui This example loads the module and configures the adapter to use an IO port base address of 200h, interrupt 10, and use the AUI media connection. The following configuration options are available on the command line: * io=### - specify IO address (200h-360h) * irq=## - specify interrupt level * mmode=##### - specify memory base address * dma=# - specify DMA channel * media=rj45 - specify media type or media=bnc or media=aui * duplex=f - specify forced half/full/autonegotiate duplex or duplex=h or duplex=auto * debug=# - debug level NOTES: * If an EEPROM is present, any specified command-line parameter will override the corresponding configuration value stored in EEPROM. * If no "io" or "mmode" parameter is specified on the command-line, the driver will scan for the adapter. When scanning, the driver only reads I/O ports. This sometimes is not sufficient, (e.g. after a warm boot). If you wish to allow the driver to perform a more aggressive scan (one write to the IO base addresses to reset the data port pointer) you can specify an I/O address with an address value one greater than the configured address. Example, to scan for an adapter located at IO base 0x300, specify an IO address of 0x301. Only ports between 200h and 360h at 20h intervals are scanned. * The "duplex=auto" parameter is only supported for the CS8920. * The minimum command-line configuration required if an EEPROM is not present is: * io or mmode base address * irq * media type (no autodetect) The following additional parameters are CS89XX defaults (values used with no EEPROM or command-line argument). * DMA Burst = enabled * IOCHRDY Enabled = enabled * UseSA = enabled * CS8900 defaults to half-duplex if not specified on command-line * CS8920 defaults to autoneg if not specified on command-line * Use reset defaults for other config parameters * You can use ifconfig to set the adapter's Ethernet address. 4.0 COMPILING THE DRIVER =============================================================================== The cs89x0 driver can be compiled directly into the kernel or compiled into a loadable device driver module. NOTE: This part of the description relates to adding the driver to a kernel not containing the cs89x0 driver. This kernel already contains it. 4.1 COMPILING THE DRIVER AS A LOADABLE MODULE To compile the driver into a loadable module, use the following command (single command line, without quotes): "gcc -D__KERNEL__ -I/usr/src/linux/include -I/usr/src/linux/net/inet -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer -DMODULE -DCONFIG_MODVERSIONS -c cs89x0.c" 4.2 COMPILING THE DRIVER INTO THE KERNEL To compile the driver directly into the kernel requires editing four configuration files, copying the source file to the /linux/drivers/net directory and then running the make utility to rebuild the kernel. 1. Edit the following configuration files by adding the statements as indicated. (When possible, try to locate the added text to the section of the file containing similar statements). a.) In /usr/src/linux/drivers/net/CONFIG, add CS89x0_OPTS = Example: WD_OPTS = #-DWD_SHMEM=0xDD000 EL2_OPTS = #-DEL2_AUI CS89x0_OPTS = NE_OPTS = HP_OPTS = PLIP_OPTS = b.) In /usr/src/linux/drivers/net/Config.in, add: tristate 'CS89x0 support' CONFIG_CS89x0 Example: if [ "$CONFIG_EXPERIMENTAL" = "y" ]; then tristate 'ICL EtherTeam 16i/32 support' CONFIG_ETH16I fi tristate 'CS89x0 support' CONFIG_CS89x0 tristate 'NE2000/NE1000 support' CONFIG_NE2000 if [ "$CONFIG_EXPERIMENTAL" = "y" ]; then tristate 'NI5210 support' CONFIG_NI52 c.) In /usr/src/linux/drivers/net/Makefile, add the following lines: ifeq ($(CONFIG_CS89x0),y) L_OBJS += cs89x0.o else ifeq ($(CONFIG_CS89x0),m) M_OBJS += cs89x0.o endif endif d.) In /linux/drivers/net/Space.c file, add the line: extern int cs89x0_probe(struct device *dev); Example: extern int ultra_probe(struct device *dev); extern int wd_probe(struct device *dev); extern int el2_probe(struct device *dev); extern int cs89x0_probe(struct device *dev); extern int ne_probe(struct device *dev); extern int hp_probe(struct device *dev); extern int hp_plus_probe(struct device *dev); Also add: #ifdef CONFIG_CS89x0 && cs89x0_probe(dev) #endif 2.) Copy the driver source files (cs89x0.c and cs89x0.h) and this README file into the /usr/src/linux/drivers/net directory. 3.) Run 'make config' followed by 'make dep' and finally 'make' to rebuild the kernel. 4.3 COMPILING THE DRIVER FOR A LINUX v1.2.13 KERNEL To compile the driver for Linux v1.2.13 (into the kernel or as a module), change the "SUPPORTS" define at the beginning of the cs89x0.c file. Example: #define SUPPORTS_1_2_13 1 /* supports Linux kernel v1.2.13 */ or #define SUPPORTS_1_2_13 0 /* supports Linux kernel v2.0 (default) */ 5.0 TESTING AND TROUBLESHOOTING =============================================================================== 5.1 KNOWN DEFECTS and LIMITATIONS Refer to the RELEASE.TXT file distributed as part of this archive for a list of known defects, driver limitations, and work arounds. 5.2 TESTING THE ADAPTER Once the adapter has been installed and configured, the diagnostic option of the CS8900/20 Setup Utility can be used to test the functionality of the adapter and its network connection. Use the diagnostics 'Self Test' option to test the functionality of the adapter with the hardware configuration you have assigned. You can use the diagnostics 'Network Test' to test the ability of the adapter to communicate across the Ethernet with another PC equipped with a CS8900/20-based adapter card (it must also be running the CS8900/20 Setup Utility). NOTE: The Setup Utility's diagnostics are designed to run in a DOS-only operating system environment. DO NOT run the diagnostics from a DOS or command prompt session under Windows 95, Windows NT, OS/2, or other operating system. [AC - Question : Do they work in DOSEMU ?] To run the diagnostics tests on the CS8900/20 adapter: 1.) Boot DOS on the PC and start the CS8900/20 Setup Utility. 2.) The adapter's current configuration is displayed. Hit the ENTER key to get to the main menu. 4.) Select 'Diagnostics' (ALT-G) from the main menu. * Select 'Self-Test' to test the adapter's basic functionality. * Select 'Network Test' to test the network connection and cabling. 5.2.1 DIAGNOSTIC SELF-TEST The diagnostic self-test checks the adapter's basic functionality as well as its ability to communicate across the ISA bus based on the system resources assigned during hardware configuration. The following tests are performed: * IO Register Read/Write Test The IO Register Read/Write test ensures that the CS8900/20 can be accessed in IO mode, and that the IO base address is correct. * Shared Memory Test The Shared Memory test ensures the CS8900/20 can be accessed in memory mode and that the range of memory addresses assigned does not conflict with other devices in the system. * Interrupt Test The Interrupt test ensures there are no conflicts with the assigned IRQ signal. * EEPROM Test The EEPROM test ensures the EEPROM can be read. * Chip RAM Test The Chip RAM test ensures the 4 K of memory internal to the CS8900/20 is working properly. * Internal Loop-back Test The Internal Loop Back test ensures the adapter's transmitter and receiver are operating properly. If this test fails, make sure the adapter's cable is connected to the network (check for LED activity for example). * Boot PROM Test The Boot PROM test ensures the Boot PROM is present, and can be read. Failure indicates the Boot PROM was not successfully read due to a hardware problem or due to a conflicts on the Boot PROM address assignment. (Test only applies if the adapter is configured to use the Boot PROM option.) Failure of a test item indicates a possible system resource conflict with another device on the ISA bus. In this case, you should use the Manual Setup option to reconfigure the adapter by selecting a different value for the system resource that failed. 5.2.2 DIAGNOSTIC NETWORK TEST The Diagnostic Network Test verifies a working network connection by transferring data between two CS8900/20 adapters installed in different PCs on the same network. (Note: the diagnostic network test should not be run between two nodes across a router.) This test requires that each of the two PCs have a CS8900/20-based adapter installed and have the CS8900/20 Setup Utility running. The first PC is configured as a Responder and the other PC is configured as an Initiator. Once the Initiator is started, it sends data frames to the Responder which returns the frames to the Initiator. The total number of frames received and transmitted are displayed on the Initiator's display, along with a count of the number of frames received and transmitted OK or in error. The test can be terminated anytime by the user at either PC. To setup the Diagnostic Network Test: 1.) Select a PC with a CS8900/20-based adapter and a known working network connection to act as the Responder. Run the CS8900/20 Setup Utility and select 'Diagnostics -> Network Test -> Responder' from the main menu. Hit ENTER to start the Responder. 2.) Return to the PC with the CS8900/20-based adapter you want to test and start the CS8900/20 Setup Utility. 3.) From the main menu, Select 'Diagnostic -> Network Test -> Initiator'. Hit ENTER to start the test. You may stop the test on the Initiator at any time while allowing the Responder to continue running. In this manner, you can move to additional PCs and test them by starting the Initiator on another PC without having to stop/start the Responder. 5.3 USING THE ADAPTER'S LEDs The 2 and 3-media adapters have two LEDs visible on the back end of the board located near the 10Base-T connector. Link Integrity LED: A "steady" ON of the green LED indicates a valid 10Base-T connection. (Only applies to 10Base-T. The green LED has no significance for a 10Base-2 or AUI connection.) TX/RX LED: The yellow LED lights briefly each time the adapter transmits or receives data. (The yellow LED will appear to "flicker" on a typical network.) 5.4 RESOLVING I/O CONFLICTS An IO conflict occurs when two or more adapter use the same ISA resource (IO address, memory address or IRQ). You can usually detect an IO conflict in one of four ways after installing and or configuring the CS8900/20-based adapter: 1.) The system does not boot properly (or at all). 2.) The driver can not communicate with the adapter, reporting an "Adapter not found" error message. 3.) You cannot connect to the network or the driver will not load. 4.) If you have configured the adapter to run in memory mode but the driver reports it is using IO mode when loading, this is an indication of a memory address conflict. If an IO conflict occurs, run the CS8900/20 Setup Utility and perform a diagnostic self-test. Normally, the ISA resource in conflict will fail the self-test. If so, reconfigure the adapter selecting another choice for the resource in conflict. Run the diagnostics again to check for further IO conflicts. In some cases, such as when the PC will not boot, it may be necessary to remove the adapter and reconfigure it by installing it in another PC to run the CS8900/20 Setup Utility. Once reinstalled in the target system, run the diagnostics self-test to ensure the new configuration is free of conflicts before loading the driver again. When manually configuring the adapter, keep in mind the typical ISA system resource usage as indicated in the tables below. I/O Address Device IRQ Device ----------- -------- --- -------- 200-20F Game I/O adapter 3 COM2, Bus Mouse 230-23F Bus Mouse 4 COM1 270-27F LPT3: third parallel port 5 LPT2 2F0-2FF COM2: second serial port 6 Floppy Disk controller 320-32F Fixed disk controller 7 LPT1 8 Real-time Clock 9 EGA/VGA display adapter 12 Mouse (PS/2) Memory Address Device 13 Math Coprocessor -------------- --------------------- 14 Hard Disk controller A000-BFFF EGA Graphics Adapter A000-C7FF VGA Graphics Adapter B000-BFFF Mono Graphics Adapter B800-BFFF Color Graphics Adapter E000-FFFF AT BIOS 6.0 TECHNICAL SUPPORT =============================================================================== 6.1 CONTACTING CRYSTAL'S TECHNICAL SUPPORT Crystal's CS89XX Technical Application Support can be reached at: Telephone :(800) 888-5016 (from inside U.S. and Canada) :(512) 442-7555 (from outside the U.S. and Canada) Fax :(512) 912-3871 E-mail :ethernet@crystal.cirrus.com WWW :http://www.crystal.com 6.2 INFORMATION REQUIRED BEFORE CONTACTING TECHNICAL SUPPORT Before contacting Crystal for technical support, be prepared to provide as much of the following information as possible. 1.) Adapter type (CRD8900, CDB8900, CDB8920, etc.) 2.) Adapter configuration * IO Base, Memory Base, IO or memory mode enabled, IRQ, DMA channel * Plug and Play enabled/disabled (CS8920-based adapters only) * Configured for media auto-detect or specific media type (which type). 3.) PC System's Configuration * Plug and Play system (yes/no) * BIOS (make and version) * System make and model * CPU (type and speed) * System RAM * SCSI Adapter 4.) Software * CS89XX driver and version * Your network operating system and version * Your system's OS version * Version of all protocol support files 5.) Any Error Message displayed. 6.3 OBTAINING THE LATEST DRIVER VERSION You can obtain the latest CS89XX drivers and support software from Crystal's BBS or Web site. You can also contact Crystal's Technical Support (email: ethernet@crystal.cirrus.com) and request that you be registered for automatic software-update notification. 6.3.1 CRYSTAL'S WEB SITE Crystal Semiconductor maintains a web page at http://www.crystal.com with the latest drivers and technical publications. 6.3.2 CRYSTAL'S BULLETIN BOARD SERVICE Access to the BBS is available 24 hours a day, seven days a week. Baud rates from 300K to 14.4K are supported as well as most common file transfer protocols. To access the BBS, set your terminal software to use 8 data bits, 1 stop bit, and no parity. Dial (512) 441-3265 and press after connection is made. Login using your account name and password. (If you do not have an account, you may login as "GUEST". No password is required for the Guest account.) From the main system menu, select the "Enter Public File Area" menu option. From the Public File Area menu, select the "LAN (Local Area Network)" file area. A list of the latest drivers and support utilities available for the CS89XX ISA Ethernet adapter will be presented along with the option to download the file(s) of your choice.