CRYSTAL LAN(tm) CS8900 VxWORKS NETWORK INTERFACE DRIVER
===============================================================================
This readme file describes how to install and configure the VxWorks network
interface driver, version 2.07a, for the Crystal Semiconductor CS8900 Ethernet 
controller chip.


0.0 TABLE OF CONTENTS
=====================

   1.0 DRIVER OVERVIEW
   2.0 INSTALLATION
   3.0 CONFIGURATION
   4.0 DISPLAYING DRIVER STATISTICS and CONFIGURATION
   5.0 PORTING TO A NEW BSP
   6.0 CONTACTING CRYSTAL'S TECHNICAL SUPPORT



1.0 DRIVER OVERVIEW
=======================

The version 2.07a Crystal LAN(tm) CS8900 Driver for VxWorks provides a high 
performance interface between the CS8900 Ethenet Controller and the VxWorks 
network communication protocols.  This driver has been tested on Intel 
[3|4|5]86-based ISA systems and on an IDT R3041 (MIPS) based system.  However,
the driver's organization facilitates porting to new BSPs.  

The driver is organized in three source file modules: if_cs.c, if_cs.h, and 
sysEnet.c.  The if_cs.c and if_cs.h provide BSP-independent routines and
definitions while the sysEnet.c module consists of BSP-dependent routines.
Porting the driver to a new BSP requires modification of only the sysEnet.c
module.

The current version of the driver is distributed with the sysEnet.c module for
the x386-based ISA BSP.  This module can be used for ISA systems as is or
used as an example for porting the driver to other VxWorks BSPs.


1. Features
-----------

* High Performance
  * Supports "Early TX" feature of CS8900
  * Automatic retransmission on TX underruns
  * Local TX queue permits start of next TX immediately after completion of
    previous TX (no ISR/Task level context switch required)
  * Local RX frame queue minimizes missed frames 
  * Supports loaning of local RX buffers to protocol (build_cluster)

* Run-time configuration from NVRAM or compile-time configuration supported
 (no NVRAM required)

* IO space or memory space models supported

* Supports "etherInput" and "etherOuput" hook routines

* Support Multicasting and Promiscuous Mode.


2. Limitations
--------------

*  Autodetection of media type is not supported.  A single media type must be 
   specified at compile time.

*  Driver supports only one CS8900 per system.


3. Known Defects
----------------

No known defects.


4. System Requirements
----------------------        
	
This driver has been designed to build and run using the following software
components:

     Tornado Version 1.0.1 (or greater)
     VxWorks Version 5.3.1 (or greater)
     GNU Toolkit Version 2.7 (or greater)




2.0 INSTALLATION
================

The following installation procedure installs and builds the Crystal
Semiconductor CS8900 ver. 2.07a network interface driver.  When the VxWorks 
operating system loads and executes, the operating system startup code 
automatically attaches and initializes the CS8900 network interface driver.


1. Copy the source files
------------------------

The CS8900 network interface driver consists of three source files:

   if_cs.c   -- BSP-independent driver routines
   if_cs.h   -- Header file: CS8900 driver and register defines
   sysEnet.c -- BSP-specific driver routines

Copy all three files to BSP directory (e.g. c:\tornado\target\config\pc486).
Verify that the driver file name is "if_cs.c" (all lower case). If the 
driver name is not lower case, the driver will not be built.


2. Modify the config.h file
---------------------------

Add the following lines to the config.h file in the BSP directory:

/* Include support for Crystal CS8900 Ethernet controller */
#include "if_cs.h"
#define CS8900_IOBASE                0x300
#define CS8900_MEMBASE               0x0000
#define CS8900_INT_LVL               0xA
#define CS8900_DMA_CHANNEL           0

#define INCLUDE_IF_USR
#define IF_USR_NAME    "cs"
#define IF_USR_ATTACH  csAttach
#define IF_USR_ARG1    (char*) CS8900_IOBASE           /* int  IOAddr        */
#define IF_USR_ARG2    (INT_NUM_IRQ0 + CS8900_INT_LVL) /* int  IntVector     */
#define IF_USR_ARG3    CS8900_INT_LVL                  /* int  IntLevel      */
#define IF_USR_ARG4    CS8900_MEMBASE                  /* int  MemAddr       */
#define IF_USR_ARG5    MEDIA_10BASE2                   /* int  MediaType     */
#define IF_USR_ARG6    CS8900_DMA_CHANNEL              /* int  DMA Channel   */
#define IF_USR_ARG7    (CFGFLG_NOT_EEPROM)             /* Config flags       */
#define IF_USR_ARG8    NULL                            /* unused             */


The definitions specifed here are an example configuration typical for an x86
ISA-based system.  Change the definitions as appropriate for your BSP.  See
the section on Configuration for more information.

If you want to boot the VxWorks operating system image over the LAN, then
modify the boot device in the DEFAULT_BOOT_LINE definition to be "cs".  The
DEFAULT_BOOT_LINE definition should look similar to:

#define DEFAULT_BOOT_LINE \
"cs(0,0)host:/pc486/vxWorks h=198.50.50.4 e=198.50.50.2 u=user pw=password"

where
   h  = IP address of host (machine where vxWorks image resides)
   e  = IP address of target
   u  = ftp account user name on the host
   pw = ftp account password on the host
   

Since the CS8900 driver is BSD 4.4 but not an Enhanced Network Driver(END),
comment out the INCLUDE_END and END_OVERRIDE definitions in the config.h file
to disable the END functions.  The BSD 4.4 network interface will be enabled
automatically by VxWorks after END is disabled.

/* Optional ethernet devices */
 
/*#define INCLUDE_END */             /* Enhanced Network Driver see configNet.h */
/*#define END_OVERRIDE*/             /* define if you are using old boot ROMs. */


3. Modify the Makefile
----------------------

You must modify the Makefile in the BSP directory.  Add the if_cs.o object file
to the MACH_EXTRA variable:

MACH_EXTRA = if_cs.o

This line causes the linker to include the CS8900 network interface driver
object file, if_cs.o, in the vxWorks (or bootrom_uncmp) image.


4. Build the Network Interface Driver
-------------------------------------

Add a dependency for the CS8900 network interface driver into the
dependency file for the BSP.  You can do this by "cleaning" the BSP directory 
and then making VxWorks.  Change to the BSP directory on the host and issue the
following two commands:

      make clean
      make vxWorks

The first command deletes the dependency file, along with other files.  The
second command makes the VxWorks image.  While making the VxWorks image, the
make utility notices that the dependency file is missing and regenerates it.
The regenerated dependency file includes a dependency for the CS8900 network
interface driver, because the if_cs.c file is sitting in the BSP directory.

To make a boot diskette for an x86 ISA-based system, place a diskette in drive 
A: and issuing the following two commands:

      make bootrom_uncmp
      mkboot a: bootrom_uncmp




3.0 CONFIGURATION
=================

The CS8900 network interface driver is configured via definitions in the
"config.h" and "sysenet.c" files.  In addition, the driver can take 
configuration information from non-volitale storage such as an EEPROM attached 
to the CS8900 or from system ROM.  (Refer to the CS8900 Technical Reference 
Manual for the format required for configuration data stored in EEPROM.)


Parameters in "config.h"
-----------------------

The following definitions are used to configure the CS8900 and specify its
hardware interface to the driver and operating system:


INCLUDE_IF_USR  Define to include support for configurable interface device


IF_USR_NAME    The "name" of the device interface.
               This value should always be "cs" (with quotes).


IF_USR_ATTACH  Name of interface's "attach" routine. 
               This value should always be "csAttach" (without quotes).


IF_USR_ARG1    IO Base Address
               This value is the base address of the CS8900 in IO space.
               Define in hexidecimal.


IF_USR_ARG2    Interrupt vector used by CS8900
               Define as INT_NUM_IRQ0 


IF_USR_ARG3    CS8900 Interrupt Request Channel
               Define as CS8900_INT_LVL.  Valid values for CS8900_INT_LVL are:
               0x5, 0xA, 0xB, or 0xC


IF_USR_ARG4    Base address of CS8900 in Memory space.
               Define in hexidecimal.
               If the memory address parameter is zero, the CS8900 operates in
			   the mode specified by EEPROM or the Configuration Flags parameter.


IF_USR_ARG5    Media type used by CS8900
               Define as:
	       MEDIA_AUI     for AUI connector
	       MEDIA_10BASE2 for 10Base-2 (BNC)
	       MEDIA_10BASET for 10Base-T (RJ45)


IF_USR_ARG6    CS8900 DMA Channel          
               Define as 0.  This driver does not require DMA support.