VxWorks Reference Manual : Libraries
dec21x4xEnd - END style DEC 21x4x PCI Ethernet network interface driver
dec21x4xEndLoad( ) - initialize the driver and device
This module implements a DEC 21x4x PCI Ethernet network interface driver and supports 21040, 21140 and 21143 versions of the chip.
The DEC 21x4x PCI Ethernet controller is little endian because it interfaces with a little endian PCI bus. Although PCI configuration for a device is handled in the BSP, all other device programming and initialization are handled in this module.
This driver is designed to be moderately generic. Without modification, it can operate across the range of architectures and targets supported by VxWorks. To achieve this, the driver requires a few external support routines as well as several target-specific parameters. These parameters, and the mechanisms used to communicate them to the driver, are detailed below. If any of the assumptions stated below are not true for your particular hardware, you need to modify the driver before it can operate correctly on your hardware.
On 21040, the driver configures the 10BASE-T interface by default, waits for two seconds, and checks the status of the link. If the link status indicates failure, AUI interface is configured.
On other versions of the 2114x family, the driver reads media information from a DEC serial ROM and configures the media. On targets that do not support a DEC format serial ROM, the driver calls a target-specfic media select routine using the hook, _func_dec2114xMediaSelect, to configure the media.
The driver supports big-endian or little-endian architectures (as a configurable option). The driver also and contains error recovery code that handles known device errata related to DMA activity.
Big endian processors can be connected to the PCI bus through some controllers which take care of hardware byte swapping. In such cases all the registers which the chip DMAs to have to be swapped and written to, so that when the hardware swaps the accesses, the chip would see them correctly. The chip still has to be programmed to operate in little endian mode as it is on the PCI bus. If the cpu board hardware automatically swaps all the accesses to and from the PCI bus, then input and output byte stream need not be swapped.
This device is on-board. No jumpering diagram is necessary.
The driver provides one standard external interface, dec21x4xEndLoad( ), which a takes a string of colon separated parameters. The parameters should be specified as hexadecimal strings, optionally preceded by "0x" or a minus sign "-".
Although the parameter string is parsed using strtok_r( ), each parameter is converted from string to binary by a call to strtoul(parameter, NULL, 16).
The format of the parameter string is:
"unit number:device addr:PCI addr:ivec:ilevel:mem base:\ mem size:user flags:offset"
- unit number
This represents the device instance number relative to this driver. I.e. a value of zero represents the first dec21x4x device, a value of 1 represents the second dec21x4x device.
- device addr
This is the base address at which the hardware device registers are located.
- PCI addr
This parameter defines the main memory address over the PCI bus. It is used to translate physical memory address into PCI accessible address.
- ivec
This is the interrupt vector number of the hardware interrupt generated by this Ethernet device. The driver uses intConnect, or pciIntConnect (x86 arch), to attach an interrupt handler for this interrupt.
- ilevel
This parameter defines the level of the hardware interrupt.
- mem base
This parameter specifies the base address of a DMA-able, cache free, pre-allocated memory region for use as a memory pool for transmit/receive descriptors and buffers.
If there is no pre-allocated memory available for the driver, this parameter should be -1 (NONE). In which case, the driver allocates cache safe memory for its use using cacheDmaAlloc( ).
- mem size
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.
- user flags
User flags control the run-time characteristics of the Ethernet chip. Most flags specify non default CSR0 bit values. Refer to dec21x4xEnd.h for the bit values of the flags, and to the device hardware reference manual for details about device capabilities, and CSR 0.
Some of them are worth mentioning:
Full Duplex Mode: When set, the DEC_USR_FD flag allows the device to work in full duplex mode, as long as the PHY used has this capability. It is worth noting here that in this operation mode, the dec21x40 chip ignores the Collision and the Carrier Sense signals.
Transmit treshold value: The DEC_USR_THR_XXX flags enable the user to choose among different threshold values for the transmit FIFO. Transmission starts when the frame size within the transmit FIFO is larger than the treshold value. This should be selected taking into account the actual operating speed of the PHY. Again, see the device hardware reference manual for details.
- offset
This parameter defines the offset which is used to solve alignment problem.
- Device Type
Although the default device type is DEC 21040, specifying the DEC_USR_21140 or DEC_USR_21143 flag bit turns on DEC 21140 or DEC_USR_21143 functionality.
- Ethernet Address
The Ethernet address is retrieved from standard serial ROM on DEC 21040, DEC 21140 and DEC 21143 devices. If retrieve from ROM fails, the driver calls the BSP routine, sysDec21x4xEnetAddrGet( ). Specifying DEC_USR_XEA flag bit tells the driver should, by default, retrieve the Ethernet address using the BSP routine, sysDec21x4xEnetAddrGet( ).
- Priority RX processing
The driver programs the chip to process the transmit and receive queues at the same priority. By specifying DEC_USR_BAR_RX, the device is programmed to process receives at a higher priority.
- TX poll rate
By default, the driver sets the Ethernet chip into a non-polling mode. In this mode, if the transmit engine is idle, it is kick-started every time a packet needs to be transmitted. Alternately, the chip can be programmed to poll for the next available transmit descriptor if the transmit engine is in idle state. The poll rate is specified by one of DEC_USR_TAP_xxx.
- Cache Alignment
The DEC_USR_CAL_xxx flags specify the address boundaries for data burst transfers.
- DMA burst length
The DEC_USR_PBL_xxx flags specify the maximum number of long words in a DMA burst.
- PCI multiple read
The DEC_USR_RML flag specifies that a device supports PCI memory-read-multiple.
This driver requires four external support functions, and provides a hook function:
- void sysLanIntEnable (int level)
This routine provides a target-specific interface for enabling Ethernet device interrupts at a specified interrupt level.
- void sysLanIntDisable (void)
This routine provides a target-specific interface for disabling Ethernet device interrupts.
- STATUS sysDec21x4xEnetAddrGet (int unit, char *enetAdrs)
This routine provides a target-specific interface for accessing a device Ethernet address.
- STATUS sysDec21143Init (DRV_CTRL * pDrvCtrl)
This routine performs any target-specific initialization required before the dec21143 device is initialized by the driver. The driver calls this routine every time it wants to load the device. This routine returns OK, or ERROR if it fails.
- FUNCPTR _func_dec2114xMediaSelect
This driver provides a default media select routine, when <_func_dec2114xMediaSelect> is NULL, to read and setup physical media with configuration information from a Version 3 DEC Serial ROM. Any other media configuration can be supported by initializing <_func_dec2114xMediaSelect>, typically in sysHwInit( ), to a target-specific media select routine.
A media select routine is typically defined as:
STATUS decMediaSelect ( DEC21X4X_DRV_CTRL * pDrvCtrl, /* Driver control */ UINT * pCsr6Val /* CSR6 return value */ ) { ... }Parameter pDrvCtrl is a pointer to the driver control structure which this routine may use to access the Ethenet device. The driver control structure field mediaCount, is initialized to 0xff at startup, while the other media control fields (mediaDefault, mediaCurrent, and gprModeVal) are initialized to zero. This routine may use these fields in any manner, however all other driver control fields should be considered read-only and should not be modified.This routine should reset, initialize and select an appropriate media, and write necessary the CSR6 bits (port select, PCS, SCR, and full duplex) to memory location pointed to by pCsr6Val. The driver will use this value to program register CSR6. This routine should return OK, and ERROR on failure.
- FUNCPTR _func_dec2114xIntAck
This driver does acknowledge the LAN interrupts. However if the board hardware requires specific interrupt acknowledgement, not provided by this driver, the BSP should define such a routine and attach it to the driver via _func_dec2114xIntAck.
dec21x4xEnd, ifLib, DECchip 21040 Ethernet LAN Controller for PCI. Digital Semiconductor 21140A PCI Fast Ethernet LAN Controller. Digital Semiconductor 21143 PCI/CardBus Fast Ethernet LAN Controller. Using the Digital Semiconductor 21140A with Boot ROM, Serial ROM, and External Register: An Application Note" Using the Digital Semiconductor 21143 with Boot ROM, Serial ROM, and External Register: An Application Note"
dec21x4xEndLoad( ) - initialize the driver and device
END_OBJ * dec21x4xEndLoad ( char * initStr /* String to be parse by the driver. */ )
This routine initializes the driver and the device to the operational state. All of the device specific parameters are passed in the initString.
This routine can be called in two modes. If it is called with an empty, but allocated string then it places the name of this device (i.e. dc) into the initString and returns 0.
If the string is allocated then the routine attempts to perform its load functionality.
An END object pointer or NULL on error or 0 and the name of the device if the initString was NULL.