Some members of the Freescale ColdFire family of processors come with an on-chip ethernet device. This package provides an eCos driver for that device. The driver supports both polled mode for use by RedBoot and interrupt-driven mode for use by a full TCP/IP stack.
The original version of the driver was written specifically for the MCF5272 processor. It has since been made to work on other members of the ColdFire family.
There are in fact two driver implementations within this driver package, one standard driver suitable for use with various TCP/IP stacks including at least RedBoot, BSD and lwIP; and one specific to lwIP. The lwIP-specific driver is a streamlined efficient version designed for very low RAM overhead. As a result it is implemented intentionally at the expense of features such as multiple network device support, and network debugging under RedBoot, but has improvements such as zero-copy reception as well as zero-copy transmission if certain constraints are met by the data packet to be transmitted.
This ethernet package should be loaded automatically when
selecting a target containing a ColdFire processor with on-chip
ethernet, and it should never be necessary to load it explicitly. If
the application does not actually require ethernet functionality then
the package is inactive and the final executable will not suffer any
overheads from unused functionality. This is determined by the
presence of the generic ethernet I/O package
CYGPKG_IO_ETH_DRIVERS. Typically the choice of eCos
template causes the right thing to happen. For example the default
template does not include any TCP/IP stack so
CYGPKG_IO_ETH_DRIVERS is not included, but the
net, redboot and lwip_eth templates do include a TCP/IP stack so will
specify that package and hence enable the ethernet driver.
The choice between using the standard driver, or the lwIP-specific
driver is not made within this package, but is instead made in the
generic ethernet I/O package
using the options within the lwIP driver model component
standard driver is the default.
All eCos network devices need a unique name. By default the on-chip
ethernet device is assigned the name eth0 but
can be changed through the configuration option
CYGDAT_DEVS_ETH_MCFxxxx_NAME. This is useful if for
example the target hardware includes a number of additional off-chip
ethernet devices. This setting is unused for the lwIP-specific driver.
The hardware requires that incoming ethernet frames are received
into one of a small number of buffers, arranged in a ring. Once a
frame has been received and its size is known the driver will pass it
up to higher-level code for further processing. The number of these
buffers is configurable via the option
CYGNUM_DEVS_ETH_MCFxxxx_RXBUFFERS. In the standard
ethernet driver, each receive buffer requires 1528 bytes of memory;
with the lwIP-specific driver, the size of each buffer is set with
the lwIP option
and multiple buffers are chained if needed to fulfil the requirements
of incoming frames.
A smaller number of buffers
increases the probability that incoming ethernet frames have to be
discarded. TCP/IP stacks are designed to cope with the occasional lost
packet, but if too many frames are discarded then this will greatly
affect performance. A key issue here is that passing the incoming
frames up to higher-level code typically happens at thread level and
hence the system behaviour is defined in large part by the priority of
various threads running in the TCP/IP stack. If application code has
high-priority threads that take up much of the available cpu time and
the TCP/IP stack gets little chance to run then there will be little
opportunity to pass received frames up the stack. Balancing out the
various thread priorities and the number of receive buffers is the
responsibility of the application developer.
By default the ethernet driver will raise interrupts using a low
priority level. The exact value will depend on the processor being
used, for example the MCF5282 interrupt controllers impose specific
constraints on interrupt priorities. The driver does very little at
interrupt level, instead the real work is done via threads inside the
TCP/IP stack. Hence the interrupt priority has little or no effect on
the system's behaviour. If the default priorities are inappropriate for
some reason then they can be changed through the configuration options
There is an option related to the default network MAC address,
CYGDAT_DEVS_ETH_MCFxxxx_PLATFORM_MAC. This is
discussed in more detail below.
Optionally the ethernet driver can maintain statistics about the
number of incoming and transmitted ethernet frames, receive overruns,
collisions, and other conditions. Maintaining and providing these
statistics involves some overhead, and is controlled by the
CYGFUN_DEVS_ETH_MCFxxxx_STATISTICS. Typically these
statistics are only accessed through SNMP, so by default statistics
gathering is enabled if the configuration includes
CYGPKG_SNMPAGENT and disabled otherwise.
The ColdFire processors do not have a built-in unique network MAC address since that would require slightly different manufacturing for each chip. All ethernet devices should have a unique address so this has to come from elsewhere. There are a number of possibilities:
The platform HAL can provide the address. For example the target board may have a small serial EPROM or similar which is initialized during board manufacture. The platform HAL can read the serial EPROM during system startup and provide the information to the ethernet driver. If this is the case then the platform HAL should implement the CDL interface
CYGINT_DEVS_ETH_MCFxxxx_PLATFORM_MACand provide a macro
HAL_MCFxxxx_ETH_GET_MAC_ADDRESSin the exported header cyg/hal/plf_arch.h.
There is a configuration option
CYGDAT_DEVS_ETH_MCFxxxx_PLATFORM_MACwhich specifies the default MAC address. Manipulating this option is fine if the configuration will only be used on a single board. However if multiple boards run applications with the same configuration then they would all have the same MAC address, and the resulting behaviour is undefined.
If the target hardware boots via RedBoot and uses a block of flash to hold configuration variables then one of these variables will be the MAC address. It can be manipulated at the RedBoot prompt using the fconfig command, thus giving each board a unique address. An eCos application containing the ethernet driver will automatically pick up this address.
When designing a new target board it is recommended that the board comes with a unique network address supported by the platform HAL, rather than relying on users to change the address. The latter approach can be error-prone and will lead to failures that are difficult to track down.
The on-chip ethernet hardware relies on an external media independent interface (MII), also known as a PHY chip. This separate chip handles the low-level details of ethernet communication, for example negotiating a link speed with the hub. In most scenarios the PHY chip simply does the right thing and needs no support from the ethernet driver. If there are special requirements, for example if the board has to be hardwired to communicate at 10Mbps rather than autonegotiate the link speed, then usually this is handled by fixed logic levels on some of the PHY pins or by using jumpers.
The eCos ethernet driver assumes that the PHY is already fully operational and does not interact with it in any way. If the target hardware does require software initialization of the PHY chip then usually this will be done in the platform HAL, because the choice of PHY chip is a characteristic of the platform.