motfcc2end.c

MPC8560 for vxwork BSP

/* motFcc2End.c - Second Generation Motorola FCC Ethernet network interface.*/

/*
 * Copyright (c) 2003-2005 Wind River Systems, Inc.
 *
 * The right to copy, distribute, modify or otherwise make use
 * of this software may be licensed only pursuant to the terms
 * of an applicable Wind River license agreement.
 */

/*
modification history
--------------------
01s,18sep06,wap  Do both pre and post invalidation of RX buffers (CQ63978)
01r,11may06,dgp  doc: fix list format in lib
01q,28aug05,dlk  Add section tags. Fix typo breaking polled mode (SPR#110883).
                 Fix off-by-one error in transmit cleanup-before-coalesce code.
		 Decrease phyMaxDelay from 20 to 5 seconds.
		 Fix errors in disabled INCLUDE_DUMPS code.
01p,29aug05,wap  Add support for IFF_ALLMULTI (SPR #110201)
01o,26jun05,dlk  Replace netJobAdd() with jobQueuePost().
01n,19mar05,dlk  Optimizations. Clean-up. Enable SNOOP through load string.
01m,28oct04,dtr  SPR 103066.
01l,31aug04,mdo  Documentation fixes for apigen
01k,19aug04,mdo  SPR's 99632, 98962, removed windview windview from code - left
                 event defines if needed.  Removed Graceful TX/Stop. Added dump
                 routines for debug. 
01j,23aug04,rcs  fixed SPR 100245
01i,23jul04,mdo  Base6 Enhancements
01p,09jul04,rcs  Fixed SPR 88900 motFcc2End driver does not handle netJobAdd() 
                 failure
01o,09jul04,rcs  Fixed SPR 98957 dereference of pDrvCtrl precedes check 
01n,09jul04,rcs  Added muxError call when netTupleGet fails SPR 88898
01m,09jul04,rcs  Implemented clean unload SPRs 98962, 98957, 98523, 89166, 
                 78575, 
01l,09jul04,rcs  Implemented Generic MIB Interface SPRs 96969, 72266, 70728, 
                 73830, 67057, 27788, 20618   
01k,09jul04,rcs  Implemented netPoolCreate SPR 67057
01j,08jul04,rcs  Fixed SPR 98818 removed motFccReplenish call from ISR
01i,08jul04,rcs  Added recommended enhancements SPR 90135
01h,15jun04,mdo  SPR 96809
01g,09jun04,mdo  SPR fix 97909
01f,04jun04,mil  Changed cacheArchXXX funcs to cacheXXX funcs.
01e,30mar04,mdo  SPR's 81336, 93209, 94561, 94562 and general cleanup.
01d,02dec03,rcs  fixed warnings for base6
01c,20aug03,gjc  Fixed SPR #90352, fixed compiler warnings and removed logMsg
01b,13aug03,gjc  Fixed SPRs #89689, #89649, #87812, #87749, #90135, #86434 
01a,14jan03,gjc  SPR#85164 Second Generation Motorola FCC END Driver.
*/

/*
DESCRIPTION
This module implements a Motorola Fast Communication Controller (FCC)
Ethernet network interface driver. This is a second generation driver that is
based on the original motFccEnd.c. It differs from the original in
initialization, performance, features and SPR fixes.

The driver "load string" interface differs from its predecessor. A parameter
that contains a pointer to a predefined array of function pointers was added
to the end of the load string. This array replaces multiple individual function
pointers for dual ported RAM allocation, MII access, duplex control, and
heartbeat and disconnect functionality; it is described more fully below.
The array simplifies updating the driver and BSP code independently.

Performance of the driver has been greatly enhanced. A layer of unnecessary
queuing was removed. Time-critical functions were re-written to be more fluid
and efficient. The driver's work load is distributed between the interrupt and
the net job queue. Only one netJobAdd() call is made per interrupt.
Multiple events pending are sent as a single net job.

A new Generic MIB interface has been implemented.

Several SPRs, written against the original motFccEnd driver and previous motFcc2End
versions, are fixed.

The FCC supports several communication protocols. This driver supports the FCC
operating in Ethernet mode, which is fully compliant with the IEEE 802.3u
10Base-T and 100Base-T specifications.

The FCC establishes a shared memory communication system with the CPU,
which may be divided into three parts: a set of Control/Status Registers (CSR)
and FCC-specific parameters, the buffer descriptors (BD), and the data buffers.

Both the CSRs and the internal parameters reside in the MPC8260's internal
RAM. They are used for mode control, and to extract status information
of a global nature. For instance, by programming these registers, the driver
can specify which FCC events should generate an interrupt, whether
features like the promiscuous mode or the heartbeat are enabled, and so on.
Pointers to both the Transmit Buffer Descriptors ring (TBD) and the
Receive Buffer Descriptors ring (RBD) are stored in the internal parameter
RAM. The latter also includes protocol-specific parameters, such as the
individual physical address of the station and the maximum receive frame
length.

The BDs are used to pass data buffers and related buffer information
between the hardware and the software. They may reside either on the 60x
bus, or on the CPM local bus. They include local status information, and a
pointer to the receive or transmit data buffers. These buffers are located in
external memory, and may reside on the 60x bus, or the CPM local bus (see
below).

This driver is designed to be moderately generic. Without modification, it can
operate across all the FCCs in the MPC8260, regardless of where the internal
memory base address is located. To achieve this goal, this driver must be
given several target-specific parameters and some external support routines.
These parameters, and the mechanisms used to communicate them to the driver, 
are detailed below.

BOARD LAYOUT
This device is on-board.  No jumper diagram is necessary.

EXTERNAL INTERFACE

The driver provides the standard external interface, motFccEnd2Load(), which
takes a string of parameters delineated by colons. The parameters should be
specified in hexadecimal, optionally preceded by "0x" or a minus sign "-".

The parameter string is parsed using strtok_r() and each parameter is
converted from a string representation to binary by a call to
strtoul(parameter, NULL, 16).

The format of the parameter string is:

"<unit>:<immrVal>:<fccNum>:<bdBase>:<bdSize>:<bufBase>:<bufSize>:<fifoTxBase>:
<fifoRxBase> :<tbdNum>:<rbdNum>:<phyAddr>:<phyDefMode>:<phyAnOrderTbl>:
<userFlags>:<function table>(:<maxRxFrames>)"

TARGET-SPECIFIC PARAMETERS

\is
\i <unit>
This driver is written to support multiple individual device units.
This parameter is used to explicitly state which unit is being used.
Default is unit 0.
    
\i <immrVal>
Indicates the address at which the host processor presents its internal
memory (also known as the internal RAM base address). With this address,
and the <fccNum> value (see below), the driver is able to compute the
location of the FCC parameter RAM, and, ultimately, to program the FCC
for proper operation.

\i <fccNum>
This driver is written to support multiple individual device units.
This parameter is used to explicitly state which FCC is being used.

\i <bdBase>
The Motorola Fast Communication Controller is a DMA-type 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 FCC.

This parameter tells the driver that space for both the TBDs and the
RBDs need not be allocated, but should be taken from a cache-coherent
private memory space provided by the user at the given address. TBDs and RBDs
are both 8 bytes each, and individual descriptors must be 8-byte
aligned. The driver requires that an additional 8 bytes be provided for
alignment, even if <bdBase> is aligned to begin with.

If this parameter is "NONE", space for buffer descriptors is obtained
by calling cacheDmaMalloc() in motFccInitMem().

\i <bdSize>
The <bdSize> parameter specifies the size of the pre-allocated memory
region for the BDs. If <bdBase> is specified as NONE (-1), the driver ignores
this parameter. Otherwise, the driver checks that the size of the provided
memory region is adequate with respect to the given number of Transmit Buffer
Descriptors and Receive Buffer Descriptors (plus an additional 8 bytes for
alignment).

\i <bufBase>
This parameter tells the driver that space for data buffers
need not be allocated but should be taken from a cache-coherent
private memory space provided at the given address. The memory used for buffers
must be 32-byte aligned and non-cacheable. The FCC poses one more constraint, in
that DMA cycles may occur even when all the incoming data have already been
transferred to memory. This means at most 32 bytes of memory at the end of
each receive data buffer may be overwritten during reception. The driver
pads that area out, thus consuming some additional memory.

If this parameter is "NONE", space for buffer descriptors is obtained
by calling memalign() in motFccInitMem().

\i <bufSize>
The <bufSize> parameter specifies the size of the pre-allocated memory
region for data buffers. If <bufBase> is specified as NONE (-1), the driver
ignores this parameter. Otherwise, the driver checks that the size of the provided
memory region is adequate with respect to the given number of Receive Buffer
Descriptors and a non-configurable number of transmit buffers
 (MOT_FCC_TX_CL_NUM).  All the above should fit in the given memory space.
This area should also include room for buffer management structures.

\i <fifoTxBase>
Indicate the base location of the transmit FIFO, in internal memory.
The user does not need to initialize this parameter. The default
value (see MOT_FCC_FIFO_TX_BASE) is highly optimized for best performance.
However, if the user wishes to reserve that very area in internal RAM for
other purposes, this parameter may be set to a different value.

If <fifoTxBase> is specified as NONE (-1), the driver uses the default
value.

\i <fifoRxBase>
Indicate the base location of the receive FIFO, in internal memory.
The user does not need to initialize this parameter. The default
value (see MOT_FCC_FIFO_RX_BASE) is highly optimized for best performance.
However, if the user wishes to reserve that very area in internal RAM for
other purposes, this parameter may be set to a different value.

If <fifoRxBase> is specified as NONE (-1), the driver uses the default
value.

\i <tbdNum>
This parameter specifies the number of transmit buffer descriptors (TBDs).
Each buffer descriptor resides in 8 bytes of the processor's external
RAM space. If this parameter is less than a minimum number specified in
MOT_FCC_TBD_MIN, or if it is "NULL", a default value of MOT_FCC_TBD_DEF_NUM
is used. This parameter should always be an even number since each packet the 
driver sends may consume more than a single TBD.

\i <rbdNum>
This parameter specifies the number of receive buffer descriptors (RBDs).
Each buffer descriptor resides in 8 bytes of the processor's external
RAM space, and each one points to a buffer in external RAM. If this parameter 
is less than a minimum number specified in MOT_FCC_RBD_MIN, or if it is "NULL", 
a default value of MOT_FCC_RBD_DEF_NUM is used. This parameter should always be 
an even number.
                 
\i <phyAddr>
This parameter specifies the logical address of a MII-compliant physical
device (PHY) that is to be used as a physical media on the network.
Valid addresses are in the range 0-31. There may be more than one device
under the control of the same management interface. The default physical
layer initialization routine scans the whole range of PHY devices
starting from the one in <phyAddr>. If this parameter is
"MII_PHY_NULL", the default physical layer initialization routine finds
out the PHY actual address by scanning the whole range. The one with the lowest
address is chosen.

\i <phyDefMode>
This parameter specifies the operating mode that is set up
by the default physical layer initialization routine in case all
the attempts made to establish a valid link failed. If that happens,
the first PHY that matches the specified abilities is chosen to
work in that mode, and the physical link is not tested.

\i <phyAnOrderTbl>
This parameter may be set to the address of a table that specifies the
order how different subsets of technology abilities, if enabled, should be 
advertised by the auto-negotiation process. Unless the flag <MOT_FCC_USR_PHY_TBL>
is set in the userFlags field of the load string, the driver ignores this
parameter.

The user does not normally need to specify this parameter, since the default
behaviour enables auto-negotiation process as described in IEEE 802.3u.

\i <userFlags>
This field enables the user to give some degree of customization to the
driver.

MOT_FCC_USR_PHY_NO_AN: The default physical layer initialization
routine exploits the auto-negotiation mechanism as described in
the IEEE Std 802.3u, to bring a valid link up. According to it, all
the link partners on the media take part in the negotiation
process, and the highest priority common denominator technology ability
is chosen. To prevent auto-negotiation from occurring, set this bit in
the user flags.

MOT_FCC_USR_PHY_TBL: In the auto-negotiation process, PHYs
advertise all their technology abilities at the same time,
and the result is that the maximum common denominator is used. However,
this behaviour may be changed, and the user may affect the order how
each subset of PHY's abilities is negotiated. Hence, when the
MOT_FCC_USR_PHY_TBL bit is set, the default physical layer
initialization routine looks at the motFccAnOrderTbl[] table and
auto-negotiate a subset of abilities at a time, as suggested by the
table itself. It is worth noticing here, however, that if the
MOT_FCC_USR_PHY_NO_AN bit is on, the above table is ignored.

MOT_FCC_USR_PHY_NO_FD: The PHY may be set to operate in full duplex mode,
provided it has this ability, as a result of the negotiation with other
link partners. However, in this operating mode, the FCC ignores the
collision detect and carrier sense signals. To prevent negotiating full
duplex mode, set the MOT_FCC_USR_PHY_NO_FD bit in the user flags.

MOT_FCC_USR_PHY_NO_HD: The PHY may be set to operate in half duplex mode,
provided it has this ability, as a result of the negotiation with other link
partners. To prevent negotiating half duplex mode, set the
MOT_FCC_USR_PHY_NO_HD bit in the user flags.

MOT_FCC_USR_PHY_NO_100: The PHY may be set to operate at 100Mbit/s speed,
provided it has this ability, as a result of the negotiation with
other link partners. To prevent negotiating 100Mbit/s speed,
set the MOT_FCC_USR_PHY_NO_100 bit in the user flags.

MOT_FCC_USR_PHY_NO_10: The PHY may be set to operate at 10Mbit/s speed,
provided it has this ability, as a result of the negotiation with
other link partners. To prevent negotiating 10Mbit/s speed,
set the MOT_FCC_USR_PHY_NO_10 bit in the user flags.

MOT_FCC_USR_PHY_ISO: Some boards may have different PHYs controlled by the
same management interface. In some cases, it may be necessary to
electrically isolate some of them from the interface itself, in order
to guarantee a proper behaviour on the medium layer. If the user wishes to
electrically isolate all PHYs from the MII interface, the MOT_FCC_USR_PHY_ISO 
bit should be set. The default behaviour is to not isolate any PHY on the board.

MOT_FCC_USR_LOOP: When the MOT_FCC_USR_LOOP bit is set, the driver
configures the FCC to work in internal loopback mode, with the TX signal
directly connected to the RX. This mode should only be used for testing.

MOT_FCC_USR_RMON: When the MOT_FCC_USR_RMON bit is set, the driver 
configures the FCC to work in RMON mode, thus collecting network statistics
required for RMON support without the need to receive all packets as in
promiscuous mode.

MOT_FCC_USR_BUF_LBUS: When the MOT_FCC_USR_BUF_LBUS bit is set, the driver
configures the FCC to work as though the data buffers were located in the
CPM local bus.

MOT_FCC_USR_BD_LBUS: When the MOT_FCC_USR_BD_LBUS bit is set, the driver 
configures the FCC to work as though the buffer descriptors were located in the
CPM local bus.

MOT_FCC_USR_HBC: If the MOT_FCC_USR_HBC bit is set, the driver 
configures the FCC to perform heartbeat check following end of transmission
and the HB bit in the status field of the TBD is set if the collision
input does not assert within the heartbeat window. The user does not normally
need to set this bit.

\i <Function>
This is a pointer to the structure FCC_END_FUNCS. The structure contains mostly
FUNCPTRs that are used as a communication mechanism between the driver and the
BSP. If the pointer contains a NULL value, the driver uses system default
functions for the m82xxDpram DPRAM allocation and, obviously, the driver 
does not support BSP function calls for heartbeat errors, disconnect errors, and
PHY status changes that are hardware specific.
\is
\cs
    FUNCPTR miiPhyInit; 
\ce
\i BSP Mii/Phy Init Function
This function pointer is initialized by the BSP and called by the driver to
initialize the MII driver. The driver sets up it's PHY settings and then
calls this routine. The BSP is responsible for setting BSP specific PHY
parameters and then calling the miiPhyInit. The BSP is responsible to set
up any call to an interrupt. See miiPhyInt below.
\cs
    FUNCPTR miiPhyInt; 
\ce
\i Driver Function for BSP to Call on a Phy Status Change
This function pointer is initialized by the driver and called by the BSP.
The BSP calls this function when it handles a hardware MII specific
interrupt. The driver initializes this to the function motFccPhyLSCInt.
The BSP may or may not choose to call this function. It will depend if the
BSP supports an interrupt driven PHY. The BSP can also set up the miiLib
driver to poll. In this case the miiPhy driver calls this function. See
miiLib for details.
Note: Not calling this function when the PHY duplex mode changes