VxWorks Reference Manual : Libraries
dec21x40End - END-style DEC 21x40 PCI Ethernet network interface driver
endTok_r( ) - get a token string (modified version)
dec21x40EndLoad( ) - initialize the driver and device
dec21140SromWordRead( ) - read two bytes from the serial ROM
dec21x40PhyFind( ) - Find the first PHY connected to DEC MII port.
dec21145SPIReadBack( ) - Read all PHY registers out
This module implements a DEC 21x40 PCI Ethernet network interface driver and supports both the 21040, 21140, 21143, 21145 versions of the chip.
The DEC 21x40 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 needs are handled in this module.
This driver is designed to be moderately generic. Without modification, it can operate across the full 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 the 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 21x40 family, the driver reads media information from a DEC serial ROM and configures the media. To configure the media on targets that do not support a DEC format serial ROM, the driver calls the target-specific media-select routine referenced in the _func_dec21x40MediaSelect hook.
The 21145 supports HomePNA 1.0 (Home Phone Line) Networking as well as 10Base-T. The HomePNA port can be forced to 1 MB/sec or 0.7 MB/sec mode via the DEC_USR_HPNA_FORCE_FAST and DEC_USR_HPNA_FORCE_SLOW user flags, respectively. If these flags are not set then the speed is set using the SROM settings. Unlike the Ethernet phys, the HomePNA phy can not determine link failure and therefore will never notify the driver when the HomePNA port is disconnected. However, to allow media change, the driver can be configured to ALWAYS perfer 10Base-T over HomePNA by interrupting on 10Base-T link pass interrupt. Upon 10Base-T link failure, the driver will revert back to HomePNA. Since this method violates the preference rules outlined in Intel/DEC SROM format spec, this is not the default mode of operation. The driver must be started with DEC_USR_HPNA_PREFER_10BT user flag set to set the driver into this mode.
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 that 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, dec21x40EndLoad( ). As input, this function expects 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 endTok_r( ), each parameter is converted from string to binary by a call to:
strtoul(parameter, NULL, 16).The format of the parameter string is:"deviceAddr:pciAddr:iVec:iLevel:numRds:numTds:\ memBase:memSize:userFlags:phyAddr:pPhyTbl:phyFlags:offset"
- deviceAddr
- This is the base address at which the hardware device registers are located.
- pciAddr
- This parameter defines the main memory address over the PCI bus. It is used to translate a physical memory address into a PCI-accessible address.
- iVec
- This is the interrupt vector number of the hardware interrupt generated by this Ethernet device. The driver uses intConnect( ) to attach an interrupt handler for this interrupt.
- iLevel
- This parameter defines the level of the hardware interrupt.
- numRds
- The number of receive descriptors to use. This controls how much data the device can absorb under load. If this is specified as NONE (-1), the default of 32 is used.
- numTds
- The number of transmit descriptors to use. This controls how much data the device can absorb under load. If this is specified as NONE (-1) then the default of 64 is used.
- memBase
- 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( ).
- 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.
- userFlags
- User flags control the run-time characteristics of the Ethernet chip. Most flags specify non default CSR0 and CSR6 bit values. Refer to dec21x40End.h for the bit values of the flags and to the device hardware reference manual for details about device capabilities, CSR6 and CSR0.
- phyAddr
- This optional parameter specifies the address on the MII (Media Independent Interface) bus of a MII-compliant PHY (Physical Layer Entity). The module that is responsible for optimally configuring the media layer will start scanning the MII bus from the address in phyAddr. It will retrieve the PHY's address regardless of that, but, since the MII management interface, through which the PHY is configured, is a very slow one, providing an incorrect or invalid address may result in a particularly long boot process. If the flag DEC_USR_MII is not set, this parameter is ignored.
- pPhyTbl
- This optional parameter specifies the address of a auto-negotiation table for the PHY being used. The user only needs to provide a valid value for this parameter if he wants to affect the order how different technology abilities are negotiated. If the flag DEC_USR_MII is not set, this parameter is ignored.
- phyFlags
- This optional parameter allows the user to affect the PHY's configuration and behaviour. See below, for an explanation of each MII flag. If the flag DEC_USR_MII is not set, this parameter is ignored.
- 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 flag bit turns on DEC 21140 functionality.
Ethernet Address: The Ethernet address is retrieved from standard serial ROM on both DEC 21040, and DEC 21140 devices. If the retrieve from ROM fails, the driver calls the sysDec21x40EnetAddrGet( ) BSP routine. Specifying DEC_USR_XEA flag bit tells the driver should, by default, retrieve the Ethernet address using the sysDec21x40EnetAddrGet( ) BSP routine.
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. Alternatively, 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 flags.
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.
MII interface: some boards feature an MII-compliant Physical Layer Entity (PHY). In this case, and if the flag DEC_USR_MII is set, then the optional fields phyAddr, pPhyTbl, and phyFlags may be used to affect the PHY's configuration on the network.
10Base-T Mode: when the flag DEC_USR_MII_10MB is set, then the PHY will negotiate this technology ability, if present.
100Base-T Mode: when the flag DEC_USR_MII_100MB is set, then the PHY will negotiate this technology ability, if present.
Half duplex Mode: when the flag DEC_USR_MII_HD is set, then the PHY will negotiate this technology ability, if present.
Full duplex Mode: when the flag DEC_USR_MII_FD is set, then the PHY will negotiate this technology ability, if present.
Auto-negotiation: the driver's default behaviour is to enable auto-negotiation, as defined in "IEEE 802.3u Standard". However, the user may disable this feature by setting the flag DEC_USR_MII_NO_AN in the phyFlags field of the load string.
Auto-negotiation table: the driver's default behaviour is to enable the standard auto-negotiation process, as defined in "IEEE 802.3u Standard". However, the user may wish to force the PHY to negotiate its technology abilities a subset at a time, and according to a particular order. The flag DEC_USR_MII_AN_TBL in the phyFlags field may be used to tell the driver that the PHY should negotiate its abilities as dictated by the entries in the pPhyTbl of the load string. If the flag DEC_USR_MII_NO_AN is set, this parameter is ignored.
Link monitoring: this feature enables the netTask to periodically monitor the PHY's link status for link down events. If any such event occurs, and if the flag DEC_USR_MII_BUS_MON is set, then a driver's optionally provided routine is executed, and the link is renegotiated.
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.
This driver requires three external support functions and provides a hook function:
- sysLanIntEnable( )
- sysLanIntDisable( )
- sysDec21x40EnetAddrGet( )
- _func_dec21x40MediaSelect
A media select routine is typically defined as:
STATUS decMediaSelect ( DEC21X40_DRV_CTRL * pDrvCtrl, /* driver control */ UINT * pCsr6Val /* CSR6 return value */ ) { ... }The pDrvCtrl parameter is a pointer to the driver control structure that this routine can use to access the Ethenet device. The driver control structure member mediaCount, is initialized to 0xff at startup, while the other media control members (mediaDefault, mediaCurrent, and gprModeVal) are initialized to zero. This routine can use these fields in any manner. However, all other driver control structure members should be considered read-only and should not be modified.This routine should reset, initialize, and select an appropriate media. It should also write necessary the CSR6 bits (port select, PCS, SCR, and full duplex) to the memory location pointed to by pCsr6Val. The driver uses this value to program register CSR6. This routine should return OK or ERROR.
The dec21xxx series chips are now owned and manufactured by Intel. Chips may be identified by either PCI Vendor ID. ID value 0x1011 for Digital, or ID value 0x8086 for Intel. Check the Intel web site for latest information. The information listed below may be out of date.
Chip Vendor ID Device ID dec 21040 0x1011 0x0002 dec 21041 0x1011 0x0014 dec 21140 0x1011 0x0009 dec 21143 0x1011 0x0019 dec 21145 0x8086 0x0039
dec21x40End, ifLib, DECchip 21040 Ethernet LAN Controller for PCI, Digital Semiconductor 21140A PCI Fast Ethernet LAN Controller,
and External Register: An Application Note" Intel 21145 Phoneline/Ethernet LAN Controller Hardware Ref. Manual Intel 21145 Phoneline/Ethernet LAN Controller Specification Update
endTok_r( ) - get a token string (modified version)
char * endTok_r ( char * string, /* string to break into tokens */ const char * separators, /* the separators */ char * * ppLast /* pointer to serve as string index */ )
This modified version can be used with optional parameters. If the parameter is not specified, this version returns NULL. It does not signify the end of the original string, but that the parameter is null.
/* required parameters */ string = endTok_r (initString, ":", &pLast); if (string == NULL) return ERROR; reqParam1 = strtoul (string); string = endTok_r (NULL, ":", &pLast); if (string == NULL) return ERROR; reqParam2 = strtoul (string); /* optional parameters */ string = endTok_r (NULL, ":", &pLast); if (string != NULL) optParam1 = strtoul (string); string = endTok_r (NULL, ":", &pLast); if (string != NULL) optParam2 = strtoul (string);
dec21x40EndLoad( ) - initialize the driver and device
END_OBJ* dec21x40EndLoad ( char* initStr /* String to be parse by the driver. */ )
This routine initializes the driver and the device to an operational state. All of the device-specific parameters are passed in the initStr. If this routine is called with an empty but allocated string, it puts the name of this device (that is, "dc") into the initStr and returns 0. If the string is allocated but not empty, this routine tries to load the device.
An END object pointer or NULL on error.
dec21140SromWordRead( ) - read two bytes from the serial ROM
USHORT dec21140SromWordRead ( DRV_CTRL * pDrvCtrl, UCHAR lineCnt /* Serial ROM line Number */ )
This routine returns the two bytes of information that is associated with it the specified ROM line number. This will later be used by the dec21140GetEthernetAdr function. It can also be used to review the ROM contents itself. The function must first send some initial bit patterns to the CSR9 that contains the Serial ROM Control bits. Then the line index into the ROM is evaluated bit-by-bit to program the ROM. The 2 bytes of data are extracted and processed into a normal pair of bytes.
Value from ROM or ERROR.
dec21x40PhyFind( ) - Find the first PHY connected to DEC MII port.
UINT8 dec21x40PhyFind ( DRV_CTRL * pDrvCtrl )
Address of PHY or 0xFF if not found.
dec21145SPIReadBack( ) - Read all PHY registers out
void dec21145SPIReadBack ( DRV_CTRL * pDrvCtrl /* pointer to DRV_CTRL structure */ )
nothing