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

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

/*
modification history
--------------------
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>:<bufBase>:<bufSize>:<fifoTxBase>:<fifoRxBase>
:<tbdNum>:<rbdNum>:<phyAddr>:<isoPhyAddr>:<phyDefMode>:<userFlags>"

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

The only adjustable parameters are the number of TBDs and RBDs that will be
created at run-time.  These parameters are given to the driver when 
motFecEndLoad() is called.  There is one RBD associated with each received 
frame whereas a single transmit packet normally uses more than one TBD.  For 
memory-limited applications, decreasing the number of RBDs may be 
desirable.  Decreasing the number of TBDs below a certain point will 
provide substantial performance degradation, and is not reccomended. An 
adequate number of loaning buffers are also pre-allocated to provide more 
buffering before packets are dropped, but this is not configurable.

The relative priority of the netTask and of the other tasks in the system
may heavily affect performance of this driver. Usually the best performance 
is achieved when the netTask priority equals that of the other 
applications using the driver.

SPECIAL CONSIDERATIONS

Due to the FEC8 errata in the document: "MPC860 Family Device Errata Reference"
available at the Motorola web site, the number of receive buffer
descriptors (RBD) for the FEC (see configNet.h) is kept deliberately high.
According to Motorola, this problem was fixed in Rev. B3 of the silicon.
In memory-bound applications, when using the above mentioned revision of
the MPC860T processor, the user may decrease the number of RBDs
to fit his needs.

SEE ALSO: ifLib,
.I "MPC860T Fast Ethernet Controller (Supplement to the MPC860 User's Manual)"
.I "Motorola MPC860 User's Manual",