simp911x.c

SMSC 9118 Driver for linux

/***************************************************************************
 *
 * Copyright (C) 2004-2005  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: simp911x.c
 *
 */

/*********************************************************
****************** USERS GUIDE ***************************
**********************************************************
This is the users guide for the LAN911x Simple Linux Driver.
LAN911x refers to the following chips.
	LAN9118
	LAN9117
	LAN9116
	LAN9115
	LAN9112
The following sections can be found below.
*  Revision History
*  Features
*  Driver Parameters
*  Tested Platforms
*  Rx Code Path
*  Tx Code Path

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

12/02/2004 Bryan Whitehead, Version 1.00
Initial release 

12/13/2004 Bryan Whitehead, Version 1.01
Added Tests Platforms section in comments.
Ran the code through the LINT tool, and made necessary
    changes.

12/17/2004 Bryan Whitehead, Version 1.02
Simplified synchronization policies.
Reduced Spin lock count to 2.
Added a comment block describing how every register is
  protected from concurrent access or why it does not 
  need protection.
Added support for one driver to handle multiple
  instances of the LAN911x

12/20/2004 Bryan Whitehead, Version 1.03
Removed GPL spin lock wrappers
Removed BWL spin locks
Added netperf scores to tested platforms, and kernel versions
Changed INSTANCE_COUNT to MAX_INSTANCES
Added support for the external Phy

12/21/2004 Bryan Whitehead, Version 1.04
Removed references to Stop lock
Changed MAX_INSTANCES to 8
Reduced some timeout lengths
change phy reset to use the reset bit in the PHY_BCR register
  this method will remain compatible with external phys
Elaborated on the comment for MacPhyAccessLock in PRIVATE_DATA

12/22/2004 Bryan Whitehead, Version 1.05
Changed initialization of SIMP911X and registered to a 
programmatic initialization in Simp911x_init_module
removed MULTI_INSTANCE_MODULE_PARM macro which didn't work right
   will use MODULE_PARM instead.

01/07/2005 Bryan Whitehead, Version 1.06
Safely disable IRQ in Simp911x_stop
Safely disable Tx queue in Simp911x_stop

01/25/2005 Bryan Whitehead, Version 1.07
Fixed Faulty define, TX_CMD_A_BUF_SIZE_
Fixed faulty define, TX_CMD_B_PKT_BYTE_LENGTH_
Increased Rx_FastForward, timeout to 500

02/03/2005 Bryan Whitehead, Version 1.08
Fixed a potential problem with regards to the
  use of multiple instances, the global variable
  Rx_TaskletParameter is now a global array designed 
  for use with multiple instances.
  NOTE: since we have no platform for testing
  multiple instances yet, the multi instance code
  used in this driver is for illustrative purposes only.
  Do keep in mind that it has not been tested. 

02/28/2005 Bryan Whitehead, Version 1.09
Updated Rx_CountErrors
	Only count length error if length/type field is set
	If there is a CRC error don't count length error or
	  multicast
Added date_code

03/01/2005 Bryan Whitehead, Version 1.10
Added support for LAN9112

05/23/2005 Bryan Whitehead, Version 1.11
Added Phy Work Around code.
  Enabled by defining USE_PHY_WORK_AROUND
  See section marked PHY WORK AROUND for changes.

05/25/2005 M. David Gelbman, Version 1.12
Added 10/100 LED1 Work Around code.
  Enabled by defining USE_LED1_WORK_AROUND
  See section marked LED1 WORK AROUND for changes.

############################################################
################### FEATURES ###############################
############################################################
Only minimum features are included. This is to allow for 
easy understanding of how to use the LAN911x chips

PIO is used for transmit and receive.
Link management
Multicast capable
Debug messages

############################################################
################## DRIVER PARAMETERS #######################
############################################################
The following are load time modifiable driver parameters.
They can be set when using insmod
Example:
# insmod simp911x.o lan_base=0xB4000000 irq=8

lan_base
    specifies the physical base location in memory where the 
    LAN911x can be accessed. If a LAN911x can not be found
    at the location specified then driver initialization 
    will fail.
        
irq
    specifies the irq number to use. If this number is 
    incorrect, then driver initialization will fail.
    
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
    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.

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.
	

###########################################################
################### TESTED PLATFORMS ######################
###########################################################
This driver has been tested on the following platforms.
The driver was loaded as a module with the following command
line.

	insmod simp911x.o lan_base=LAN_BASE irq=IRQ

Where LAN_BASE, and IRQ are replaced with appropriate
driver resources for the particular platform as indicated
below.

It should also be noted that the LAN911x may not be accessable
unless the bus as already been configured properly. Usually
this is done by the BIOS or some architecture initialization
code. Bus configuration is platform specific and therefore 
beyond the scope of this demonstration driver.
===========================================================
Platform: 
	SH3 SE01
Motherboard: 
	Hitachi/Renesas, MS7727SE01/02
SMSC LAN911x Board: 
	LAN9118 FPGA DEV BOARD, ASSY 6337 REV A
LAN911x:
	LAN9118
Linux Kernel Version:
	2.4.18
Driver Resources: 
	LAN_BASE=0xB4000000
	IRQ=8
netperf Scores:
	TCP RX:                  49.70 Mbps
	TCP TX:                  39.54 Mbps
	UDP RX -m1472 -w10 -b59: 52.08 Mbps
	UDP TX -m1472:           68.06 Mbps

===========================================================
Platform: 
	XSCALE
Motherboard:
	Intel Corp, MAINSTONE II MAIN BOARD REV 2.1
SMSC LAN911x Board:
	LAN9118 XSCALE FPGA DEV BOARD, ASSY 6343 REV A
LAN911x:
	LAN9118
Linux Kernel Version:
	2.4.21
Driver Resources:
	LAN_BASE=0xF2000000
	IRQ=198	
netperf Scores:
	TCP RX:                  58.97 Mbps
	TCP TX:                  88.04 Mbps
	UDP RX -m1472 -w10 -b61: 60.87 Mbps 
	UDP TX -m1472:           94.73 Mbps

###########################################################
##################### RX CODE PATH ########################
###########################################################
The purpose of this section is to describe how the driver
receives packets out of the LAN911x and passes them to the
Linux OS. Most functions in the Rx code path start with Rx_

During initialization (Simp911x_open) the function 
Rx_Initialize is called. This call enables interrupts for 
receiving packets.

When a packet is received the LAN911x signals an interrupt, 
which causes Simp911x_ISR to be called. The Simp911x_ISR function
is the main ISR which passes control to various handler routines.
One such handler routine that gets called is Rx_HandleInterrupt.

Rx_HandleInterrupt first checks to make sure the proper 
interrupt has been signaled (INT_STS_RSFL_). If it has not
it returns immediately. If INT_STS_RSFL_ has been signaled
then it schedules Rx_Tasklet which will shortly after call
Rx_ProcessPacketsTasklet to service the packets that have arrived.

The tasklet runs the following algorithm to service packets.

    An Rx status DWORD is read using Rx_PopRxStatus
    If there is an error 
        the packet is purged from the LAN911x
            data fifo with Rx_FastForward
    If there is no error 
        an sk_buff is allocated to receive the data
        The data is read into the sk_buff using PIO.
        After data is read the sk_buff is sent to linux using
            Rx_HandOffSkb
    The process repeats until Rx_PopRxStatus returns 0

The driver must also participate in Rx flow control because of
platform speed limitations. Rx flow control in the driver is handled
in the functions Rx_HandOffSkb, and Rx_PopRxStatus. The function
Rx_HandOffSkb calls netif_rx which returns a congestion level.
If any congestion is detected then Rx_HandOffSkb will set the
RxCongested flag. The next time the driver calls Rx_PopRxStatus it
will see the RxCongested flag is set and will not Pop a new status
off the RX_STATUS_FIFO, but rather it will disable and re-enable
interrupts. This action will cause the interrupt deassertion interval
to begin. The ISR will return, and not be called again until the 
deassertion interval has expired. This gives CPU time to linux so it
can handle the packets that have been sent to it and lower the
congestion level. In this case the driver voluntarily stops
servicing packets, which means the RX Data Fifo will fill up.
Eventually the hardware flow control will start up to slow down the
sender. Many times this will still result in an overflow of the 
Rx Data fifo and packets will be lost under heavy traffic conditions.
But if the driver did not release the CPU to linux, then linux would
drop almost all the packets. So it is better to let the packets be
lost on the wire, rather than over consuming resources to service
them.


###########################################################
##################### TX CODE PATH ########################
###########################################################
When Linux wants to transmit a packet it will call 
Simp911x_hard_start_xmit. This function performs some checks
then calles Tx_SendSkb to send the packet.

The basic sequence is this.
First Write TxCmdA and TxCmdB into the TX_DATA_FIFO.
Then Write the packet data into the TX_DATA_FIFO with 
    adjustments for offset and end alignment.
Then free the skb using dev_kfree_skb

Tx Flow control works like this.
If the free space in the TX_DATA_FIFO after writing the data
is determined to be less than about the size of one full size
packet then the driver can't be sure it can transmit the next
packet without overflowing. Therefore the driver turns off the 
Tx queue by calling netif_stop_queue. Then it prepares an interrupt
to be signaled when the free space in the TX_DATA_FIFO has risen 
to an acceptable level. When that level of free space has been 
reached the interrupt is signaled and the handler will turn on
the Tx queue by calling netif_wake_queue

Statistic counters are updated after about every 30 packets or
when linux calls Simp911x_get_stats

###########################################################
################### PHY WORK AROUND #######################
###########################################################
This section provides a brief overview of the changes necessary
to implement the phy work around.

First, the nature of the problem is this. During initialization
the phy gets reset. It has been found to be possible that
the phy will come out of reset in a state that may cause transmitted
packets to be inverted.

The fix for this problem is too run a phy loop back test after
a phy reset in order to detect inverted packets. If an inverted
packet is detected then the phy is reset again, and the loop back
test is repeated. If the loop back packet returns with out error,
then that is confirmation that the phy came out of reset properly,
so the code resumes normal initialization.

The loop back test was added to the function Phy_Initialize.
To see all necessary changes search for USE_PHY_WORK_AROUND

*/

#ifndef __KERNEL__
#	define __KERNEL__
#endif

#ifdef USING_LINT
#include "lint.h"
#else //not USING_LINT
#include <linux/config.h>
#include <linux/module.h>
#include <linux/init.h>
#include <linux/sched.h>
#include <linux/kernel.h>
#include <linux/slab.h>
#include <linux/ioport.h>
#include <linux/errno.h>
#include <linux/netdevice.h>
#include <linux/etherdevice.h>
#include <linux/delay.h>
#include <linux/mii.h>
#include <linux/timer.h>
#include <asm/irq.h>
#include <asm/dma.h>
#include <asm/bitops.h>
#include <linux/version.h>
#endif //not USING_LINT

static const char date_code[]="053105";

#define USE_PHY_WORK_AROUND
#define	USE_LED1_WORK_AROUND	// 10/100 LED link-state inversion