readme.txt

SMSC NET controller 9218 driver software

====================================================================================
XScale Linux v1.55 Driver Release Note for SMSC LAN9118 Family Ethernet Controllers
====================================================================================


/***************************************************************************
 *
 * Copyright (c) 2004-2006, SMSC
 *
 * 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; either version 2
 * of the License, or (at your option) any later version.
 *
 * 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.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 ***************************************************************************
 * File: Readme.txt
 */

This is the users/programmers guide for the LAN9118 Linux Driver
The following sections can be found below
*  Revision History
*  Files
*  Features
*  Driver Parameters
*  Rx Performance Tuning
*  Tested Platforms
*  Rx Code Path
*  Tx Code Path
*  Platform Interface Descriptions

#######################################################
############### REVISION HISTORY ######################
#######################################################

01/07/2008 Afshin Hosseinipour, version 1.55
Added Support for LAN9210
Added Flow Control Parameters for Lan9210

#######################################################
#################### FILES ############################
#######################################################
readme.txt: this file

smsc9118.c: Main driver source code file.
xscale_linux.c
sh3_polaris.c
sh3_se01.c
      These are platform dependent files. It defines
      the platform dependent structure, PLATFORM_DATA.
      It also defines some platform dependent constants for
      use by smsc9118.c. see PLATFORM INTERFACE DESCRIPTIONS
      below for more information. This should be defined in the Makefile
ioctl_118.h
      defines ioctl codes common between the driver(smsc9118.c)
      and the helper application (cmd9118.c)
      
cmd9118.c
       This is the source code for the helper application.
       It provides the means by which one can send any ioctl code
       to the driver (smsc9118.c).
       

Makefile_2.4: This file is used for building the Linux-2.4 driver for the
        xscale platform, and the helper application. It will copy the binary files
	
	to ./bin_2.4/ folder
	
	usage:  cp Makefile_2.4 Makefile
		make

Makefile_2.6: This file is used for building the Linux-2.6 driver for the
        xscale platform, and the helper application. It will copy the binary files
	
	to ./bin_2.6/ folder
	
	usage:  cp Makefile_2.6 Makefile
		make
        
smsc9118.o: this is the driver binary obtained after building under Linux-2.4 kernel


smsc9118.ko: this is the driver binary obtained after building under Linux-2.6 kernel

    
cmd9118: this is the helper application binary obtained after 
        building cmd9118.c
        
lint.h:
	This is a header file for use only with the lint tool.
	It provides structure definitions and function declarations 
	used by the driver so the lint tool does not need to 
	scan the real header files. This is done because the real
	header files generate too many error messages.

COPYING:
	This is a copy of the GNU GENERAL PUBLIC LICENSE


testing.txt:

	 This file has some informations about the testing of the driver.


xscale_release_note.txt

	This file has some informations about the release and the driver migration

############################################################
################### FEATURES ###############################
############################################################
transmit and receive for pio and dma
Automatic Flow control for Tx, and Rx
Multicast capable
Mac Address Management
External Phy support


############################################################
################## DRIVER PARAMETERS #######################
############################################################
The following are load time modifiable driver parameters.
They can be set when using insmod
Example:
# insmod smsc9118.o rx_dma=0 tx_dma=1 irq=5

lan_base
    specifies the physical base location in memory where the 
    LAN9118 can be accessed. By default the location will be
    choosen by Platform_Initialize.
    
bus_width
    specifies the bus_width to be configured by
    Platform_Initialize. Must be set to either 16, or 32.
    Any other value or by default Platform_Initialize will 
    attempt to autodetect the bus width
    

link_mode
    specifies the link mode used. Each bit has different meanings
      bit 0, 0x01, 10Mbps Half Duplex,
      bit 1, 0x02, 10Mbps Full Duplex,
      bit 2, 0x04, 100Mbps Half Duplex,
      bit 3, 0x08, 100Mbps Full Duplex,
      bit 4, 0x10, Symmetrical Pause,
      bit 5, 0x20, Asymmetrical Pause,
      bit 6, 0x40, Auto Negotiate,
      
    if bit 6 is set, then Auto Negotiation is used, and bits 0 through 5
      define what modes are advertised. 
      
    if bit 6 is clear, then Auto Negotiation is not used, and bits 0 
      through 3 select which speed and duplex setting to use. In this case, 
      only the most significant set bit is used to set the speed and duplex.
      Example, the following are bits 6 to 0, and the resulting setting
      bits 6 5 4 3 2 1 0
           0 x x 0 0 0 x, 10Mbps Half Duplex
           0 x x 0 0 1 x, 10Mbps Full Duplex
           0 x x 0 1 x x, 100Mbps Half Duplex
           0 x x 1 x x x, 100Mbps Full Duplex
           
    by default link_mode=0x7F which uses Auto Negotiation and advertises
       all modes.
    
irq
    specifies the irq number to use. The default value is decided
    by the platform layer with the macro PLATFORM_IRQ
    
int_deas
    specifies the interrupt deassertion period to be written to
    INT_DEAS of INT_CFG register. The default value is decided by
    the platform layer with the macro PLATFORM_INT_DEAS
    
irq_pol
    specifies the value to be written to IRQ_POL of INT_CFG register.
    The default value is decided by the platform layer with the 
    macro PLATFORM_INT_POL.
    
irq_type
    specifies the value to be written to IRQ_TYPE of INT_CFG register.
    The default value is decided by the platform layer with the 
    macro PLATFORM_IRQ_TYPE
    
rx_dma
    specifies the dma channel to use for receiving packets. It may
    also be set to the following values
        256 = TRANSFER_PIO
            the driver will not use dma, it will use PIO.
        255 = TRANSFER_REQUEST_DMA
            the driver will call the Platform_RequestDmaChannel
            to get an available dma channel
    the default value is decided by the platform layer with the 
    macro PLATFORM_RX_DMA
        
tx_dma
    specifies the dma channel to use for transmitting packets. It may
    also be set to the following values
        256 = TRANSFER_PIO
            the driver will not use dma, it will use PIO.
        255 = TRANSFER_REQUEST_DMA
            the driver will call the Platform_RequestDmaChannel
            to get an available dma channel
    the default value is decided by the platform layer with the 
    macro PLATFORM_TX_DMA

dma_threshold
    specifies the minimum size a packet must be for using DMA. 
    Otherwise the driver will use PIO. For small packets PIO may
    be faster than DMA because DMA requires a certain amount of set
    up time where as PIO can start almost immediately. Setting this
    value to 0 means dma will always be used where dma has been enabled.

    The default value is decided by the platform layer with the
    macro PLATFORM_DMA_THRESHOLD
    
mac_addr_hi16
    Specifies the high word of the mac address. If it was not 
    specified then the driver will try to read the mac address 
    from the eeprom. If that failes then the driver will set it 
    to a valid value. Both mac_addr_hi16 and mac_addr_lo32 must be 
    used together or not at all.
    
mac_addr_lo32
    Specifies the low dword of the mac address. If it was not 
    specified then the driver will try to read the mac address 
    from the eeprom. If that failes then the driver will set it to 
    a valid value. Both mac_addr_hi16 and mac_addr_lo32 must be 
    used together or not at all.
    
debug_mode
    specifies the debug mode
        0x01, bit 0 display trace messages
        0x02, bit 1 display warning messages
        0x04, bit 2 enable GPO signals

    Trace messages will only display if the driver was compiled
        with USE_TRACE defined.
    Warning message will only display if the driver was compiled
        with USE_WARNING defined.

tx_fifo_sz
    specifies the value to write to TX_FIFO_SZ of the 
    HW_CFG register. It should be set to a value from 0 to 15
    that has been left shifted 16 bits.
    The default value is 0x00050000UL
    
afc_cfg
    specifies the value to write to write to the AFC_CFG register
    during initialization. By default the driver will choose a value
    that seems resonable for the tx_fifo_sz setting. However it
    should be noted that the driver has only be tested using the 
    default setting for tx_fifo_sz
    
link_mode
    	specifies the link mode used. 
		2  using NAPI.
		1  using tasklet
		0  ISR

	2 specifies that most of the receive work should be done in a NAPI mode.
	  It is the feature of 2.6 kernel or newer.

	1 specifies that most of the receive work should be done in a tasklet, 
	  thereby enabling other system interrupts.
	0 specifies that all receive work is done in the ISR,
	where interrupts are not enabled. A single burst of receive work has
	been seen to take as long as 3 mS. It would not be friendly for this
	driver to hold the CPU for that long, there for tasklets are enabled
	by default. However there are some tests that measure a mild performance 
	drop when using tasklets, therefor this parameter is included so the 
	end user can choose to disable tasklets.
	NOTE:10/29/2004: as of version 1.02 tasklets are disabled by default because
	testing has not confirmed their stability. The user may still turn on
	tasklets but does so at there own risk.
	NOTE:11/05/2004: as of version 1.04 tasklets are enabled by default because
	the issue observed before has been solved.
	    
phy_addr
	The default value of 0xFFFFFFFF tells the driver to use the internal phy.
	A value less than or equal to 31 tells the driver to use the external phy
	    at that address. If the external phy is not found the internal phy
	    will be used.
	Any other value tells the driver to search for the external phy on all
	    addresses from 0 to 31. If the external phy is not found the internal 
	    phy will be used.
	
max_throughput
    This is one of the software flow control parameters. It specifies the 
    maximum throughput in a 100mS period that was measured during an rx 
    TCP_STREAM test. It is used to help the driver decide when to activate 
    software flow control and what work load to maintain when flow control 
    is active. By default the driver will decide what value to use.
    See RX PERFORMANCE TUNING.
    
max_packet_count
	This is one of the software flow control parameters. It specifies the
	maximum packets counted in a 100mS period during an rx TCP_STREAM test.
	It is used to help the driver decide when to activate software flow
	control, and what work load to maintain when flow control is active.
	By default the driver will decide what value to use.
	See RX PERFORMANCE TUNING.
	
packet_cost
	This is one of the software flow control parameters. It specifies the
	ideal packet cost. This allows the driver achieve the best performance
	with both large and small packets, when flow control is active.
	By default the driver will decide what value to use.
	See RX PERFORMANCE TUNING.

burst_period
	This is one of the software flow control parameters. When flow control is active
	the driver will do work in bursts. This value specifies the length of 
	the burst period in 100uS units. By default the driver will decide what value to
	use. See RX PERFORMANCE TUNING.

max_work_load
	This is one of the software flow control parameters. It specifies the amount
	of work the driver can do in a 100mS period. By default it is set as
	max_work_load = max_throughput + (max_packet_count*packet_cost);
	See RX PERFORMANCE TUNING.