/* motFecEnd.c - END style Motorola FEC Ethernet network interface driver */

/* Copyright 1989-2003 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
02f,03mar04,dtr  Removing compiler warnings.
02e,24feb04,dtr  Added support for FEC2 specifically for MPC885.
02d,30jan03,m_h  IPv6 Support
02c,02may02,pmr  SPR 75008: only set txStall flag if motFecTbdClean() fails to 
		 free any Tx BDs in motFecSend().
02b,30apr02,rcs  SPR 76102: polling mode fix
02a,28jan02,rcs  changed motRevNumGet() to call vxImmrDevGet() SPR# 7120
01z,06dec01,rcs  changed REV_D_4 back to REV_D_3 SPR# 71420 
01y,04dec01,kab  Removed decl for vxImmrGet(), get from vxPpcLib.h
01x,26oct01,crg  fixed a possible cause of transmitter underruns by preventing
                 generation of TBDs with no data (SPR 29513)
                 added support for proper setting of MII management interface
                 speed (SPR 33812)
		 corrected clearing of receive events in motFecHandleRecvInt()
		 (SPR 69440)
01w,21sep01,dat  Removing ANSI errors for diab compiler (needs more work)
01v,15sep01,dat  Removed special definition of CACHE_PIPE_FLUSH
01u,01feb01,rcs  added motRevNumGet() using vxImmrGet()
01t,01feb01,rcs  merged in Motorola's modifications.
01s,29jan01,rcs  in motFecRxCtrlRegValGet initialized *rxCtrlVal (SPR# 63479)
01r,29jan01,rcs  in motFecTxCtrlRegValGet initialized *txCtrlVal (SPR# 63479)
01q,05dec00,dat  merge from sustaining branch to tor2_0_x
01p,21nov00,rhk  changes to initialization of FEC in order to support
                 rev. D.4 and newer 860T processors.
01o,05jul00,stv  fixed the coding error in motFecHashTblPopulate (SPR #31622).
01n,07jul00,stv  fixed the coding error in motFecHashTblPopulate (SPR# 31283).
01m,11jun00,ham  removed reference to etherLib.
01l,22may00,pai  Repaired (SPR #30673) by adding Keith Wiles' corrections to
                 hash register bit settings and his table driven CRC funtion.
                 Updated comments in motFecHashRegValGet().  Corrected the
                 coding error in motFecHashTblPopulate() (SPR #31283).
                 Released transmit semaphore and incremented MIB-II counter
                 in motFecSend() when returning ERROR as a result of being
                 called in polled mode.
01k,29mar00,pai  allocated memory for PHY_INFO struct in motFecEndLoad() (SPR
                 #30085).
01j,01feb00,pai  set driver control TX stall flag in motFecSend() if clean
                 TBD count becomes 0 (SPR #30135).
01i,27jan00,dat  fixed use of NULL
01h,05jan00,stv  removed private/funcBindP.h (SPR# 29875).
01g,06dec99,stv  corrected return error code and freed mBlk chain (SPR #28492).
01f,11nov99,cn   removed unnecessary freeing of pDrvCtrl in motFecUnload
		 (SPR# 28772).
01e,09sep99,rhk  added a check to make sure driver is operational before
                 shutting down in motFecStop.
01d,31aug99,rhk  disabled the MOT_FEC_DBG switch, pointed to the local
                 copy of ppc860Intr.h.
01c,19feb99,cn   corrected a bug in motFecMiiDiag ().
01b,09feb99,cn   changes required by performance improvement (SPR# 24883).
		 Also up-dated documentation, added probing of the device
		 in the motFecStart () routine.
01a,09nov98,cn   written.
*/

/*
DESCRIPTION
This module implements a Motorola Fast Ethernet Controller (FEC) network
interface driver. The FEC is fully compliant with the IEEE 802.3
10Base-T and 100Base-T specifications. Hardware support of
the Media Independent Interface (MII) is built-in in the chip.

The FEC establishes a shared memory communication system with the CPU,
which is divided into two parts: the Control/Status Registers (CSR),
and the buffer descriptors (BD).

The CSRs reside in the MPC860T Communication Controller's internal RAM.
They are used for mode control and to extract status information
of a global nature. For instance, the types of events that should
generate an interrupt, or features like the promiscous mode or the
max receive frame length may be set programming some of the CSRs properly.
Pointers to both the Transmit Buffer Descriptors ring (TBD) and the
Receive Buffer Descriptors ring (RBD) are also stored in the CSRs.
The CSRs are located in on-chip RAM and must be accessed using the
big-endian mode.

The BDs are used to pass data buffers and related buffer information
between the hardware and the software. They reside in the host main
memory and basically include local status information and a pointer
to the actual buffer, again in external memory.

This 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.

For versions of the MPC860T starting with revision D.4 and beyond
the functioning of the FEC changes slightly.  An additional bit has
been added to the Ethernet Control Register (ECNTRL), the FEC PIN
MUX bit.  This bit must be set prior to issuing commands involving
the other two bits in the register (ETHER_EN, RESET).  The bit must
also be set when either of the other two bits are being utilized.
For versions of the 860T prior to revision D.4, this bit should not
be set.

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

EXTERNAL INTERFACE

The driver provides the standard external interface, motFecEndLoad(), which
takes a string of colon-separated parameters. The parameters should be
specified in hexadecimal, optionally preceeded 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:

"<motCpmAddr>:<ivec>:<fecNum>:<bufBase>:<bufSize>:<fifoTxBase>:<fifoRxBase>
:<tbdNum>:<rbdNum>:<phyAddr>:<isoPhyAddr>:<phyDefMode>:<userFlags>
:<clockSpeed>"

TARGET-SPECIFIC PARAMETERS

.IP <motCpmAddr>
Indicates the address at which the host processor presents its internal
memory (also known as the dual ported RAM base address). With this address,
the driver is able to compute the location of the FEC parameter RAM, and,
ultimately, to program the FEC for proper operations.

.IP <ivec>
This driver configures the host processor 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 the VxWorks system function intConnect(). It is also used to
compute the interrupt level (0-7) associated with the FEC interrupt (one
of the MPC860T SIU internal interrupt sources). The latter is given as
a parameter to intEnable(), in order to enable this level interrupt to
the PPC core.

.IP <bufBase>
The Motorola Fast Ethernet 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 FEC.

This parameter tells the driver that space for the both the TBDs and the
RBDs needs 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 descriptors must be 8-byte
aligned and non-cacheable. All the buffer descriptors should fit
in the given memory space.

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

.IP <bufSize>
The memory size parameter specifies the size of the pre-allocated memory
region. If <bufBase> is specified as NONE (-1), the driver ignores this
parameter. Otherwise, the driver checks the size of the provided memory
region is adequate with respect to the given number of Transmit Buffer
Descriptors and Receive Buffer Descriptors.

.IP <fifoTxBase>
Indicate the base location of the transmit FIFO, in internal memory.
The user does not need to initialize this parameter, as the related
FEC register defaults to a proper value after reset. The specific
reset value is microcode dependent. However, if the user wishes to
reserve some RAM for other purposes, he may set this parameter to a
different value. This should not be less than the default.

If <fifoTxBase> is specified as NONE (-1), the driver ignores it.

.IP <fifoRxBase>
Indicate the base location of the receive FIFO, in internal memory.
The user does not need to initialize this parameter, as the related
FEC register defaults to a proper value after reset. The specific
reset value is microcode dependent. However, if the user wishes to
reserve some RAM for other purposes, he may set this parameter to a
different value. This should not be less than the default.

If <fifoRxBase> is specified as NONE (-1), the driver ignores it.

.IP <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, and each one points to a 1536-byte buffer again in external
RAM. If this parameter is less than a minimum number specified in the
macro MOT_FEC_TBD_MIN, or if it is "NULL", a default value of 64 is used.
This default number is kept deliberately hugh, since each packet the driver
sends may consume more than a single TBD. This parameter should always
equal a even number.

.IP  <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 1536-byte buffer again in external
RAM. If this parameter is less than a minimum number specified in the
macro MOT_FEC_RBD_MIN, or if it is "NULL", a default value of 48 is used.
This parameter should always equal a even number.

.IP  <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. If this parameter is
"NULL", the default physical layer initialization routine will find out the
PHY actual address by scanning the whole range. The one with the lowest
address will be chosen.

.IP  <isoPhyAddr>
This parameter specifies the logical address of a MII-compliant physical
device (PHY) that is to be electrically isolated by the management
interface. Valid addresses are in the range 0-31. If this parameter
equals 0xff, the default physical layer initialization routine will
assume there is no need to isolate any device. However, this parameter
will be ignored unless the MOT_FEC_USR_PHY_ISO bit in the <userFlags>
is set to one.

.IP  <phyDefMode>
This parameter specifies the operating mode that will be 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 will be chosen to
work in that mode, and the physical link will not be tested.

.IP  <userFlags>
This field enables the user to give some degree of customization to the
driver, especially as regards the physical layer interface.

.IP  <clockSpeed>
This field enables the user to define the speed of the clock being used
to drive the interface.  The clock speed is used to derive the MII
management interface clock, which cannot exceed 2.5 MHz.  <clockSpeed>
is optional in BSPs using clocks that are 50 MHz or less, but it is
required in faster designs to ensure proper MII interface operation.

MOT_FEC_USR_PHY_NO_AN: the default physical layer initialization
routine will exploit the auto-negotiation mechanism as described in
the IEEE Std 802.3, to bring a valid link up. According to it, all
the link partners on the media will take part to the negotiation
process, and the highest priority common denominator technology ability
will be chosen. It the user wishes to prevent auto-negotiation from
occurring, he may set this bit in the user flags.

MOT_FEC_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_FEC_USR_PHY_TBL bit is set, the default physical layer
initialization routine will look at the motFecPhyAnOrderTbl[] 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_FEC_USR_PHY_NO_AN bit is on, the above table will be ignored.

MOT_FEC_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 FEC will ignore the
collision detect and carrier sense signals. If the user wishes not to
negotiate full duplex mode, he should set the MOT_FEC_USR_PHY_NO_FD bit
in the user flags.

MOT_FEC_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. If the user wishes not to negotiate half duplex mode, he should
set the MOT_FEC_USR_PHY_NO_HD bit in the user flags.

MOT_FEC_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. If the user wishes not to negotiate 100Mbit/s speed,
he should set the MOT_FEC_USR_PHY_NO_100 bit in the user flags.

MOT_FEC_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. If the user wishes not to negotiate 10Mbit/s speed,
he should set the MOT_FEC_USR_PHY_NO_10 bit in the user flags.

MOT_FEC_USR_PHY_ISO: some boards may have different PHYs controlled by the
same management interface. In some cases, there may be the need of
electrically isolating 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 one PHY from the MII interface, he should set the
MOT_FEC_USR_PHY_ISO bit and provide its logical address in the <isoPhyAddr>
field of the load string. The default behaviour is to not isolate any
PHY on the board.

MOT_FEC_USR_SER: the user may set the MOT_FEC_USR_SER bit to enable
the 7-wire interface instead of the MII which is the default.

MOT_FEC_USR_LOOP: when the MOT_FEC_USR_LOOP bit is set, the driver will
configure the FEC to work in loopback mode, with the TX signal directly
connected to the RX. This mode should only be used for testing.

MOT_FEC_USR_HBC: if the MOT_FEC_USR_HBC bit is set, the driver will
configure the FEC to perform heartbeat check following end of transmisson
and the HB bit in the status field of the TBD will be set if the collision
input does not assert within the heartbeat window (also see _func_motFecHbFail,
below). The user does not normally need to set this bit.

.LP

EXTERNAL SUPPORT REQUIREMENTS
This driver requires three external support functions:
.IP sysFecEnetEnable()
.CS
    STATUS sysFecEnetEnable (UINT32 motCpmAddr);
.CE
This routine is expected to handle any target-specific functions needed
to enable the FEC. These functions typically include setting the Port D
on the 860T-based board so that the MII interface may be used, and also
disabling the IRQ7 signal. This routine is expected to return OK on
success, or ERROR. The driver calls this routine, once per device, from the
motFecEndLoad() routine.
.IP sysFecEnetDisable()
.CS
    STATUS sysFecEnetDisable (UINT32 motCpmAddr);
.CE
This routine is expected to perform any target specific functions required
to disable the MII interface to the FEC.  This involves restoring the
default values for all the Port D signals. This routine is expected to
return OK on success, or ERROR. The driver calls this routine from the
motFecEndStop() routine each time a device is disabled.
.IP sysFecEnetAddrGet()
.CS
STATUS sysFecEnetAddrGet (UINT32 motCpmAddr, UCHAR * enetAddr);
.CE
The driver expects this routine to provide the six-byte Ethernet hardware
address that is used by this device.  This routine must copy the six-byte
address to the space provided by <enetAddr>.  This routine is expected to
return OK on success, or ERROR.  The driver calls this routine, once per
device, from the motFecEndLoad() routine.
.IP `_func_motFecPhyInit'
.CS
    FUNCPTR _func_motFecPhyInit
.CE
This driver sets the global variable `_func_motFecPhyInit' to the
MII-compliant media initialization routine motFecPhyInit(). If the user
wishes to exploit a different way to configure the PHY, he may set
this variable to his own media initialization routine, tipically
in sysHwInit().
.IP `_func_motFecHbFail'
.CS
    FUNCPTR _func_motFecPhyInit
.CE
The FEC may be configured to perform heartbeat check following end
of transmission, and to generate an interrupt, when this event occurs.
If this is the case, and if the global variable `_func_motFecHbFail'
is not NULL, the routine referenced to by `_func_motFecHbFail' is called,
with a pointer to the driver control structure as parameter. Hence,
the user may set this variable to his own heart beat check fail routine,
where he can take any action he sees appropriate.
The default value for the global variable `_func_motFecHbFail' is NULL.
.LP

SYSTEM RESOURCE USAGE
If the driver allocates the memory to share with the Ethernet device,
it does so by calling the cacheDmaMalloc() routine.  For the default case
of 64 transmit buffers and 48 receive buffers, the total size requested
is 912 bytes, and this includes the 16-byte alignment requirement of the
device.  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 this memory region is non-cacheable
or if the hardware implements bus snooping.  The driver cannot maintain
cache coherency for the device because the BDs are asynchronously
modified by both the driver and the device, and these fields might share
the same cache line.

Data buffers are instead allocated in the external memory through the
regular memory allocation routine (memalign), and the related cache lines
are then flushed or invalidated as appropriate. The user should not allocate
memory for them.

TUNING HINTS