if_cpm

NAME

if_cpm - Motorola CPM core network interface driver

ROUTINES

cpmattach( ) - publish the cpm network interface and initialize the driver
cpmStartOutput( ) - output packet to network interface device

DESCRIPTION

This module implements the driver for the Motorola CPM core Ethernet network interface used in the M68EN360 and PPC800-series communications controllers.
The driver is designed to support the Ethernet mode of an SCC residing on the CPM processor core. It is generic in the sense that it does not care which SCC is being used, and it supports up to four individual units per board.
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.
This network interface driver does not include support for trailer protocols or data chaining. However, buffer loaning has been implemented in an effort to boost performance. This driver provides support for four individual device units.
This driver maintains cache coherency by allocating buffer space using the cacheDmaMalloc( ) routine. It is assumed that cache-safe memory is returned; this driver does not perform cache flushing and invalidating.

BOARD LAYOUT

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

EXTERNAL INTERFACE

This driver presents the standard WRS network driver API: the device unit must be attached and initialized with the cpmattach( ) routine.
The only user-callable routine is cpmattach( ), which publishes the cpm interface and initializes the driver structures.

TARGET-SPECIFIC PARAMETERS

These parameters are passed to the driver via cpmattach( ).

address of SCC parameter RAM
This parameter is the address of the parameter RAM used to control the SCC. Through this address, and the address of the SCC registers (see below), different network interface units are able to use different SCCs without conflict. This parameter points to the internal memory of the chip where the SCC physically resides, which may not necessarily be the master chip on the target board.

address of SCC registers
This parameter is the address of the registers used to control the SCC. Through this address, and the address of the SCC parameter RAM (see above), different network interface units are able to use different SCCs without conflict. This parameter points to the internal memory of the chip where the SCC physically resides, which may not necessarily be the master chip on the target board.

interrupt-vector offset
This driver configures the SCC to generate hardware interrupts for various events within the device. The interrupt-vector offset parameter is used to connect the driver's ISR to the interrupt through a call to intConnect( ).

address of transmit and receive buffer descriptors
These parameters indicate the base locations of the transmit and receive buffer descriptor (BD) rings. Each BD takes up 8 bytes of dual-ported RAM, and it is the user's responsibility to ensure that all specified BDs will fit within dual-ported RAM. This includes any other BDs the target board may be using, including other SCCs, SMCs, and the SPI device. There is no default for these parameters; they must be provided by the user.

number of transmit and receive buffer descriptors
The number of transmit and receive buffer descriptors (BDs) used is configurable by the user upon attaching the driver. Each buffer descriptor resides in 8 bytes of the chip's dual-ported RAM space, and each one points to a 1520-byte buffer in regular RAM. There must be a minimum of two transmit and two receive BDs. There is no maximum number of buffers, but there is a limit to how much the driver speed increases as more buffers are added, and dual-ported RAM space is at a premium. If this parameter is "NULL", a default value of 32 BDs is used.

base address of buffer pool
This parameter is used to notify the driver that space for the transmit and receive buffers need not be allocated, but should be taken from a cache-coherent private memory space provided by the user at the given address. The user should be aware that memory used for buffers must be 4-byte aligned and non-cacheable. All the buffers must fit in the given memory space; no checking is performed. This includes all transmit and receive buffers (see above) and an additional 16 receive loaner buffers. If the number of receive BDs is less than 16, that number of loaner buffers is used. Each buffer is 1520 bytes. If this parameter is "NONE," space for buffers is obtained by calling cacheDmaMalloc( ) in cpmattach( ).

EXTERNAL SUPPORT REQUIREMENTS

This driver requires seven external support functions:

STATUS sysCpmEnetEnable (int unit)
This routine is expected to perform any target-specific functions required to enable the Ethernet controller. These functions typically include enabling the Transmit Enable signal (TENA) and connecting the transmit and receive clocks to the SCC. The driver calls this routine, once per unit, from the cpmInit( ) routine.

void sysCpmEnetDisable (int unit)
This routine is expected to perform any target-specific functions required to disable the Ethernet controller. This usually involves disabling the Transmit Enable (TENA) signal. The driver calls this routine from the cpmReset( ) routine each time a unit is disabled.

STATUS sysCpmEnetCommand (int unit, UINT16 command)
This routine is expected to issue a command to the Ethernet interface controller. The driver calls this routine to perform basic commands, such as restarting the transmitter and stopping reception.

void sysCpmEnetIntEnable (int unit)
This routine is expected to enable the interrupt for the Ethernet interface specified by unit.

void sysCpmEnetIntDisable (int unit)
This routine is expected to disable the interrupt for the Ethernet interface specified by unit.

void sysCpmEnetIntClear (int unit)
This routine is expected to clear the interrupt for the Ethernet interface specified by unit.

STATUS sysCpmEnetAddrGet (int unit, UINT8 * addr)
The driver expects this routine to provide the 6-byte Ethernet hardware address that will be used by unit. This routine must copy the 6-byte address to the space provided by addr. This routine is expected to return OK on success, or ERROR. The driver calls this routine, once per unit, from the cpmInit( ) routine.

SYSTEM RESOURCE USAGE

This driver requires the following system resources:
    - one mutual exclusion semaphore
    - one interrupt vector
    - 0 bytes in the initialized data section (data)
    - 1272 bytes in the uninitialized data section (BSS)
The data and BSS sections are quoted for the CPU32 architecture and may vary for other architectures. The code size (text) varies greatly between architectures, and is therefore not quoted here.
If the driver allocates the memory shared with the Ethernet device unit, it does so by calling the cacheDmaMalloc( ) routine. For the default case of 32 transmit buffers, 32 receive buffers, and 16 loaner buffers, the total size requested is 121,600 bytes. If a non-cacheable memory region is provided by the user, the size of this region should be this amount, unless the user has specified a different number of transmit or receive BDs.
This driver can operate only if the shared memory region is non-cacheable, or if the hardware implements bus snooping. The driver cannot maintain cache coherency for the device because the buffers are asynchronously modified by both the driver and the device, and these fields may share the same cache line. Additionally, the chip's dual ported RAM must be declared as non-cacheable memory where applicable.

cpmattach( )

NAME

cpmattach( ) - publish the cpm network interface and initialize the driver

SYNOPSIS

STATUS cpmattach
    (
    int           unit,     /* unit number */
    SCC *         pScc,     /* address of SCC parameter RAM */
    SCC_REG *     pSccReg,  /* address of SCC registers */
    VOIDFUNCPTR * ivec,     /* interrupt vector offset */
    SCC_BUF *     txBdBase, /* transmit buffer descriptor base address */
    SCC_BUF *     rxBdBase, /* receive buffer descriptor base address */
    int           txBdNum,  /* number of transmit buffer descriptors */
    int           rxBdNum,  /* number of receive buffer descriptors */
    UINT8 *       bufBase   /* address of memory pool; NONE = malloc it */
    )

DESCRIPTION

The routine publishes the cpm interface by filling in a network Interface Data Record (IDR) and adding this record to the system's interface list.
The SCC shares a region of memory with the driver. The caller of this routine can specify the address of a shared, non-cacheable memory region with bufBase. If this parameter is NONE, the driver obtains this memory region by calling cacheDmaMalloc( ). Non-cacheable memory space is important for cases where the SCC is operating with a processor that has a data cache.
Once non-cacheable memory is obtained, this routine divides up the memory between the various buffer descriptors (BDs). The number of BDs can be specified by txBdNum and rxBdNum, or if NULL, a default value of 32 BDs will be used. Additional buffers are reserved as receive loaner buffers. The number of loaner buffers is the lesser of rxBdNum and a default value of 16.
The user must specify the location of the transmit and receive BDs in the CPU's dual-ported RAM. txBdBase and rxBdBase give the base address of the BD rings. Each BD uses 8 bytes. Care must be taken so that the specified locations for Ethernet BDs do not conflict with other dual-ported RAM structures.
Up to four individual device units are supported by this driver. Device units may reside on different processor chips, or may be on different SCCs within a single CPU.
Before this routine returns, it calls cpmReset( ) and cpmInit( ) to configure the Ethernet controller, and connects the interrupt vector ivec.

RETURNS

OK or ERROR.

cpmStartOutput( )

NAME

cpmStartOutput( ) - output packet to network interface device

SYNOPSIS

#ifdef BSD43_DRIVER LOCAL void cpmStartOutput
    (
    int unit /* unit number */
    )

DESCRIPTION

cpmStartOutput( ) takes a packet from the network interface output queue, copies the mbuf chain into an interface buffer, and sends the packet over the interface. etherOutputHookRtns are supported.
Collision stats are collected in this routine from previously sent BDs. These BDs will not be examined until after the transmitter has cycled the ring, coming upon the BD after it has been sent. Thus, collision stat collection will be delayed a full cycle through the Tx ring.
This routine is called from several possible threads. Each one will be described below.
The first, and most common thread, is when a user task requests the transmission of data. Under BSD 4.3, this will cause cpmOutput( ) to be called, which calls ether_output( ), which usually calls this routine. This routine will not be called if ether_output( ) finds that our interface output queue is full. In this very rare case, the outgoing data will be thrown out. BSD 4.4 uses a slightly different model in which the generic ether_output( ) routine is called directly, followed by a call to this routine.
The second thread is when a transmitter error occurs that causes a TXE event interrupt. This happens for the following errors: transmitter underrun, retry limit reached, late collision, and heartbeat error. The ISR sets the txStop flag to stop the transmitter until the errors are serviced. These events require a RESTART command of the transmitter, which occurs in the cpmTxRestart( ) routine. After the transmitter is restarted, cpmTxRestart( ) does a netJobAdd of cpmStartOutput( ) to send any packets left in the interface output queue. Thus, the second thread executes in the context of netTask( ).
The third, and most unlikely, thread occurs when this routine is executing and it runs out of free Tx BDs. In this case, this routine turns on transmit interrupt and exits. When the next BD is actually sent, an interrupt occurs. The ISR does a netJobAdd of cpmStartOutput( ) to continue sending packets left in the interface output queue. Once again, we find ourselves executing in the context of netTask( ).

RETURNS

N/A

if_cpm

NAME

ROUTINES

DESCRIPTION

BOARD LAYOUT

EXTERNAL INTERFACE

TARGET-SPECIFIC PARAMETERS

EXTERNAL SUPPORT REQUIREMENTS

SYSTEM RESOURCE USAGE

SEE ALSO

cpmattach( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

cpmStartOutput( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO