/* fei82557End.c - END style Intel 82557 Ethernet network interface driver *//* Copyright 1989-2003 Wind River Systems, Inc. */#include "copyright_wrs.h"/*modification history--------------------01l,21mar03,rcs  removed #include "endNetBufLib.c" SPR# 8703901k,21mar03,rcs  unmasked interrupt after netJobAdd() failed SPR# 8703801j,28feb03,rcs  fixed polled mode. SPR#8643301i,24feb03,rcs  corrected for using pre-allocated memory SPR# 8635201h,13feb03,rcs  consolidated CFD writes in fei82557Encap.01g,13feb03,rcs  consolidated descriptor cachDmaMalloc s in fei82557InitMem().01f,07feb03,rcs  fixed diab compiler warnings.01e,05feb03,rcs  fixed RFD_LONG_WR double swap SPR# 86037 and added                 documentation for fei82557ShowRxRing and fei82557GetRUStatus01d,04feb03,pmr  fixed doc build error.01c,31jan03,m_h  IPv6 support01b,31jan03,jkf  removed logMsg() of pDrvCtrl value.01a,23jan03,rcs  created from target/src/drv/end/fei82557End.c, version 02r *//*DESCRIPTIONThis module implements an Intel 82557 and 82559 Ethernet network interface driver. (For the sake of brevity this document will only refer to the 82557.)This is a fast Ethernet PCI bus controller, IEEE 802.3 10Base-T and 100Base-T compatible. It also features a glueless 32-bit PCI bus master interface, fully compliant with PCI Spec version 2.1. An interface to MII compliant physical layer devices is built-in to the card. The 82557Ethernet PCI bus controller also includes Flash support up to 1 MByteand EEPROM support, altough these features are not dealt with in this driver.The 82557 establishes a shared memory communication system with the CPU,which is divided into three parts: the Control/Status Registers (CSR),the Command Block List (CBL) and the Receive Frame Area (RFA). The CSRis on chip and is either accessible with I/O or memory cycles, whereas theother structures reside on the host.The CSR is the main means of communication between the device and thehost, meaning that the host issues commands through these registerswhile the chip posts status changes in it, occurred as a result of thosecommands. Pointers to both the CBL and RFA are also stored in the CSR.The CBL consists of a linked list of frame descriptors through which individual action commands can be performed. These may be transmit commands as well as non-transmit commands, e.g. Configure or Multicastsetup commands. While the CBL list may function in two different modes,only the simplified memory mode is implemented in the driver.The RFA consists of a pair of linked list rings. The Receive Frame Descriptor(RFD) ring and the Receive Buffer Descriptor (RBD) ring. The RFDs hold the status of completed DMAs. The RBDs hold the pointers to the DMA buffers,refered to as clusters. When the device is initialized or restarted it is passed a pointer to an RFD.This RFD is considered to be the "first" RFD. This RFD holds a pointer to one of the RBDs. This RBD is then considered the "first" RBD. All other RFDs only have a NULL RBD pointer, actually 0xffffffff. Once the device is startedthe rings are traversed by the device independently. Either descriptor type RFD or RBD can have a bit set in it to indicate that it is the End of the List (EL). This is initially set in the RBD descriptor immediately before the first RBD. This acts as a stop which prevents the DMA engine from wrapping around the ring and encountering a used descriptor. This is an unallowed condition and results in the device stopping operationwithout an interupt or and indication of failure. When the EL RBD is encountered the the device goes into the receive stall state. The driver must then restart the device. To reduce, if not eliminate, the occurence of this costly, time consuming operation, the driver continually advances the EL to the last cleared RBD. Then when the driver services an incomming frame itclears the RFD RBD pair and advances the EL. If the driver is not able to service an incomming frame, because of a shortage of resources such as clusters, the driver will throw that frame away and clear the RFD RBD pair and advance EL.         Because the rings are independently traversed by the device it is imperativethat they be kept in sync. Unfortunately, there is no indication from oneor the other as to which descriptor it is pared with. It is left to the driverto keep track of which discriptor goes with its counter part. If this syncronization is lost then the performance of the driver will be greatly impared or worse. To keep this syncronization this driver imbeds the RBD descriptors in tags. To do this it utilizes memory that would otherwise have been wasted. The DMA engine purportedly works most efficiently when thedescriptors are on a 32 byte boundry. The descriptors are only 16 bytes so there are 16 bytes to work with. The RBD_TAG s have as their first 16 bytesthe RBD itself, then it holds the RFD pointer to its counter part, a pointer to itself, a 16 bit index, a 16 bit next index, and 4 bytes of spare. This arrangement allows the driver to traverse only the RBD ring and discover the corresponding RFD through the RBD_TAG and guaranteeing sycronization.     The driver is designed to be moderately generic, operating unmodifiedacross the range of architectures and targets supported by VxWorks.  To achieve this, this driver must be given several target-specific parameters, and some external support routines must be provided.  These parameters, and the mechanisms used to communicate them to the driver, are detailed below.BOARD LAYOUTThis device is on-board.  No jumpering diagram is necessary.EXTERNAL INTERFACEThe driver provides the standard external interface, fei82557EndLoad(), whichtakes a string of colon separated parameters. The parameters should bespecified in hexadecimal, optionally preceeded by "0x" or a minus sign "-".The parameter string is parsed using strtok_r() and each parameter isconverted from a string representation to binary by a call tostrtoul(parameter, NULL, 16).The format of the parameter string is:"<memBase>:<memSize>:<nTfds>:<nRfds>:<flags>:<offset>:<maxRxFrames>:<clToRfdRatio>:<nClusters>"In addition, the two global variables 'feiEndIntConnect' and 'feiEndIntDisconnect' specify respectively the interrupt connect routine and the interrupt disconnect routine to be used depending on the BSP. The former defaults to intConnect() and the user can override this to use any other interrupt connect routine (say pciIntConnect()) in sysHwInit() or any device specific initialization routine called in sysHwInit(). Likewise, the latter is set by default to NULL, but it may be overridden in the BSP in the same way. TARGET-SPECIFIC PARAMETERS.IP <memBase>This parameter is passed to the driver via fei82557EndLoad().The Intel 82557 device is a DMA-type device and typically sharesaccess to some region of memory with the CPU.  This driver is designedfor systems that directly share memory between the CPU and the 82557.This parameter can be used to specify an explicit memory region for useby the 82557.  This should be done on targets that restrict the 82557to a particular memory region. Since use of this parameter indicates that the device has limited access to this specific memory region all buffers and descriptors directly accessed by the device (RFDs, RBDs, CFDs, and clusters) must be carved from this region. Since the transmit buffers must reside in this region the driver will revert to using simple mode buffering for transmit meaning that zero copy transmit is not supported. This then requires that there be enough space for clusters to be attached to the CFDs. The minimum memory requirement is for 32 bytes for all descriptors plusat lease two 1536 byte clusters for each RFD and one 1536 byte cluster foreach CFD. Also, it should be noted that this memory must be non-cached. The constant `NONE' can be used to indicate that there are no memory limitations, in which case the driver will allocate cache aligned memory for its use using memalign().  .IP <memSize>The memory size parameter specifies the size of the pre-allocated memoryregion. If memory base is specified as NONE (-1), the driver ignores thisparameter. Otherwise, the driver checks the size of the provided memory region is adequate with respect to the given number of descriptors and clusters specified. The amount of memory allocated must be enough to hold the RFDs, RBDs, CFDs and clusters. The minimum memory requirement is for 32 bytes each for all descriptors, 32 bytes each for alignment of the descriptor types (RFDs, RBDs, and CFDs),  plus at least two 1536 byte clusters for each RFD and one 1536 byte cluster for each CFD. Otherwise the End Load routine will return ERROR. The number of clusters can be specified by either passing a value in the nCluster parameter, in which case the nCluster value must be at least nRFDs * 2, or by setting the cluster to RFD ratio (clToRfdRatio) to a number equal or greater than 2.   .IP <nTfds>This parameter specifies the number of transmit descriptor/buffers to beallocated. If this parameter is less than two, a default of 64 is used..IP <nRfds>This parameter specifies the number of receive descriptors to beallocated. If this parameter is less than two, a default of 128 is used..IP <flags>User flags may control the run-time characteristics of the Ethernetchip. Not implemented..IP <offset>Offset used to align IP header on word boundary for CPUs that need long wordaligned access to the IP packet (this will normally be zero or two). This parameter is optional, the default value is zero..IP <deviceId>This parameter is used to indicate the specific type of device being used,the 82557 or subsequent.  This is used to determine if features which were introduced after the 82557 can be used. The default is the 82557. If this is set to any value other than ZERO (0), NONE (-1), or FEI82557_DEVICE_ID (0x1229)it is assumed that the device will support features not in the 82557.   .IP <maxRxFrames>This parameter limits the number of frames the receive handler will service in one pass. It is intended to prevent the tNetTask from hoging the CPU andstarving applications. This parameter is optional, the default value is nRFDs * 2.   .IP <clToRfdRatio>Cluster To RFD Ratio sets the number of clusters as a ratio of nRFDs. The minimum setting for this parameter is 2. This parameter is optional, the default value is 5..IP <nClusters>Number of clusters to allocate. This value must be  at least nRFD * 2.If this value is set then the <clToRfdRatio> is ignored. This parameter is optional, the default is nRFDs * clToRfdRatio. .LP EXTERNAL SUPPORT REQUIREMENTSThis driver requires one external support function:.CSSTATUS sys557Init (int unit, FEI_BOARD_INFO *pBoard).CEThis routine performs any target-specific initializationrequired before the 82557 device is initialized by the driver.The driver calls this routine every time it wants to [re]initializethe device.  This routine returns OK, or ERROR if it fails..LPSYSTEM RESOURCE USAGEThe driver uses cacheDmaMalloc() to allocate memory to share with the 82557.The size of this area is affected by the configuration parameters specifiedin the fei82557EndLoad() call. Either the shared memory region must be non-cacheable, or elsethe hardware must implement bus snooping.  The driver cannot maintaincache coherency for the device because fields within the commandstructures are asynchronously modified by both the driver and the device,and these fields may share the same cache line.TUNING HINTSThe adjustable parameters are:The number of TFDs and RFDs that will be created at run-time. These parameters are given to the driver when fei82557EndLoad() is called. There is one TFD and one RFD associated with each transmitted frame and each received frame respectively. For memory-limited applications, decreasing the number of TFDs and RFDs may be desirable. Increasing the number of TFDs will provide no performance benefit after a certain point. Increasing the number of RFDs will provide more buffering before packets are dropped.  This can be useful if there are tasks running at a higher priority than tNetTask. The maximum receive frames <maxRxFrames>. This parameter will allow the driver to service fixed amount of in comming traffic before forcing the receive handler to relenquish the CPU. This prevents the possible scenerio of the receive handler starving the application.The parameters <clToRfdRatio> and <nClusters> control the number of clusters  created which is the major portion of the memory allocated by the driver. For memory-limited applications, decreasing the number clustersmay be desirable. However, this also will probably result in performancedegradation.    ALIGNMENTSome architectures do not support unaligned access to 32-bit data items. Onthese architectures (eg ARM and MIPs), it will be necessary to adjust theoffset parameter in the load string to realign the packet. Failure to do sowill result in received packets being absorbed by the network stack, althoughtransmit functions should work OK. Also, some architectures do not supportSNOOPING, for these architectures the utilities FLUSH and INVALIDATE areused for cache coherency of DMA buffers (clusters). These utilities depend on the buffers being cache line aligned and being cache line multiple. Therefore, if memory for these buffers is pre-allocated then it is imperitivethat this memory be cache line aligned and being cache line multiple. SEE ALSO: ifLib,.I "Intel 82557 User's Manual,".I "Intel 32-bit Local Area Network (LAN) Component User's Manual"*/#include "vxWorks.h"#include "wdLib.h"#include "iv.h"#include "vme.h"#include "lstLib.h"#include "semLib.h"#include "sys/times.h"#include "net/mbuf.h"#include "net/unixLib.h"#include "net/protosw.h"#include "sys/socket.h"#include "sys/ioctl.h"#include "errno.h"#include "memLib.h"#include "intLib.h"#include "net/route.h"#include "iosLib.h"#include "errnoLib.h"#include "vxLib.h"    /* from if_fei.c */#include "private/funcBindP.h"#include "cacheLib.h"#include "logLib.h"#include "netLib.h"#include "stdio.h"#include "stdlib.h"#include "sysLib.h"#include "taskLib.h"#include "msgQLib.h"#include "net/systm.h"#include "net/if_subr.h"#include "drv/end/fei82557End.h"#include "drv/pci/pciIntLib.h"#undef ETHER_MAP_IP_MULTICAST#include "etherMultiLib.h"#include "end.h"#define    END_MACROS#include "endLib.h"#ifdef WR_IPV6#include "adv_net.h"#endif /*WR_IPV6*//* defines *//* Driver debug control */#undef DRV_DEBUG557/* Driver debug control */#ifdef DRV_DEBUG557#define DRV_DEBUG_OFF		0x0000#define DRV_DEBUG_RX		0x0001#define DRV_DEBUG_TX		0x0002#define DRV_DEBUG_POLL		(DRV_DEBUG_POLL_RX | DRV_DEBUG_POLL_TX)#define DRV_DEBUG_POLL_RX    	0x0004#define DRV_DEBUG_POLL_TX    	0x0008#define DRV_DEBUG_LOAD		0x0010#define DRV_DEBUG_IOCTL		0x0020#define DRV_DEBUG_INT		0x0040#define DRV_DEBUG_START    	0x0080#define DRV_DEBUG_DUMP    	0x0100#define DRV_DEBUG_PHY		0x0200#define DRV_DEBUG_ALL    	0xffffint	fei82557Debug = DRV_DEBUG_ALL;#define DRV_LOG(FLG, X0, X1, X2, X3, X4, X5, X6)			\    do {								\    if (fei82557Debug & FLG)						\	if (_func_logMsg != NULL)					\	    _func_logMsg (X0, (int)X1, (int)X2, (int)X3, (int)X4,	\			    (int)X5, (int)X6);				\    } while (0)#else /* DRV_DEBUG557 */#define DRV_LOG(FLG, X0, X1, X2, X3, X4, X5, X6)#define DRV_PRINT(FLG, X)#endif /* DRV_DEBUG557 *//* general macros for reading/writing from/to specified locations */