Subversion Repositories openrisc

    MCFxxxx ColdFire Processors

    CYGPKG_HAL_M68K_MCFxxxx

    eCos Support for Freescale MCFxxxx Processors

The Freescale ColdFire family is a range of processors including the

MCF5206 and the MCF5282. From a programmer's perspective these

processors all share basically the same processor core, albeit with

minor differences in the instruction set. They differ in areas like

performance, on-chip peripherals and caches. Even when it comes to

peripherals there is a lot of commonality. For example many but not

all Coldfire processors use the same basic interrupt controller(s) as

the MCF5282. Similarly the on-chip UARTs tend to use the same basic

design although there are variations in the number of UARTs, the fifo

sizes, and in certain details.

    The MCFxxxx variant HAL package

CYGPKG_HAL_M68K_MCFxxxx provides support for

various features that are common to many but not all Coldfire

processors. This includes HAL diagnostics via an on-chip UART and

interrupt controller management for those processors which have

MCF5282-compatible controllers. The variant HAL complements the M68K

architectural HAL package. An eCos configuration should also include a

processor-specific HAL package such as

CYGPKG_HAL_M68K_MCF5272 to support the

chip-specific peripherals and cache details, and a platform HAL

package such as CYGPKG_HAL_M68K_M5272C3 to support

board-level details like external memory chips. The processor or

platform HAL can override the functionality provided by the variant

HAL.

The MCFxxxx variant HAL package should be loaded automatically when

eCos is configured for appropriate target hardware. It should never be

necessary to load this package explicitly. Unloading the package

should only happen as a side effect of switching target hardware.

On most ColdFire platforms the variant HAL will provide the HAL

diagnostics support via one of the UARTs. Some platforms may provide

their own HAL diagnostics facility, for example output via an LCD. The

variant HAL diagnostics support is active if the processor or platform

implements the

CYGINT_HAL_M68K_MCFxxxx_DIAGNOSTICS_USE_DEFAULT

interface. It is also active only in configurations which do not rely

on an underlying rom monitor such as RedBoot:

if CYGSEM_HAL_USE_ROM_MONITOR is enabled then the

default diagnostics channel will automatically be inherited from

RedBoot. The variant HAL then provides a number of configuration

options related to diagnostics:

        CYGHWR_HAL_M68K_MCFxxxx_DIAGNOSTICS_PORT

This selects the destination for HAL diagnostics. The number of UARTs

available depends on the processor, and on any given board some of the

UARTs may not be connected. Hence the variant HAL looks for

configuration options

CYGHWR_HAL_M68K_MCFxxxx_UART0,

CYGHWR_HAL_M68K_MCFxxxx_UART1 and

CYGHWR_HAL_M68K_MCFxxxx_UART2 to see which on-chip

UARTs are actually available on the processor and target hardware, and

uses this information to let the user select a UART.

When a UART is in use as the HAL diagnostics channel, that UART

should not be used for any other purpose. In particular application

code should avoid using it for I/O via the serial driver.

        CYGNUM_HAL_M68K_MCFxxxx_DIAGNOSTICS_BAUD

When a UART is selected for HAL diagnostics this option specifies the

default baud rate. The most common setting is 38400. That provides a

compromise between performance and reliability, especially in

electrically noisy environments such as an industrial environment or a

test farm. Some platforms may define

CYGNUM_HAL_M68K_MCFxxxx_DIAGNOSTICS_DEFAULT_BAUD

to handle scenarios where another default baud rate is preferable,

typically for compatibility with existing software.

        CYGNUM_HAL_M68K_MCFxxxx_DIAGNOSTICS_ISRPRI

Usually the HAL diagnostics channel is driven in polled mode but in

some scenarios interrupts are required. For example, when debugging an

application over a serial line on top of the gdb stubs provided by

RedBoot, the user should be able to interrupt the application with a

control-C. The application will not be polling the HAL diagnostics

UART at this point so instead the eCos interrupt management code

interacts with the gdb stubs to do the right thing. This configuration

option selects the interrupt priority. It should be noted that on some

processors with MCF5282-compatible interrupt controllers all

priorities for enabled interrupts should be unique, and it is the

responsibility of application developers to ensure this condition is

satisfied.

This section describes how the MCFxxxx variant HAL package implements

parts of the eCos HAL specification. It should be read in conjunction

with similar sections from the architectural and processor HAL

documentation.

The cyg/hal/var_io.h header

provides various definitions for on-chip peripherals, where the

current processor has peripherals compatible with the MCF5282's.

This header is automatically included by the architectural

cyg/hal/hal_io.h so other

packages and application code will usually only include the latter.

It is up to the processor HAL to specify exactly what 

class="headerfile">var_io.h should export. For example the

MCF5213's proc_io.h header

contains the following:

# define HAL_MCFxxxx_HAS_MCF5282_INTC               1

# define HAL_MCFxxxx_INTC0_BASE                     (HAL_MCF521x_IPSBAR + 0x00000C00)

This enables support within the variant HAL for a single

MCF5282-compatible interrupt controller, and cases 

class="headerfile">var_io.h to export symbols such as:

#ifdef HAL_MCFxxxx_HAS_MCF5282_INTC

// Two 32-bit interrupt mask registers

# define HAL_MCFxxxx_INTCx_IMRH                     0x0008

# define HAL_MCFxxxx_INTCx_IMRL                     0x000C

…

# define HAL_MCFxxxx_INTCx_ICRxx_IL_MASK            (0x07 << 3)

# define HAL_MCFxxxx_INTCx_ICRxx_IL_SHIFT           3

Symbols such as HAL_MCFxxxx_INTCx_IMRH can be used

to access the relevant hardware registers via

HAL_READ_UINT32 and

HAL_WRITE_UINT32. Symbols like

HAL_MCFxxxx_INTCx_ICRxx_IL_MASK can be used to

generate or decode the contents of the hardware registers.

The header file does mostly use a naming convention, but is not

guaranteed to be totally consistent. There may also be discrepancies

with the documentation because the manuals for the various Coldfire

processors are not always consistent about their naming schemes.

All I/O definitions provided by the variant HAL will start with

HAL_MCFxxxx_, followed by the name of the

peripheral. If a peripheral is likely to be a singleton, for example

an on-chip flash unit, then the name is unadorned. If there may be

several instances of the peripheral then the name will be followed by

a lower case x. For example:

# define HAL_MCFxxxx_CFM_CR                         0x0000

…

# define HAL_MCFxxxx_UARTx_UMR                      0x00

Register names will be relative to some base address such as

HAL_MCFxxxx_CFM_BASE or

HAL_MCFxxxx_UART0_BASE, so code accessing a

register would look like:

    HAL_READ_UINT32(HAL_MCFxxxx_CFM_BASE + HAL_MCFxxxx_CFM_PROT, reg);

    …

    HAL_WRITE_UINT8(base + HAL_MCFxxxx_UARTx_UTB, '*');

Usually the register names are singletons, but in some cases such as

the interrupt controller priority registers there may be multiple

instances of the register and the names will be suffixed

appropriately. For example

HAL_MCFxxxx_INTCx_ICRxx_IL_MASK indicates the field

IL within one of the ICR

registers within one of the interrupt controllers.

As mentioned earlier the processor HAL's 

class="headerfile">proc_io.h will control which definitions

are exported by var_io.h.

Sometimes the processor HAL will then go on to undefine or redefine

some of the symbols, to reflect incompatibilities between the

processor's devices and the equivalent devices on the MCF5282. There

may also be additional symbols for the devices, and there will be

additional definitions for any processor-specific hardware. In

particular GPIO pin handling is handled by the processor HAL, not by

the variant HAL. Application developers should examine 

class="headerfile">proc_io.h as well as

var_io.h and the

processor-specific documentation to see exactly what I/O definitions

are provided. When porting to a new Coldfire processor it is best to

start with an existing processor HAL and copy

code as appropriate. A search for _HAS_ in

var_io.h will also be

informative.

All MCFxxxx processors support interrupts and exceptions in a uniform

way. When an interrupt or exception occurs the hardware pushes the

current program counter, the status register, and an additional 16-bit

word containing information about the interrupt source, for a total of

64 bits. Hence the PCSR part of a thread context consists of two

32-bit integers, and the variant HAL provides appropriate C and

assembler macros to examine and manipulate these.

Not all MCFxxxx processors have hardware floating point, so support

for this is left to the processor HAL package. Some MCFxxxx processors

have additional hardware units such as a multiply-accumulator, but

these are not currently supported by eCos.

The various MCFxxxx processors usually have one or more UARTs based on

very similar hardware. The variant HAL package can provide HAL

diagnostic support using such a UART. There are some minor differences

such as fifo sizes, and the UARTs will be accessed at different memory

locations. These differences are handled by a small number of macros

provided by the processor and platform HAL.

The MCFxxxx variant HAL only provides HAL diagnostic support via a

UART if the processor or platform HAL does not provide an alternative

implementation. That copes with situations where the on-chip UARTs are

not actually accessible on the target board and an alternative

communication channel must be used.

If the variant HAL should implement HAL diagnostics then the processor

or platform HAL should implement the CDL interface

CYGINT_HAL_M68K_MCFxxxx_DIAGNOSTICS_USE_DEFAULT. It

should also define one or more of

CYGHWR_HAL_M68K_MCFxxxx_UART0,

CYGHWR_HAL_M68K_MCFxxxx_UART1 and

CYGHWR_HAL_M68K_MCFxxxx_UART2, and ensure that any

multi-purpose GPIO pins are set correctly. The variant HAL will take

care of the rest.

The various MCFxxxx processors all have very different caches, so

support for these is deferred to the processor HAL.

All MCFxxxx processors support synchronous exceptions in a uniform

way, with the hardware pushing sufficient information on to the stack

to identify the nature of the exception. This means that the architectural

entry point hal_m68k_exception_vsr can be used as

the default VSR for all exceptions, with no need for separate

trampoline functions.

The variant HAL does not provide any special support for recovering

from exceptions.

All MCFxxxx processors supports interrupts in a uniform way. When an

interrupt occurs the hardware pushes sufficient information on to the

stack to identify the interrupt. Therefore the architectural entry

point hal_m68k_interrupt_vsr can be used as the

default VSR for all interrupts, with the variant just supplying a

small number of macros that allow the generic code to extract details of

the interrupt source. There is no need for separate trampoline

functions for every interrupt source.

On processors which have MCF5282-compatible interrupt and edge port

modules the variant HAL can provide the

HAL_INTERRUPT_MASK,

HAL_INTERRUPT_UNMASK,

HAL_INTERRUPT_SET_LEVEL,

HAL_INTERRUPT_ACKNOWLEDGE and

HAL_INTERRUPT_CONFIGURE macros. There is support

for processors with a single interrupt controller or with two separate

interrupt controllers. Otherwise these macros are left to the

processor HAL. The allocation of interrupt vectors to the various

on-chip devices is also a characteristic of the processor HAL.

proc_intr.h should be

consulted for appropriate definitions, for example

CYGNUM_HAL_ISR_UART0.

The mask and umask operations are straightforward: if the interrupt

controller has the SIMR and CIMR

registers those will be used; otherwise the IRM

registers will be updated by a read-modify-write cycle. The

acknowledge macro is only relevant for external interrupts coming in

via the edge port module and will clear the interrupt by writing to

the EPIER register. There is no simple way to clear

interrupts generated by the on-chip peripherals, so that is the

responsibility of the various device drivers or of application code.

The configure macro is only relevant for external interrupts and

involves manipulating the edge port module.

The HAL_INTERRUPT_SET_LEVEL macro is used

implicitly by higher level code such as

cyg_interrupt_create. With MCF5282-compatible

interrupt controllers the priority level corresponds to

the ICRxx register. The exact format depends on the

processor. Interrupt priorities corresponding to IPL level 7 are

non-maskable. Such interrupts cannot be managed safely by the usual

eCos ISR and DSR mechanisms. Instead application code will have to

install a custom VSR and manage the entire interrupt.

Some MCF5282-compatible interrupt controllers have a major

restriction: all interrupt priorities within each controller must be

unique. If two interrupts go off at the same time and have exactly the

same priority then the controllers' behaviour is undefined. In a

typical application some of the interrupts will be handled by eCos

device drivers while others will be handled directly by application

code. Since eCos cannot know which interrupts may get used, it cannot

allocate unique priorities. Instead this has to be left to the

application developer. eCos does provide configuration options such as

CYGNUM_KERNEL_COUNTERS_CLOCK_ISR_PRIORITY and

CYGNUM_DEVS_SERIAL_MCFxxxx_SERIAL0_ISR_PRIORITY to

provide control over the eCos-managed interrupts, and provides default

values for these which are unique.

Non-unique interrupt priorities can lead to very confusing system

behaviour. For example on an MCF5282, if the PIT3 system clock

(interrupt 0x3a) and ethernet RX frame (interrupt 0x1b) are

accidentally given the same priority and go off at the same time, the

interrupt controller may actually issue an interrupt 0x3b, the bitwise

or of the two interrupt numbers. That interrupt belongs to the on-chip

flash module. There may not be an installed handler for that interrupt

at all, and even if there is a handler it will only manipulate the

flash hardware and not clear the system clock and ethernet interrupts.

Hence the system is likely to go into a spin, continually trying to

service the wrong interrupt. To track down such problems during

debugging it may prove useful to install a breakpoint on the

hal_arch_default_isr function.

On processors with an MCF5282-compatible programmable interrupt timer

module or PIT, the variant HAL can provide the

HAL_CLOCK_INITIALIZE,

HAL_CLOCK_RESET,

HAL_CLOCK_READ and

HAL_CLOCK_LATENCY macros. These macros are used

by the eCos kernel to implement the system clock and may be used for

other purposes in non-kernel configurations. When multiple timers are

available it is up to the processor or platform HAL to select which

one gets used for the system clock. It is also up to the processor or

platform HAL to provide various clock-related configuration options

such as CYGNUM_HAL_RTC_PERIOD. Those options need

to take into account the processor clock speed, which is usually a

characteristic of the platform and hence not known to the variant HAL.

When porting to a new Coldfire processor, the processor or platform

HAL should define the symbols

CYGNUM_HAL_INTERRUPT_RTC,

_HAL_MCFxxxx_CLOCK_PIT_BASE_, and

_HAL_MCFxxxx_CLOCK_PIT_PRE_. Existing ports can be

examined for more details.

On processors with an MCF5282-compatible reset module or RST, the

variant HAL can provide the HAL_PLATFORM_RESET

macro. That macro is typically used by the gdb stubs support inside

RedBoot to reset the hardware between debug sessions, ensuring that

each session runs in as close to pristine hardware as possible. The

macro uses the SOFTRST bit of the

RCR register.

By default the variant HAL will provide versions of

HAL_LSBIT_INDEX and

HAL_MSBIT_INDEX which are more efficient than the

default ones in the architectural HAL. The implementation uses the

ff1.l and bitrev.l instructions.

If the Coldfire processor does not support these instructions then

the processor HAL should define

_HAL_M68K_MCFxxxx_NO_FF1_.

The MCFxxxx variant HAL does not affect the implementation of data

types, stack size definitions, idle thread processing, linker scripts,

SMP support, system startup, or debug support.

The MCFxxxx variant HAL only implements functionality defined in the

eCos HAL specification and does not export any additional functions.