VxWorks Reference Manual : Libraries

el3c90xEnd

NAME

el3c90xEnd - END network interface driver for 3COM 3C90xB XL

ROUTINES

el3c90xEndLoad( ) - initialize the driver and device
el3c90xInitParse( ) - parse the initialization string

DESCRIPTION

This module implements the device driver for the 3COM EtherLink Xl and Fast EtherLink XL PCI network interface cards.

The 3c90x PCI ethernet controller is inherently little endian because the chip is designed to operate on a PCI bus which is a little endian bus. The software interface to the driver is divided into three parts. The first part is the PCI configuration registers and their set up. This part is done at the BSP level in the various BSPs which use this driver. The second and third part are dealt in the driver. The second part of the interface comprises of the I/O control registers and their programming. The third part of the interface comprises of the descriptors and the buffers.

This driver is designed to be moderately generic, operating unmodified across the range of architectures and targets supported by VxWorks. To achieve this, the driver must be given several target-specific parameters, and some external support routines must be provided. These target-specific values and the external support routines are described below.

This driver supports multiple units per CPU. The driver can be configured to support big-endian or little-endian architectures. It contains error recovery code to handle 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 DMA s 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 operated 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.

The 3c90x series chips use a bus-master DMA interface for transfering packets to and from the controller chip. Some of the old 3c59x cards also supported a bus master mode, however for those chips you could only DMA packets to and from a contiguous memory buffer. For transmission this would mean copying the contents of the queued M_BLK chain into a an M_BLK cluster and then DMAing the cluster. This extra copy would sort of defeat the purpose of the bus master support for any packet that doesn't fit into a single M_BLK. By contrast, the 3c90x cards support a fragment-based bus master mode where M_BLK chains can be encapsulated using TX descriptors. This is also called the gather technique, where the fragments in an mBlk chain are directly incorporated into the download transmit descriptor. This avoids any copying of data from the mBlk chain.

NETWORK CARDS SUPPORTED

        - 3Com 3c900-TPO 10Mbps/RJ-45
        - 3Com 3c900-COMBO 10Mbps/RJ-45,AUI,BNC
        - 3Com 3c905-TX 10/100Mbps/RJ-45
        - 3Com 3c905-T4 10/100Mbps/RJ-45
        - 3Com 3c900B-TPO 10Mbps/RJ-45
        - 3Com 3c900B-COMBO 10Mbps/RJ-45,AUI,BNC
        - 3Com 3c905B-TX 10/100Mbps/RJ-45
        - 3Com 3c905B-FL/FX 10/100Mbps/Fiber-optic
        - 3Com 3c980-TX 10/100Mbps server adapter
        - Dell Optiplex GX1 on-board 3c918 10/100Mbps/RJ-45

BOARD LAYOUT

This device is on-board. No jumpering diagram is necessary.

EXTERNAL INTERFACE

The only external interface is the el3c90xEndLoad( ) routine, which expects the initString parameter as input. This parameter passes in a colon-delimited string of the format:

unit:devMemAddr:devIoAddr:pciMemBase::intLvl:memAdrs: memSize:memWidth:flags:buffMultiplier

The el3c90xEndLoad( ) function uses strtok( ) to parse the string.

TARGET-SPECIFIC PARAMETERS

unit

A convenient holdover from the former model. This parameter is used only in the string name for the driver.

devMemAddr

This parameter in the memory base address of the device registers in the memory map of the CPU. It indicates to the driver where to find the register set. < This parameter should be equal to NONE if the device does not support memory mapped registers.

devIoAddr

This parameter in the IO base address of the device registers in the IO map of some CPUs. It indicates to the driver where to find the RDP register. If both devIoAddr and devMemAddr are given then the device chooses devMemAddr which is a memory mapped register base address. This parameter should be equal to NONE if the device does not support IO mapped registers.

. pciMemBase This parameter is the base address of the CPU memory as seen from the PCI bus. This parameter is zero for most intel architectures.

vecNum

This parameter is the vector associated with the device interrupt. This driver configures the LANCE device to generate hardware interrupts for various events within the device; thus it contains an interrupt handler routine. The driver calls intConnect( ) to connect its interrupt handler to the interrupt vector generated as a result of the LANCE interrupt.

intLvl

Some targets use additional interrupt controller devices to help organize and service the various interrupt sources. This driver avoids all board-specific knowledge of such devices. During the driver's initialization, the external routine sysEl3c90xIntEnable( ) is called to perform any board-specific operations required to allow the servicing of a NIC interrupt. For a description of sysEl3c90xIntEnable( ), see "External Support Requirements" below.

memAdrs

This parameter gives the driver the memory address to carve out its buffers and data structures. If this parameter is specified to be NONE then the driver allocates cache coherent memory for buffers and descriptors from the system pool. The 3C90x NIC is a DMA type of 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 NIC. It assumes that this shared memory is directly available to it without any arbitration or timing concerns.

memSize

This parameter can be used to explicitly limit the amount of shared memory (bytes) this driver will use. The constant NONE can be used to indicate no specific size limitation. This parameter is used only if a specific memory region is provided to the driver.

memWidth

Some target hardware that restricts the shared memory region to a specific location also restricts the access width to this region by the CPU. On these targets, performing an access of an invalid width will cause a bus error.

This parameter can be used to specify the number of bytes of access width to be used by the driver during access to the shared memory. The constant NONE can be used to indicate no restrictions.

Current internal support for this mechanism is not robust; implementation may not work on all targets requiring these restrictions.

flags

This is parameter is used for future use, currently its value should be zero.

buffMultiplier

This parameter is used increase the number of buffers allocated in the driver pool. If this parameter is -1 then a default multiplier of 2 is choosen. With a multiplier of 2 the total number of clusters allocated is 64 which is twice the cumulative number of upload and download descriptors. The device has 16 upload and 16 download descriptors. For example on choosing the buffer multiplier of 3, the total number of clusters allocated will be 96 ((16 + 16)*3). There are as many clBlks as the number of clusters. The number of mBlks allocated are twice the number of clBlks. By default there are 64 clusters, 64 clBlks and 128 mBlks allocated in the pool for the device. Depending on the load of the system increase the number of clusters allocated by incrementing the buffer multiplier.

EXTERNAL SUPPORT REQUIREMENTS

This driver requires several external support functions, defined as macros:

    SYS_INT_CONNECT(pDrvCtrl, routine, arg)
    SYS_INT_DISCONNECT (pDrvCtrl, routine, arg)
    SYS_INT_ENABLE(pDrvCtrl)
    SYS_INT_DISABLE(pDrvCtrl)
    SYS_OUT_BYTE(pDrvCtrl, reg, data)
    SYS_IN_BYTE(pDrvCtrl, reg, data)
    SYS_OUT_WORD(pDrvCtrl, reg, data)
    SYS_IN_WORD(pDrvCtrl, reg, data)
    SYS_OUT_LONG(pDrvCtrl, reg, data)
    SYS_IN_LONG(pDrvCtrl, reg, data)
    SYS_DELAY (delay)
    sysEl3c90xIntEnable(pDrvCtrl->intLevel) 
    sysEl3c90xIntDisable(pDrvCtrl->intLevel)
    sysDelay (delay)

There are default values in the source code for these macros. They presume memory mapped accesses to the device registers and the normal intConnect( ), and intEnable( ) BSP functions. The first argument to each is the device controller structure. Thus, each has access back to all the device-specific information. Having the pointer in the macro facilitates the addition of new features to this driver.

The macros SYS_INT_CONNECT, SYS_INT_DISCONNECT, SYS_INT_ENABLE and SYS_INT_DISABLE allow the driver to be customized for BSPs that use special versions of these routines.

The macro SYS_INT_CONNECT is used to connect the interrupt handler to the appropriate vector. By default it is the routine intConnect( ).

The macro SYS_INT_DISCONNECT is used to disconnect the interrupt handler prior to unloading the module. By default this is a dummy routine that returns OK.

The macro SYS_INT_ENABLE is used to enable the interrupt level for the end device. It is called once during initialization. It calls an external board level routine sysEl3c90xIntEnable( ).

The macro SYS_INT_DISABLE is used to disable the interrupt level for the end device. It is called during stop. It calls an external board level routine sysEl3c90xIntDisable( ).

The macro SYS_DELAY is used for a delay loop. It calls an external board level routine sysDelay(delay). The granularity of delay is one microsecond.

SYSTEM RESOURCE USAGE

When implemented, this driver requires the following system resources:

    - one mutual exclusion semaphore
    - one interrupt vector
    - 24072 bytes in text for a I80486 target
    - 112 bytes in the initialized data section (data)
    - 0 bytes in the uninitialized data section (BSS)

The driver allocates clusters of size 1536 bytes for receive frames and and transmit frames. There are 16 descriptors in the upload ring and 16 descriptors in the download ring. The buffer multiplier by default is 2, which means that the total number of clusters allocated by default are 64 ((upload descriptors + download descriptors)*2). There are as many clBlks as the number of clusters. The number of mBlks allocated are twice the number of clBlks. By default there are 64 clusters, 64 clBlks and 128 mBlks allocated in the pool for the device. Depending on the load of the system increase the number of clusters allocated by incrementing the buffer multiplier.

INCLUDES

end.h endLib.h etherMultiLib.h el3c90xEnd.h

SEE ALSO

el3c90xEnd, muxLib, endLib, netBufLib VxWorks Programmer's Guide: Writing and Enhanced Network Driver

BIBLIOGRAPHY

3COM 3c90x and 3c90xB NICs Technical reference.

---

Libraries : Routines

el3c90xEndLoad( )