HAL I/O

The header file cyg/hal/proc_io.h provides definitions of all on-chip peripherals, except for some UART definitions which are provided by the variant HAL instead. This header file is automatically included by the architectural header cyg/hal/hal_io.h, so typically application code and other packages will just include the latter. There are default INIT macros for the various on-chip devices which can be used by platform initialization code, although on any given platform some of the devices may need special attention.

The MCF5282 reserves a 1-gbyte area of memory for the internal peripheral space. Usually this is mapped between 0x40000000 and 0x7fffffff. Most of this space is not used, but accessing it can cause problems including apparently locking up the processor such that either a hard reset or a watchdog timeout is needed. The target-side gdb stubs code can trap most accesses initiated by host-side gdb, but cannot protect against errant accesses by application code.

It should be noted that the Freescale documentation is occasionally confusing when it comes to numbering devices. For example the four on-chip programmable timers are numbered PIT1 to PIT4, but in the interrupt controller the corresponding interrupts are numbered PIT0 to PIT3. The eCos port consistently starts numbering at 0, so the timers have been renamed PIT0 to PIT3.

Interrupt Handling

The header file cyg/hal/proc_intr.h provides VSR and ISR vector numbers for all interrupt sources. The VSR vector number, for example CYGNUM_HAL_VECTOR_TMR0, should be used for calls like cyg_interrupt_get_vsr. It corresponds directly to the M68K exception number. The ISR vector number, for example CYGNUM_HAL_ISR_TMR0, should be used for calls like cyg_interrupt_create. This header file is automatically included by the architectural header cyg/hal/hal_intr.h, and other packages and application code will normally just include the latter.

The eCos HAL macros HAL_INTERRUPT_MASK, HAL_INTERRUPT_UNMASK, HAL_INTERRUPT_ACKNOWLEDGE, and HAL_INTERRUPT_CONFIGURE are implemented by the processor HAL. The mask and unmask operations are straightforward, simply manipulating the IMR registers in the on-chip interrupt controllers. 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 other sources. Instead each such interrupt has to be cleared in a device-specific way, and that is the responsibility of the appropriate device driver. The configure macro is only relevant for external interrupts and involves manipulating the edge port module.

The HAL_INTERRUPT_SET_LEVEL macro, used implicitly by higher level code such as cyg_interrupt_create, is also implemented by the processor HAL. In the MCF5282 processor interrupt priorities have to be managed very carefully. Interrupts are managed via two interrupt controllers, INTC0 and INTC1. Each controller contains ICRxx control registers for each interrupt to manage that interrupt's priority. The HAL_INTERRUPT_SET_LEVEL macro simply fills in the ICRxx register.

An ICRxx value is a six-bit number. The top three bits correspond to the standard M68K IPL interrupt level. The bottom three bits give a finer-grained priority within that IPL level. For example, if the priority argument to cyg_interrupt_create is 42 then that corresponds to an IPL level of 5 and a finer-grained priority of 2. If the system has been configured to support nested interrupts and a level 42 interrupt goes off, the processor's IPL level will be set to 5 so all interrupts with priorities < 48 will remain blocked. The finer-grained priority controls what happens when two interrupts with the same IPL level go off at the same time.

Interrupt priorities between 0 and 7 would correspond to an IPL level of 0. The interrupt controller can only raise an interrupt if the IPL level is at least 1, so the smallest valid interrupt priority is 8. Interrupt priorities between 56 and 63 correspond to IPL level 7, and such interrupts are non-maskable and must be used with care. These 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. This means that interrupt priorities should normally be in the range 8 to 55.

As a special case, external interrupts coming in via the edge port module have hard-wired priorities which do not clash with the programmable ones. For these the priority argument to HAL_INTERRUPT_SET_LEVEL and higher-level code is ignored.

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

To ensure that the configured interrupt priorities are unique the processor HAL comes with a test case intrpri. The source code for this can be found in the package's tests subdirectory. The test examines the ICRxx registers in both interrupt controllers. It will report all priorities that are in use, and report a failure if a non-unique priority is detected. This code may prove useful for application developers trying to allocate interrupt priorities.

Caution

Non-unique interrupt priorities can lead to very confusing system behaviour. For example 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.

Clock Support

The processor HAL provides support for the eCos system clock. This always uses hardware timer PIT3, which should not be manipulated directly by application code. If gprof-based profiling is enabled then that will use hardware timer PIT2. PIT timers 0 and 1 are never used by eCos so application code is free to manipulate these as required.

Some of the configuration options related to the system clock, for example CYGNUM_HAL_RTC_PERIOD, are actually contained in the platform HAL rather than the processor HAL. These options need to take into account the processor clock speed, a characteristic of the platform rather than the processor.

Cache Handling

The MCF5282 has 2K of cache. Usually this will be set up as a split cache, 1K for instructions and 1K for data, which should give the best performance for typical applications. The standard HAL cache macros are supported.

On some platforms it may be better to organize the cache differently. For example if the platform involves running code only out of internal flash but may access external data, it may be possible to improve performance by using a 2K data cache instead of a split cache. This is controlled by CYGIMP_HAL_M68K_MCF5282_CACHE_MODE, which may be either a fixed #define or a configuration option depending on the platform. For more details see the header file proc_cache.h.

Other Issues

The MCF5282 processor HAL does not affect the implementation of data types, stack size definitions, bit indexing, idle thread processing, linker scripts, SMP support, system startup, or debug support.

Other Functionality

The MCF5282 processor HAL only implements functionality defined in the eCos HAL specification and does not export any additional functions.