VxWorks Reference Manual : Libraries
fei82557End - END style Intel 82557 Ethernet network interface driver
fei82557EndLoad( ) - initialize the driver and device
fei82557DumpPrint( ) - Display statistical counters
fei82557ErrCounterDump( ) - dump statistical counters
This module implements an Intel 82557 Ethernet network interface driver. 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 82557 Ethernet PCI bus controller also includes Flash support up to 1 MByte and 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 CSR is on chip and is either accessible with I/O or memory cycles, whereas the other structures reside on the host.
The CSR is the main means of communication between the device and the host, meaning that the host issues commands through these registers while the chip posts status changes in it, occurred as a result of those commands. 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 Multicast setup commands. While the CBL list may function in two different modes, only the simplified memory mode is implemented in the driver.
The RFA is a linked list of receive frame descriptors. Only support for the simplified memory mode is granted. In this model, the data buffer immediately follows the related frame descriptor.
The driver is designed to be moderately generic, operating unmodified across 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.
This device is on-board. No jumpering diagram is necessary.
The driver provides the standard external interface, fei82557EndLoad( ), which takes a string of colon separated parameters. The parameters should be specified in hexadecimal, optionally preceeded by "0x" or a minus sign "-".
The parameter string is parsed using strtok_r( ) and each parameter is converted from a string representation to binary by a call to strtoul(parameter, NULL, 16).
The format of the parameter string is:
"memBase:memSize:nTfds:nRfds:flags:offset"
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.
- memBase
- This parameter is passed to the driver via fei82557EndLoad( ).
The Intel 82557 device is a DMA-type device and typically shares access to some region of memory with the CPU. This driver is designed for systems that directly share memory between the CPU and the 82557.
This parameter can be used to specify an explicit memory region for use by the 82557. This should be done on targets that restrict the 82557 to a particular memory region. The constant NONE can be used to indicate that there are no memory limitations, in which case the driver will allocate cache safe memory for its use using cacheDmaAlloc( ).
- memSize
- The memory size parameter specifies the size of the pre-allocated memory region. If memory base is specified as NONE (-1), the driver ignores this parameter. Otherwise, the driver checks the size of the provoded memory region is adequate with respect to the given number of Command Frame Descriptor and Receive Frame Descriptor.
- nTfds
- This parameter specifies the number of transmit descriptor/buffers to be allocated. If this parameter is less than two, a default of 32 is used.
- nRfds
- This parameter specifies the number of receive descriptor/buffers to be allocated. If this parameter is less than two, a default of 32 is used. In addition, four times as many loaning buffers are created. These buffers are loaned up to the network stack. When loaning buffers are exhausted, the system begins discarding incoming packets. Specifying 32 buffers results in 32 frame descriptors, 32 reserved buffers and 128 loaning buffers being created from the system heap.
- flags
- User flags may control the run-time characteristics of the Ethernet chip. Not implemented.
- offset
- Offset used to align IP header on word boundary for CPUs that need long word aligned access to the IP packet (this will normally be zero or two). This field is optional, the default value is zero.
This driver requires one external support function:
STATUS sys557Init (int unit, FEI_BOARD_INFO *pBoard)This routine performs any target-specific initialization required before the 82557 device is initialized by the driver. The driver calls this routine every time it wants to [re]initialize the device. This routine returns OK, or ERROR if it fails.
The driver uses cacheDmaMalloc( ) to allocate memory to share with the 82557. The size of this area is affected by the configuration parameters specified in the fei82557EndLoad( ) call.
Either the shared memory region must be non-cacheable, or else the hardware must implement bus snooping. The driver cannot maintain cache coherency for the device because fields within the command structures are asynchronously modified by both the driver and the device, and these fields may share the same cache line.
The only 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 the net task.
Some architectures do not support unaligned access to 32-bit data items. On these architectures (eg PowerPC and ARM), it will be necessary to adjust the offset parameter in the load string to realign the packet. Failure to do so will result in received packets being absorbed by the network stack, although transmit functions should work OK.
fei82557End, ifLib, Intel 82557 User's Manual, Intel 32-bit Local Area Network (LAN) Component User's Manual
fei82557EndLoad( ) - initialize the driver and device
END_OBJ* fei82557EndLoad ( char * initString /* parameter string */ )
This routine initializes both, driver and device to an operational state using device specific parameters specified by initString.
The parameter string, initString, is an ordered list of parameters each separated by a colon. The format of initString is, "unit:memBase:memSize:nCFDs:nRFDs:flags"
The 82557 shares a region of memory with the driver. The caller of this routine can specify the address of this memory region, or can specify that the driver must obtain this memory region from the system resources.
A default number of transmit/receive frames of 32 can be selected by passing zero in the parameters nTfds and nRfds. In other cases, the number of frames selected should be greater than two.
The memBase parameter is used to inform the driver about the shared memory region. If this parameter is set to the constant "NONE," then this routine will attempt to allocate the shared memory from the system. Any other value for this parameter is interpreted by this routine as the address of the shared memory region to be used. The memSize parameter is used to check that this region is large enough with respect to the provided values of both transmit/receive frames.
If the caller provides the shared memory region, then the driver assumes that this region does not require cache coherency operations, nor does it require conversions between virtual and physical addresses.
If the caller indicates that this routine must allocate the shared memory region, then this routine will use cacheDmaMalloc( ) to obtain some non-cacheable memory. The attributes of this memory will be checked, and if the memory is not write coherent, this routine will abort and return ERROR.
an END object pointer, or NULL on error.
fei82557End, ifLib, Intel 82557 User's Manual
fei82557DumpPrint( ) - Display statistical counters
STATUS fei82557DumpPrint ( DRV_CTRL * pDrvCtrl /* pointer to DRV_CTRL structure */ )
This routine displays i82557 statistical counters
OK, or ERROR if the DUMP command failed.
fei82557ErrCounterDump( ) - dump statistical counters
STATUS fei82557ErrCounterDump ( DRV_CTRL * pDrvCtrl, /* pointer to DRV_CTRL structure */ UINT32 * memAddr )
This routine dumps statistical counters for the purpose of debugging and tuning the 82557.
The memAddr parameter is the pointer to an array of 68 bytes in the local memory. This memory region must be allocated before this routine is called. The memory space must also be DWORD (4 bytes) aligned. When the last DWORD (4 bytes) is written to a value, 0xa007, it indicates the dump command has completed. To determine the meaning of each statistical counter, see the Intel 82557 manual.
OK or ERROR.