readme.txt

smsc911x 网卡驱动 This the users/programmers guide for the LAN911x Linux Driver The following sections

Install the driver on your target platform with your choosen configuration.
	insmod smsc911xd.o 
	ifconfig eth1 192.1.1.118
load servers on target platform
	netserver
	cmd911x -cSERVER
On host platform, make sure the netperf executable is 
located in the same directory and the cmd911x executable. While in that
directory run the following.
	cmd911x -cTUNER -H192.1.1.118
This command, if successful, will begin the one hour tuning process.
At the end you will get a dump of the optimal flow control parameters.
The key parameters needed are
    MaxThroughput
    MaxPacketCount
    PacketCost
    BurstPeriod
    IntDeas
These value must be assigned in Platform_GetFlowControlParameters to
	flowControlParameters->MaxThroughput
	flowControlParameters->MaxPacketCount
	flowControlParameters->PacketCost
	flowControlParameters->BurstPeriod
	flowControlParameters->IntDeas
Make sure the Platform_GetFlowControlParameters checks the current configuration
and will only set those parameters if the current configuration matches the
configuration you tuned with.

Next start over but choose a configuration you haven't already tuned.
   

MANUAL TUNING:
In the off chance that the automated tuning fails to work properly, you may
use the following manual tuning procedure.

STEP 1:
	Select a configuration. That is choose between DMA or PIO, 16 bit or 
	32 bit, 118/117 or 116/115.
	Make sure there is a direct connection between the target platform
	and the host platform. Do not use a hub, or switch. The target
	platform is the platform that will run this driver. The host platform
	should be a PC easily capable of sending wire speed traffic.

STEP 2:
	load the driver on the target platform with the following commands
		insmod smsc911x.o max_work_load=0 int_deas=ID
		ifconfig eth1 192.1.1.118
		netserver
	ID will be replated by the number you will be adjusting to obtain the
		best throughput score in STEP 3, initially a goog number to start
		with is 0.

STEP 3:
	On  the host platform run the following command
		netperf -H192.1.1.118 
	Examine the output. The goal is to maximize the number on the 
		Throughput column.
	If you are satisfied with the throughput remember the ID number
		you used and move on to STEP 4.
	If you would like to try improving the throughput
		unload the driver on the target with
			ifconfig eth1 down
			rmmod smsc911x
		goto STEP 2 and use a different value for ID

	
STEP 4:
	unload the driver with 
		ifconfig eth1 down
		rmmod smsc911x
	load driver on the target platform with the following commands
		insmod smsc911x.o max_work_load=0 int_deas=ID
		ifconfig eth1 192.1.1.118
		netserver
	NOTE: the driver will be making traffic measurements. Therefor
		it is important not to insert any steps between 4 and 6.
		
STEP 5:	
	run netperf on the host platform
		netperf -H192.1.1.118
	repeat two more times.
	
STEP 6:
	on target platform run the following
		cmd911x -cGET_FLOW
	Many variables will be displayed. Two of them are measurements we need.
	You can set the following two parameters as follows.
		MaxThroughput  = RxFlowMeasuredMaxThroughput;
		MaxPacketCount = RxFlowMeasuredMaxPacketCount;
		
STEP 7:
	Unload the driver on target platform with
		ifconfig eth1 down
		rmmod smsc911x
	Apply the parameters obtained in STEP 6 and 2/3 to the appropriate location,
		given the configuration choosen in STEP 1, in
		Platform_GetFlowControlParameters. The parameters for your
		choosen configuration should be set as follows
			MaxThroughput = (RxFlowMeasuredMaxThroughput from step 6);
			MaxPacketCount = (RxFlowMeasuredMaxPacketCount from step 6);
			PacketCost=0; //temporarily set to 0
			BurstPeriod=100; //temporarily set to 100
			IntDeas= (ID from step 2/3).
	recompile driver.
		
STEP 8:
	Again make sure your still using the same configuration you selected
		in STEP 1.
	Load recompiled driver on target platform with the following commands
		insmod smsc911x.o burst_period=BP
		ifconfig eth1 192.1.1.118
	BP will be replaced by the number you will be adjusting to obtain the
		best throughput score in STEP 9, initially a good number to 
		start with is 100.

STEP 9:
	On Host platform run the following command
		netperf -H192.1.1.118 -tUDP_STREAM -l10 -- -m1472
	Examine the output.	The goal is to maximize the lower 
		number on the Throughput column.
	If you are satisfied with the throughput remember the BP number 
		you used and move on to STEP 10.
	If you would like to try improving the throughput
		unload the driver on the target with
			ifconfig eth1 down
			rmmod smsc911x
		goto STEP 8 and use a different value for BP.
		
STEP 10:
	unload the driver on target platform
		ifconfig eth1 192.1.1.118 down
		rmmod smsc911x
	Again make sure your still using the same configuration you selected
		in STEP 1.
	Load the recompiled driver from STEP 7 on target platform with 
		insmod smsc911x.o burst_period=BP packet_cost=PC
		ifconfig eth1 192.1.1.118
	BP will be replaced with the value you settled on in STEP 8/9.
	PC will be replaced by the number you will be adjusting to 
		obtain the best throughput score in STEP 11, typically PC ends 
		up somewhere between 100 and 200.

STEP 11:
	On Host platform run the following command
		netperf -H192.1.1.118 -tUDP_STREAM -l10 -- -m16
	Examine the output. The goal is to maximize the lower
		number on the Throughput column.
	If you are satisfied with the throughput remember the PC number
		you used and move on the STEP 12.
	If you would like to try improving the throughput
		unload the driver on the target with
			ifconfig eth1 down
			rmmod smsc911x
		goto STEP 10 and use a different value for PC
		
STEP 12:
	Apply the parameters to the appropriate location, given the
	configuration choosen in step 1, in Platform_GetFlowControlParameters.
		PacketCost= (PC from step 10/11);
		BurstPeriod= (BP from step 8/9);
	recompile driver.
	Now the values you applied will be the default values used when that
		same configuration is used again.
	Goto STEP 1 and choose a configuration you have not yet tuned.
	
###########################################################
################### TESTED PLATFORMS ######################
###########################################################
This driver has been tested on the following platforms.
The driver was loaded as a module with the following command
line.

	insmod smsc911x.o 

===========================================================
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
	
===========================================================
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	
	
###########################################################
##################### 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 (Smsc911x_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 Smsc911x_ISR to be called. The Smsc911x_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 it has been signaled then it decides
if it should use PIO or DMA to read the data.

In both cases the process is like this
    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 or DMA.
        After data is read the sk_buff is sent to linux using
            Rx_HandOffSkb
    The process continues until Rx_PopRxStatus returns 0
    
DMA is a little more complicated than PIO because it is written
to take advantage of concurrent processing. To get as much useful
work done as possible while a DMA operation is in progress.
Therefor DMA has the best performance boost when there are 
several packets to service on a single call to Rx_HandleInterrupt

This is the purpose of the INT_DEAS field of INT_CFG. When that
field is set (using the driver parameter int_deas or platform macro
PLATFORM_INT_DEAS) it forces interrupts to be paced, so more packets
can arrive before a single call to the ISR. 

The LAN911x has been proven to receive at about 94Mbps on the
xscale platform. However other platforms run slower and require
some means of flow control. Rx flow control is built into the 
LAN911x. It is configured by writing the AFC_CFG register. The 
user can set this value at load time using the afc_cfg parameter.

Basically it works like this. If the Rx Data fifo fills up to
a level specified by AFC_HI in AFC_CFG then the LAN911x will begin 
flow control. If the link is half duplex then the LAN911x will
exert back pressure by forcing a collision on the wire when a
packet is arriving. This will cause the sender to retransmit later.
If the link is full duplex then the LAN911x will transmit a Pause
frame requesting the partner to stop sending packets. Then when 
the Rx Data fifo drops to AFC_LO in AFC_CFG then the LAN911x will 
stop exerting back pressure in half duplex, or in full duplex it 
will transmit another pause frame that lets the partner know it 
can start sending packets again. See the LAN911x specification
for more information. But all of this is done with out the help
of the driver.

Still the driver must 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 
Smsc911x_hard_start_xmit. This function performs some checks
then calles Tx_SendSkb to send the packet.

Tx_SendSkb works with PIO or DMA depending on the selected
mode. 

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

DMA is a little more complicated than PIO because it is written
to take advantage of concurrent processing. To get as much useful
work done as possible while a DMA operation is in progress.
Therefor DMA has the best performance boost when there are
a burst of large packets to transmit.

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. Therefor the driver turns off the 
Tx queue by calling Tx_StopQueue. 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 Tx_WakeQueue

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

###########################################################
########## PLATFORM INTERFACE DESCRIPTIONS ################
###########################################################
The platform interface provides a platform independent
interface for the driver (smsc911x.c) This interface
simplifies the task of porting the driver to other platforms.