VxWorks API Reference : Driver Libraries

auEnd

NAME

auEnd - END style Au MAC Ethernet driver

ROUTINES

auEndLoad( ) - initialize the driver and device
auInitParse( ) - parse the initialization string
auDump( ) - display device status

DESCRIPTION

This module implements the Alchemey Semiconductor au on-chip ethernet MACs.
The software interface to the driver is divided into three parts. The first part is the interrupt registers and their setup. This part is done at the BSP level in the various BSPs which use this driver. The second and third part are addressed 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. Though it currently is implemented on one processor, in the future it may be added to other Alchemey product offerings. Thus, it would be desirable to use the same driver with no source level changes. 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.

BOARD LAYOUT

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

EXTERNAL INTERFACE

The only external interface is the auEndLoad( ) routine, which expects the initString parameter as input. This parameter passes in a colon-delimited string of the format:
unit:devMemAddr:devIoAddr:enableAddr:vecNum:intLvl:offset :qtyCluster:flags
The auEndLoad( ) 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.

devAddr
This parameter is the memory base address of the device registers in the memory map of the CPU. It indicates to the driver where to find the base MAC register.

devIoAddr
This parameter in the base address of the device registers for the dedicated DMA channel for the MAC device. It indicates to the driver where to find the DMA registers.

enableAddr
This parameter is the address MAC enable register. It is necessary to specify selection between MAC 0 and MAC 1.

vecNum
This parameter is the vector associated with the device interrupt. This driver configures the MAC device to generate hardware interrupts for various events within the device; thus it contains an interrupt handler routine. The driver calls intConnect( ) via the macro SYS_INT_CONNECT( ) to connect its interrupt handler to the interrupt vector generated as a result of the MAC 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 sysLanAuIntEnable( ) is called to perform any board-specific operations required to allow the servicing of an interrupt. For a description of sysLanAuIntEnable( ), see "External Support Requirements" below.

offset
This parameter specifies the offset from which the packet has to be loaded from the begining of the device buffer. Normally this parameter is zero except for architectures which access long words only on aligned addresses. For these architectures the value of this offset should be 2.

qtyCluster
This parameter is used to explicitly allocate the number of clusters that will be allocated. This allows the user to suit the stack to the amount of physical memory on the board.

flags
This is parameter is reserved for future use. Its value should be zero.

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_ENET_ADDR_GET(pDrvCtrl, pAddress)    
    sysLanAuIntEnable(pDrvCtrl->intLevel) 
    sysLanAuIntDisable(pDrvCtrl->intLevel) 
    sysLanAuEnetAddrGet(pDrvCtrl, enetAdrs)
There are default values in the source code for these macros. They presume memory mapped accesses to the device registers and the 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 routine is not implemented.
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 sysLanAuIntEnable( ).
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 sysLanAuIntDisable( ).
The macro SYS_ENET_ADDR_GET is used get the ethernet hardware of the chip. This macro calls an external board level routine namely sysLanAuEnetAddrGet( ) to get the ethernet address.

SYSTEM RESOURCE USAGE

When implemented, this driver requires the following system resources:
    - one mutual exclusion semaphore
    - one interrupt vector
    - 64 bytes in the initialized data section (data)
    - 0 bytes in the uninitialized data section (BSS)
The driver allocates clusters of size 1520 bytes for receive frames and and transmit frames.

INCLUDES

end.h endLib.h etherMultiLib.h auEnd.h

auEndLoad( )

NAME

auEndLoad( ) - initialize the driver and device

SYNOPSIS

END_OBJ * auEndLoad
    (
    char * initString         /* string to be parse by the driver */
    )

DESCRIPTION

This routine initializes the driver and the device to the operational state. All of the device-specific parameters are passed in initString, which expects a string of the following format:
unit:devMemAddr:devIoAddr:enableAddr:vecNum:intLvl:offset :qtyCluster:flags
This routine can be called in two modes. If it is called with an empty but allocated string, it places the name of this device (that is, "au") into the initString and returns 0.
If the string is allocated and not empty, the routine attempts to load the driver using the values specified in the string.

RETURNS

An END object pointer, or NULL on error, or 0 and the name of the device if the initString was NULL.

auInitParse( )

NAME

auInitParse( ) - parse the initialization string

SYNOPSIS

STATUS auInitParse
    (
    AU_DRV_CTRL * pDrvCtrl,   /* pointer to the control structure */
    char *        initString  /* initialization string */
    )

DESCRIPTION

Parse the input string. This routine is called from auEndLoad( ) which intializes some values in the driver control structure with the values passed in the intialization string.
The initialization string format is: unit:devMemAddr:devIoAddr:vecNum:intLvl:offset:flags

unit
Device unit number, a small integer.
devMemAddr
Device register base memory address
devIoAddr
I/O register base memory address
enableAddr
Address of MAC enable register
vecNum
Interrupt vector number.
intLvl
Interrupt level.
offset
Offset of starting of data in the device buffers.
qtyCluster
Number of clusters to allocate
flags
Device specific flags, for future use.

RETURNS

OK, or ERROR if any arguments are invalid.

auDump( )

NAME

auDump( ) - display device status

SYNOPSIS

void auDump
    (
    int unit
    )

auEnd

NAME

ROUTINES

DESCRIPTION

BOARD LAYOUT

EXTERNAL INTERFACE

TARGET-SPECIFIC PARAMETERS

EXTERNAL SUPPORT REQUIREMENTS

SYSTEM RESOURCE USAGE

INCLUDES

SEE ALSO

auEndLoad( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

auInitParse( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

auDump( )

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO