HAL I/O

The header file cyg/hal/proc_io.h provides definitions of MCF5275-specific on-chip peripherals. Many of the on-chip peripherals are compatible with those on the MCF5282 or other ColdFire processors, and for those peripherals it is the var_io.h header provided by the MCFxxxx variant HAL which provides the appropriate definitions. Both headers are automatically included by the architectural header cyg/hal/hal_io.h, so typically application code and other packages will just include the latter.

The MCF5275 reserves a 1GB 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.

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 MCF5275 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 MCF5275 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 0x27) and UART2 (interrupt 0x0F) are accidentally given the same priority and go off at the same time, the interrupt controller may actually issue an interrupt 0x2F, the bitwise-or of the two interrupt numbers. That interrupt belongs to the on-chip USB 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 USB hardware and not clear the system clock and UART 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 MCF5275 has 16K of cache. Usually this will be set up as a split cache, 8K for instructions and 8K 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 SRAM which may access external data, it may be possible to improve performance by using a 16K data cache instead of a split cache. This is controlled by CYGIMP_HAL_M68K_MCF5275_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.

The HAL also defines a macro HAL_MEMORY_BARRIER() which acts to synchronize the pipeline, delaying execution until all previous operations including all pending writes are complete. This will usually be necessary when interacting with devices that access memory directly.

Other Issues

The MCF5275 processor HAL does not affect the implementation of data types, stack size definitions, SMP support, system startup, or debug support. The MCFxxxx variant HAL versions of HAL_LSBIT_INDEX and HAL_MSBIT_INDEX are used since the processor supports the ff1.l and bitrev.l instructions. HAL_DELAY_US is implemented as a simple counting loop. HAL_IDLE_THREAD_ACTION may be defined depending on configuration option CYGIMP_HAL_M68K_MCF5275_IDLE.

Other Functionality

The processor HAL will instantiate a cyg_i2c_bus structure hal_mcfxxxx_i2c_bus when the configuration option CYGHWR_HAL_M68K_MCFxxxx_I2C is enabled. That option is enabled by default if various GPIO pins are configured appropriately. The implementation is provided by the CYGPKG_DEVS_I2C_MCFxxxx device driver. The processor HAL does not know what I²C devices may be attached to the bus so that is left to the platform HAL.

The processor HAL will instantiate a cyg_spi_bus structure hal_mcfxxxx_qspi_bus when the configuration option CYGHWR_HAL_M68K_MCFxxxx_SPI is enabled. That option is enabled by default if various GPIO pins are configured appropriately. The implementation is provided by the CYGPKG_DEVS_SPI_MCFxxxx_QSPI device driver. The processor HAL does not know what SPI devices may be attached to the bus so that is left to the platform HAL. All SPI device structures should be placed in the table mcfxxxx_qspi.