readme.txt

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

All functions that start with Platform_ are part of the 
platform interface. All macros that start with PLATFORM_
are part of the platform interface.

Below are descriptions of PLATFORM_ macros.
for examples of usage see sh3.h, xscale.h or peaks.h

PLATFORM_CACHE_LINE_BYTES
      This macro is set to the size of a cache line in bytes.
      It is used with dma operations to insure cache line 
          alignment which generally improves dma efficiency
      It is also used to insure that the IP header of received
          packets will be aligned on a cache line boundary
          
PLATFORM_IRQ_POL
      This macro is set to 0 or 1 and indicates the default 
      value the driver will use when setting the IRQ_POL bit
      of the INT_CFG register. The user can override this 
      value at load time by setting the driver parameter irq_pol.
      
PLATFORM_IRQ_TYPE
      This macro is set to 0 or 1 and indicates the default
      value the driver will use when setting the IRQ_TYPE bit
      of the INT_CFG register. The user can override this
      value at load time by setting the driver parameter irq_type.
      
PLATFORM_INT_DEAS
      This macro indicates the default value the driver will 
      use when setting the INT_DEAS field of the INT_CFG register.
      The user can override this value at load time by setting
      the driver parameter int_deas.
        
PLATFORM_IRQ
      This macro indicates the default irq the driver will
      use when requesting an ISR.
      The user can override this value at load time by setting
      the driver parameter irq.
         
PLATFORM_RX_DMA
      This macro indicates the default dma channel to use for
      receiving packets. It may also be set to the following
      macros
         TRANSFER_PIO = 256
             the driver will not use dma. It will use PIO.
         TRANSFER_REQUEST_DMA = 255
             the driver will call the Platform_RequestDmaChannel
             to get an available dma channel
      The user can override this value at load time by setting
      the driver parameter rx_dma.
      
PLATFORM_TX_DMA
      This macro indicates the default dma channel to use for
      transmitting packets. It may also be set to the following
      macros
         TRANSFER_PIO = 256
             the driver will not use dma. It will use PIO.
         TRANSFER_REQUEST_DMA = 255
             the driver will call the Platform_RequestDmaChannel
             to get an available dma channel
      The user can override this value at load time by setting
      the driver parameter

PLATFORM_DMA_THRESHOLD
      This macro indicates the default value for dma_threshold.
      This value 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 platform specific header files (sh3.h, peaks.h, and xscale.h)
must also define the platform specific data structure
PLATFORM_DATA, and its pointer PPLATFORM_DATA.
this structure is passed to almost every Platform_ function. It
allows the platform layer to maintain its own context information.

The following are descriptions of the Platform_ functions
for examples of usage see the files sh3.c, peaks.c, or xscale.c

/************************************************************
FUNCTION: Platform_Initialize
PARAMETERS:
	platformData, pointer to platform specified data structure
	dwLanBase,	user specified physical base address for the LAN911x
		= 0, let this function decide
	dwBusWidth,     
		= 16, user specifies 16 bit mode operation, bypass autodetection
		= 32, user specifies 32 bit mode operation, bypass autodetection
		= any other value, driver should auto detect bus width
DESCRIPTION:
    This is the first Platform_xxx function that will be called
	This function will initialize the PLATFORM_DATA structure.
	This function will prepare the system to access the LAN911x.
	It will properly initialize the bus and return the virtual 
	memory location where the LAN911x can be access.
RETURN VALUE:
	0 = failed,
	any other value is the virtual base address where the LAN911x 
	   can be accessed 
************************************************************/
DWORD Platform_Initialize(
	PPLATFORM_DATA platformData,
	DWORD dwLanBase,
	DWORD dwBusWidth);
	
/***********************************************************
FUNCTION: Platform_Is16BitMode
PARAMETER:
	platformData, pointer to platform specific data structure
RETURN VALUE:
	TRUE if the platform is configured for 16 bit mode
	FALSE if the platform is configured for 32 bit mode
NOTE: this function is not currently used. 
***********************************************************/
BOOLEAN Platform_Is16BitMode(
	PPLATFORM_DATA platformData);

/************************************************************
FUNCTION: Platform_RequestIRQ
DESCRIPTION:
    Used to request and set up the ISR
PARAMETERS:
	platformData, pointer to platform specific data structure
	dwIrq, 
	  = 0xFFFFFFFF, let this function decide what IRQ to use
	  = any other value is the IRQ requested by the user
	pIsr, pointer to the ISR, to be registered.
	dev_id, pointer to the driver specific structure
	   used when registering the ISR with Linux
RETURN VALUE:
    TRUE if successful
	FALSE is unsuccessful
************************************************************/
BOOLEAN Platform_RequestIRQ(
	PPLATFORM_DATA platformData,
	DWORD dwIrq,
	void (*pIsr)(int irq,void *dev_id,struct pt_regs *regs),
	void *dev_id);

/***********************************************************
FUNCTION: Platform_CurrentIRQ
PARAMETERS:
    platformData, pointer to platform specific data structure
RETURN VALUE:
	The IRQ number actually used by Platform_RequestIRQ
	  This may be different than the requested IRQ
***********************************************************/
DWORD Platform_CurrentIRQ(
	PPLATFORM_DATA platformData);

/**********************************************************
FUNCTION: Platform_FreeIRQ
PARAMETERS:
    platformData, pointer to platform specific data structure
DESCRIPTION:
    uninstalls the ISR installed from Platform_RequestIRQ
**********************************************************/
void Platform_FreeIRQ(
	PPLATFORM_DATA platformData);

/*********************************************************
FUNCTION: Platform_IsValidDmaChannel
PARAMETERS:
	dwDmaCh, the dma channel number to test for validity
DESCRIPTION:
    This function is used to test the validity of the 
    channels request with parameters rx_dma, and tx_dma
RETURN VALUE:
	TRUE if the dma channel may be used
	FALSE if the dma channel may not be used
NOTE: this function does not use PLATFORM_DATA because
    it is called before the driver allocates memory for
    PLATFORM_DATA
*********************************************************/
BOOLEAN Platform_IsValidDmaChannel(DWORD dwDmaCh);

/********************************************************
FUNCTION: Platform_DmaInitialize
PARAMETERS:
    platformData, pointer to the platform specific data structure
	dwDmaCh, the Dma channel to initialize
RETURN VALUE:
	TRUE, on Success
	FALSE, on Failure
********************************************************/
BOOLEAN Platform_DmaInitialize(
	PPLATFORM_DATA platformData,
	DWORD dwDmaCh);

/********************************************************
FUNCTION: Platform_DmaDisable
PARAMETERS:
	platformData, pointer to the platform specific data structure
	dwDmaCh, the Dma channel to disable
RETURN VALUE:
	TRUE on success
	FALSE on failure
********************************************************/
BOOLEAN Platform_DmaDisable(
	PPLATFORM_DATA platformData,
	const DWORD dwDmaCh);

/*******************************************************
FUNCTION: Platform_CacheInvalidate
PARAMETERS:
	platformData, pointer to the platform specific data structure
	pStartAddress, the starting virtual address of the region
	dwLengthInBytes, the length in bytes of the region to invalidate
DESCRIPTION:
	Invalidates a specified memory region if it exists in cache.
	  Does not necessarily write the data back to memory.
*******************************************************/
void Platform_CacheInvalidate(
	PPLATFORM_DATA platformData,
	const void * const pStartAddress,
	const DWORD dwLengthInBytes);

/*******************************************************
FUNCTION: Platform_CachePurge
PARAMETERS:
    platformData, pointer to the platform specific data structure
	pStartAddress, the starting virtual address of the region
	dwLengthInBytes, the length in bytes of the region to purge
DESCRIPTION:
    Writes back data to a specified memory region if it 
      exists in cache.
*******************************************************/
void Platform_CachePurge(
	PPLATFORM_DATA platformData,
	const void * const pStartAddress,
	const DWORD dwLengthInBytes);

/******************************************************
FUNCTION: Platform_RequestDmaChannel
PARAMETERS:
	platformData, pointer to the platform specific data structure
DESCRIPTION:
	If the OS supports Dma Channel allocation then this function
	  will use that support to reserve a dma channel.
	If the OS does not support Dma Channel allocation, or a
	  channel can not be reserved then this function 
	  will return TRANSFER_PIO
RETURN VALUE:
	returns the DMA channel number that has been reserved
	if a channel can not be reserved then return TRANSFER_PIO
******************************************************/
DWORD Platform_RequestDmaChannel(
	PPLATFORM_DATA platformData);

/*****************************************************
FUNCTION: Platform_ReleaseDmaChannel
PARAMETERS:
	platformData, pointer to the platform specific data structure
	dwDmaChannel, the Dma channel number to be released
DESCRIPTION:
	Releases the DMA channel specified by dwDmaChannel,
	  which was previously returned by Platform_RequestDmaChannel
    If the OS supports it this function will notify the OS
	  that the dma channel is free to be used by other devices
******************************************************/
void Platform_ReleaseDmaChannel(
	PPLATFORM_DATA platformData,
	DWORD dwDmaChannel);

/*****************************************************
FUNCTION: Platform_DmaStartXfer
PARAMETERS:
    platformData, pointer to the platform specific data structure
    pDmaXfer, pointer to DMA_XFER structure
	    which describes the requested transfer
DESCRIPTION:
    Begins a new dma transfer,
	Should not be called if another transfer is in progress
RETURN VALUE:
    TRUE if dma has begun the transfer
	FALSE for any error
******************************************************/
BOOLEAN Platform_DmaStartXfer(
	PPLATFORM_DATA platformData,
	const DMA_XFER * const pDmaXfer);

/*******************************************************
FUNCTION: Platform_DmaGetDwCnt
PARAMETERS:
    platformData, pointer to the platform specific data structure
	dwDmaCh, Dma channel number
RETURN VALUE:
    0, if the DMA channel is ready to handle another 
	   request from Platform_DmaStartXfer
   non zero, is the number of DWORDS left for the 
       dma channel to transfer
*******************************************************/
DWORD Platform_DmaGetDwCnt(
	PPLATFORM_DATA platformData,
	const DWORD dwDmaCh);

/******************************************************
FUNCTION: Platform_DmaComplete
PARAMETERS:
    platformData, pointer to platform specific data structure
	dwDmaCh, dma channel number
DESCRIPTION:
	Waits for the specified dma channel to finish 
	transfering data. Upon return the dma channel should
	be ready to handle another request from 
	Platform_DmaStartXfer
	This function should be the same as waiting for 
	Platform_DmaGetDwCnt to return 0
******************************************************/
void Platform_DmaComplete(
	PPLATFORM_DATA platformData,
	const DWORD dwDmaCh);

/*****************************************************
FUNCTION: Platform_GetFlowControlParameters
PARAMETERS:
	platformData, pointer to platform specific data structure
	flowControlParameters, pointer to structure which receives 
	     the flow control parameters.
    useDma, flag which specifies whether to get flow control
         parameters for PIO(FALSE) or DMA(TRUE). 
DESCRIPTION:
	fills the structure pointed to by flowControlParameters,
	with the appropriate flow control parameters for the 
	current combination of ((117/118) or (116/115)), 
	(16 or 32 bit mode), and (PIO or DMA).
******************************************************/
void Platform_GetFlowControlParameters(
	PPLATFORM_DATA platformData,
	PFLOW_CONTROL_PARAMETERS flowControlParameters,
	BOOLEAN useDma);