readme.txt

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

      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
    
tasklets
	A non zero value specifies that most of the receive work 
	should be done in a tasklet, thereby enabling other system interrupts.
	A zero value 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.
	

###########################################################
################# RX PERFORMANCE TUNING ###################
###########################################################

Under most real world conditions traffic is flow controlled at
the upper layers of the protocol stack. The most common example is 
TCP traffic. Even UDP traffic is usually flow controlled in the sense 
that the transmitter does not normally send continuous wirespeed traffic.
When high level flow control is in use, it usually produces the
best performance on its own with no intervention from the driver.
But if high level flow control is not in use, then the driver will be 
working as fast as it can to receive packets and pass them up to 
the OS. In doing so it will hog CPU time and the OS may drop packets
due to lack of an ability to process them. It has been found that
during these heavy traffic conditions, throughput can be significantly
improved if the driver voluntarily releases the CPU. Yes, this will
cause more packets to be dropped on the wire but a greater number
of packets are spared because the OS has more time to process them.

As of version 1.05 and later, the driver implements a new flow control
detection method that operates like this. If the driver detects an
excessive work load in the period of 100mS, then the driver
assumes there is insufficient flow control in use. Therefor it will 
turn on driver level flow control. Which significantly reduces the 
amount of time the driver holds the CPU, and causes more packets to
be dropped on the wire. So a balancing/tuning, needs to be performed
on each system to get the best performance under these conditions. 
If however the driver detects a tolerable work load in a period of 
100mS then it assumes flow control is being managed well and does 
not attempt to intervene by releasing the CPU. Under these conditions
the driver will naturally release the CPU to the OS, since the system
as a whole is keeping up with traffic.

Now that the background has been discussed, its necessary to talk 
about how the driver implements flow control. The method used is a 
work load model. This is similar but not exactly the same as 
throughput. Work load is the sum of all the packet sizes plus a constant
packet cost for each packet. This provides more balance. For instance
a stream of max size packets will give a large throughput with fewer
packets, while a stream of min size packets will give a low throughput
with many packets. Adding a per packet cost to the work load allows these
two cases to both activate and manage flow control. If work load only 
counted packet sizes then only a stream of max size packets would
activate flow control, while a stream of min size packets would not.

There are five primary parameters responsible for managing flow control.
They can be found in the FLOW_CONTROL_PARAMETERS structure. 
They are
	MaxThroughput, Represents the maximum throughput measured in a 
		100mS period, during an rx TCP_STREAM test.		
	MaxPacketCount, Represents the maximum packet count measured in a 
		100mS period, during an rx TCP_STREAM test.
	PacketCost, Represents the optimal per packet cost
	BurstPeriod, Represents the optimal burst period in 100uS units.
	IntDeas, This is the value for the interrupt deassertion period.
	    It is set to INT_DEAS field of the INT_CFG register.
The driver will call Platform_GetFlowControlParameters to get these
parameters for the specific platform and current configuration.
These parameters must be carefully choosen by the driver writer so
optimal performance can be achieved. Therefor it is necessary to 
describe how the driver uses each parameter.

The first three parameters MaxThroughput, MaxPacketCount, and PacketCost,
are used to calculate the secondary parameter, MaxWorkLoad according
to the following formula.
	MaxWorkLoad=MaxThroughput+(MaxPacketCount*PacketCost);
MaxWorkLoad represents the maximum work load the system can handle during
a 100mS period.
	The driver will use MaxWorkLoad and BurstPeriod to determine 
BurstPeriodMaxWorkLoad, which represents the maximum amount of work the 
system can handle during a single burst period. It is calculated as follows
	BurstPeriodMaxWorkLoad=(MaxWorkLoad*BurstPeriod)/1000;

Every 100mS the driver measures the CurrentWorkLoad by the following 
algorithm.

	At the beginning of a 100mS period
		CurrentWorkLoad=0;
		
	During a 100mS period CurrentWorkLoad is adjusted when a packet
	arrives according to the following formula.
		CurrentWorkLoad+=PacketSize+PacketCost;
		
	At the end of a 100mS period
		if(CurrentWorkLoad>((MaxWorkLoad*(100+ActivationMargin))/100)) 
		{
			if(!FlowControlActive) {
				FlowControlActive=TRUE;
				//Do other flow control initialization
				BurstPeriodCurrentWorkLoad=0;
			}
		}
		if(CurrentWorkLoad<((MaxWorkLoad*(100-DeactivationMargin))/100))
		{
			if(FlowControlActive) {
				FlowControlActive=FALSE;
				//Do other flow control clean up
				Enable Receiver interrupts
			}
		}

During periods where flow control is active, that is 
FlowControlActive==TRUE, the driver will manage flow control by the
following algorithm.

	At the end/beginning of a burst period
		if(BurstPeriodCurrentWorkLoad>BurstPeriodMaxWorkLoad) {
			BurstPeriodCurrentWorkLoad-=BurstPeriodMaxWorkLoad;
		} else {
			BurstPeriodCurrentWorkLoad=0;
		}
		Enable Receiver Interrupts;
		
	When checking if a packet arrives
		if(BurstPeriodCurrentWorkLoad<BurstPeriodMaxWorkLoad) {
			//check for packet normally
			BurstPeriodCurrentWorkLoad+=PacketSize+PacketCost;
		} else {
			//Do not check for packet, but rather
			//  behave as though there is no new packet.
			Disable Receiver interrupts
		}

This algorithm will allow the driver to do a specified amount
of work and then give up the CPU until the next burst period. Doing this
allows the OS to process all the packets that have been sent to it.

So that is generally how the driver manages flow control. For more
detail you can refer to the source code. Now it is necessary to 
describe the exact method for obtaining the optimal flow control 
parameters.

When obtaining the optimal flow control parameters it is important
to note the configuration you are using. Generally there are 8
configurations for each platform. They involve the following options
	DMA or PIO
	16 bit or 32 bit
	118/117 or 116/115
Some platforms may only use 16 bit mode. While other platforms may 
have a selectable clock rate. What ever the options are, every combination
should be identifiable, and Platform_GetFlowControlParameters should be
implemented to provide the correct flow control parameters. It is important
to be sure that the carefully selected parameters are applied to the
same configuration used during tuning.

Flow control tuning requires a publically available program called
netperf, and netserver, which are a client/server pair. These are built 
with the same make file and can be found on the web.

Fortunately, as of version 1.10, smsc911x and cmd911x supports an automated
tuning mechanism. The process takes about one hour and can be initiated as
follows

AUTOMATED TUNING:

Choose the configuration you want to tune. 
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.