VxWorks Reference Manual : Libraries
if_ln - AMD Am7990 LANCE Ethernet network interface driver
lnattach( ) - publish the ln network interface and initialize driver structures
This module implements the Advanced Micro Devices Am7990 LANCE Ethernet network interface driver.
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 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, this driver will probably not function correctly with it.
This driver supports only one LANCE unit 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.
This device is on-board. No jumpering diagram is necessary.
This driver provides the standard external interface with the following exceptions. All initialization is performed within the attach routine; there is no separate initialization routine. Therefore, in the global interface structure, the function pointer to the initialization routine is NULL.
The only user-callable routine is lnattach( ), which publishes the ln interface and initializes the driver and device.
- bus mode
- This parameter is a global variable that can be modified at run-time.
The LANCE control register #3 determines the bus mode of the device, allowing the support of big-endian and little-endian architectures. This parameter, defined as "u_short lnCSR_3B", is the value that will be placed into LANCE control register #3. The default value supports Motorola-type buses. For information about changing this parameter, see the manual Advanced Micro Devices Local Area Network Controller Am7990 (LANCE).
- base address of device registers
- This parameter is passed to the driver by lnattach( ). It indicates to the driver where to find the RDP register.
The LANCE presents two registers to the external interface, the RDP (register data port) and RAP (register address port) registers. This driver assumes that these two registers occupy two unique addresses in a memory space that is directly accessible by the CPU executing this driver. The driver assumes that the RDP register is mapped at a lower address than the RAP register; the RDP register is therefore considered the "base address."
- interrupt vector
- This parameter is passed to the driver by lnattach( ).
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.
- interrupt level
- This parameter is passed to the driver by lnattach( ).
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 sysLanIntEnable( ) is called to perform any board-specific operations required to allow the servicing of a LANCE interrupt. For a description of sysLanIntEnable( ), see "External Support Requirements" below.
This parameter is passed to the external routine.
- shared memory address
- This parameter is passed to the driver by lnattach( ).
The LANCE device 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 LANCE. It assumes that this shared memory is directly available to it without any arbitration or timing concerns.
This parameter can be used to specify an explicit memory region for use by the LANCE. This should be done on hardware that restricts the LANCE to a particular memory region. The constant NONE can be used to indicate that there are no memory limitations, in which case, the driver attempts to allocate the shared memory from the system space.
- shared memory size
- This parameter is passed to the driver by lnattach( ).
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.
- shared memory width
- This parameter is passed to the driver by lnattach( ).
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.
- Ethernet address
- This parameter is obtained directly from a global memory location.
During initialization, the driver needs to know the Ethernet address for the LANCE device. The driver assumes that this address is available in a global, six-byte character array, lnEnetAddr[]. This array is typically created and stuffed by the BSP code.
This driver requires one external support function:
- void sysLanIntEnable (int level)
- This routine provides a target-specific enable of the interrupt for the LANCE device. Typically, this involves interrupt controller hardware, either internal or external to the CPU.
This routine is called once, from the lnattach( ) routine.
When implemented, this driver requires the following system resources:
- one mutual exclusion semaphore
- one interrupt vector
- 24 bytes in the initialized data section (data)
- 208 bytes in the uninitialized data section (BSS)The above data and BSS requirements are for the MC68020 architecture and may vary for other architectures. Code size (text) varies greatly between architectures and is therefore not quoted here.
If the driver is not given a specific region of memory via the lnattach( ) routine, then it calls cacheDmaMalloc( ) to allocate the memory to be shared with the LANCE. The size requested is 80,542 bytes. If a memory region is provided to the driver, the size of this region is adjustable to suit user needs.
The LANCE can only be operated if the shared memory region is write-coherent with the data cache. The driver cannot maintain cache coherency for the device for data that is written by the driver because fields within the shared structures are asynchronously modified by both the driver and the device, and these fields may share the same cache line.
if_ln, ifLib, Advanced Micro Devices Local Area Network Controller Am7990 (LANCE)
lnattach( ) - publish the ln network interface and initialize driver structures
STATUS lnattach ( int unit, /* unit number */ char * devAdrs, /* LANCE I/O address */ int ivec, /* interrupt vector */ int ilevel, /* interrupt level */ char * memAdrs, /* address of memory pool (-1 = malloc it) */ ULONG memSize, /* only used if memory pool is NOT malloc()'d */ int memWidth, /* byte-width of data (-1 = any width) */ int spare, /* not used */ int spare2 /* not used */ )
This routine publishes the ln interface by filling in a network interface record and adding this record to the system list. This routine also initializes the driver and the device to the operational state.
The memAdrs parameter can be used to specify the location of the memory that will be shared between the driver and the device. The value NONE is used to indicate that the driver should obtain the memory.
The memSize parameter is valid only if the memAdrs parameter is not set to NONE, in which case memSize indicates the size of the provided memory region.
The memWidth parameter sets the memory pool's data port width (in bytes); if it is NONE, any data width is used.
To zero out LANCE data structures, this routine uses bzero( ), which ignores the memWidth specification and uses any size data access to write to memory.
OK or ERROR.