M5213EVB Board

Description

The Motorola M5212EVB board has an MCF5213 ColdFire processor, support chips for the on-chip peripherals such as the UARTs and CAN bus, power and clock circuitry, a Zigbee chip attached to the MCF5213's SPI serial bus, some LEDs and switches, and an expansion connector for application-specific devices. The MCF5213 does not have an external memory bus, instead applications have to fit into the 256KB of on-chip flash and 32KB of on-chip SRAM.

The platform HAL package CYGPKG_HAL_M68K_M5213EVB provides the platform-specific support needed to configure and build eCos. It complements the M68K architectural HAL, the MCFxxxx variant HAL, and the MCF521x processor HAL. On the M5213EVB the role of the platform HAL is small compared with many other eCos platforms. The absence of an external memory bus means that the differences between one MCF5213 platform and the next will be comparatively small, and much of the work that would normally be done by the platform HAL can instead be done by the processor HAL. The main responsibilities of the platform HAL are to control the hardware clock and to define the default GPIO pin settings.

For typical application development eCos will be configured for a ROM startup. An application linked against eCos will be programmed into the base of flash, location 0x0, using a BDM debug solution. The application will run as soon as the board is reset, or it can be debugged over BDM using the m68k-elf-gdb debugger. Alternatively it is possible to configure eCos for a RAM startup, load the application into RAM via m68k-elf-gdb and BDM, and execute it from RAM. However with only 32KB of RAM to work with this will only be possible for comparatively simple applications. Even for ROM startup application complexity will be limited by the 32KB of SRAM for data and the 256KB of flash for code.

All configurations for the M5213EVB include serial, watchdog, flash, I2C and SPI device drivers. However these are not always active:

1. The serial device CYGPKG_DEVS_SERIAL_MCFxxxx is inactive unless the generic serial support CYGPKG_IO_SERIAL is loaded and the configuration option CYGPKG_IO_SERIAL_DEVICES is enabled. Exactly which of the on-chip UARTs are supported depends on options in the processor HAL such as CYGHWR_HAL_M68K_MCFxxxx_UART0, which in turn depend on the GPIO pin settings. With the default settings all three UARTs can be accessed via the serial device driver, using standard I/O facilities and names such as /dev/ser0. However by default UART0 will also be used as the HAL diagnostics channel and if so it should not be accessed via the serial driver. The MCFxxxx variant HAL and the serial device driver provide relevant configuration options.

2. The watchdog device driver CYGPKG_DEVS_WATCHDOG_MCFxxxx is inactive unless the generic watchdog support CYGPKG_IO_WATCHDOG is loaded into the configuration. The latter provides functions such as watchdog_reset for manipulating the watchdog.

3. The flash device driver CYGPKG_DEVS_FLASH_M68K_MCFxxxx_CFM is inactive unless the generic flash support CYGPKG_IO_FLASH is loaded into the configuration. The latter provides functions such as cyg_flash_program for manipulating the on-chip flash.

4. The I2C bus driver CYGPKG_DEVS_I2C_MCFxxxx is automatically available to the application and can be accessed through functions such as cyg_i2c_tx provided by the generic I2C package CYGPKG_IO_I2C. The M5213EVB board does not have any I2C devices on board but the I2C SDA and SCL signals can be accessed via the expansion connector so devices can be attached that way. It would then be up to the application to instantiate appropriate cyg_i2c_device structures. If the application does not use any I2C functionality then it will all be eliminated at link-time and the application will not suffer any unnecessary overheads. The I2C and FlexCAN support are mutually exclusive.

5. The SPI bus driver CYGPKG_DEVS_SPI_MCFxxxx_QSPI is automatically available to the application and can be accessed through functions such as cyg_spi_transfer provided by the generic SPI package CYGPKG_IO_SPI. The M5213EVB has a single on-board SPI device, the Zigbee chip, and the platform HAL provides a cyg_spi_device structure cyg_spi_zigbee_mc13191. The SPI signals are available on the expansion connector so additional devices can be attached that way. It would then be up to the application to instantiate appropriate cyg_spi_device structures. If the application does not use any SPI functionality then it will all be eliminated at link-time and the application will not suffer any unnecessary overheads

6. The FlexCAN device driver CYGPKG_DEVS_CAN_FLEXCAN is inactive unless the generic CAN support CYGPKG_IO_CAN is loaded into the configuration. It is also necessary to set the appropriate jumpers, specifically the CAN_EN jumpers must be closed and the COM_SEL jumpers must be set to CAN. The corresponding configuration option CYGHWR_HAL_M68K_M5213EVB_CAN_EN should then enabled. The driver provides a single channel, by default “can0”. The FlexCAN and I2C support are mutually exclusive.

The on-chip interrupt controller and the edge port module are managed by eCos using macros provided by the MCFxxxx variant HAL. PIT timer 1 is normally used to implement the eCos system clock. PIT timer 0 is unused and can be manipulated by the application. The remaining peripherals (DMA, GPT, DTIM, ADC, PWM, FLEXCAN) are not used by eCos.

Some standard eCos functionality is not available on the M5213EVB board. On most platforms in a development environment the RedBoot ROM monitor is programmed into flash, allowing applications to be loaded into RAM and debugged over a serial line or ethernet. This is not possible on an M5213EVB. Even if RedBoot's data requirements could be squeezed into the 32KB of available SRAM there would not be enough left for applications. Instead on an M5213EVB debugging involves a hardware debug solution such as BDM and the application is programmed directly into flash. Other eCos functionality such as the Robust Boot Loader (RBL) package or the common HAL's virtual vector mechanism are only relevant in systems containing RedBoot, so will not work on an M5213EVB. The 32KB RAM limitation also means that some of the more advanced eCos functionality such as TCP/IP networking, the JFFS2 flash file system, and gprof-based profiling, will not fit into an M5213EVB.

Setup and eCos Configuration

Both eCos and applications should be built using the GNU tools m68k-elf-gcc, m68k-elf-g++, and so on. The original port of eCos to the M5213EVB was done using m68k-elf-gcc version 3.4.4 (eCosCentric). Debugging generally involves the GNU debugger m68k-elf-gdb, either used directly at the command line or via an integrated development environment such as Eclipse. m68k-elf-gdb will operate via the processor's BDM port and the on-chip debug module. However the BDM modules shipped with M5213EVB boards require the use of proprietary code, so m68k-elf-gdb cannot drive the BDM modules directly. Instead the debugger interacts with a stub program m68k-elf-cfpe-stub, and it is the stub which drives the BDM module.

It is assumed that all the GNU tools and the stub program are already installed. These come with their own documentation. The examples below assume that the stub is already running and is listening for connections on TCP/IP port 9000. This can be achieved using, for example:

$ m68k-elf-cfpe-stub -m -l 9000 -t m5213evb -d USBMultilink
    

The M5213EVB board comes with a large number of jumpers. This means that the platform HAL does not automatically know which on-chip peripherals should be connected to the appropriate pins and which pins should be left for general purpose I/O. For example usually processor pin 7 will be used for the UART0 RX line but by removing a jumper it can be disconnected from the RS232 transceiver. Instead some other device can be hooked up to this pin via the expansion connector and the pin should be set up as a GPIO output to drive that device. Jumpers also control which input clock should be used, and that affects how eCos should initialize the clock hardware.

The default eCos configuration will assume the default jumper settings as follows:

The platform HAL does not concern itself with other jumpers such as those controlling the I2C pull-ups, although obviously these will have to be set appropriately if the corresponding on-chip peripherals are to function correctly.

If any of these jumper settings are changed then configuration options within the platform HAL will need to be changed accordingly. If some other clock input is enabled or if the system clock should run at some speed other than 80MHz then CYGHWR_HAL_M68K_M5213EVB_SYNCR and CYGHWR_HAL_SYSTEM_CLOCK_HZ should be edited. The first of these determines what gets programmed into the SYNCR register and the processor reference manual should be consulted for more information. The second informs eCos what the actual system clock speed will be. This depends on the hardware as well as the SYNCR setting so cannot be calculated.

If the LED_EN jumper is disconnected then the configuration option CYGHWR_HAL_M68K_M5213EVB_LED_EN should be disabled. Similary if any of the jumper blocks UART0_EN, UART1_EN or UART2_EN are disconnected then the corresponding configuration options CYGHWR_HAL_M68K_M5213EVB_UART0_EN etc. should be disabled. This assumes all of the jumpers in a jumper block are either in or out. If instead say UART1 still has its TX line connected but not RX, RTS or CTS then the processor HAL provides finer-grained configuration options such as CYGHWR_HAL_M68K_MCF521x_GPIO_PORTUB_UB1 which allow the application developer to specify exactly which pins should be used for what purpose.

The coarse-grained platform HAL options such as CYGHWR_HAL_M68K_M5213EVB_LED_EN are used to determine the default values of various processor HAL options such as CYGHWR_HAL_M68K_MCF521x_GPIO_PORTTC. Application developers can always edit the latter options rather than the platform HAL ones to gain full control over each pin. The processor HAL will initialize all the pins as per its GPIO options, and the information is also used by the configuration system to determine whether, for example, the serial device driver should allow access to UART2.

Assuming default jumper settings there is no need to change any of the configuration options. eCos can be built and applications linked as normal. Because only very simple applications will fit into the 32KB of on-chip SRAM the default startup mode is ROM, requiring that the application be programmed into flash at location 0. Any suitable flash programming utility can be used for this. eCos comes with its own utility ecoflash which can be used if desired. Assuming ecoflash has been correctly installed, to program an executable hello into flash would involve a command such as:

$ ecoflash -b m5213evb -t 'remote localhost:9000' program hello
    

The -b argument identifies the target hardware and the -t option informs ecoflash how to access the board in the current development environment. Here it is told to interact with an existing instance of the m68k-elf-cfpe-stub running on the same machine and listening on TCP/IP port 9000. For repeated use ecoflash supports various environment variables:

$ export ECOFLASH_BOARD=m5213evb
$ export ECOFLASH_TARGET='remote localhost:9000'
$ ecoflash program hello
    

The separate ecoflash documentation should be consulted for further details.

Once programmed into flash the application can be run simply by resetting the board. UART0 will be used for the HAL diagnostics channel so any output generated by the application will appear there. The default communication parameters are 8 bits, no parity, 1 stop bit, and 38400 baud. HAL diagnostics are managed by the MCFxxxx variant HAL and there are two main configuration options: CYGHWR_HAL_M68K_MCFxxxx_DIAGNOSTICS_PORT can be used to change the UART used or to cause diagnostics to be discarded completely; CYGNUM_HAL_M68K_MCFxxxx_DIAGNOSTICS_BAUD can be used to change the baud rate.

More commonly some debugging will be necessary and m68k-elf-gdb can be used for this. It can be invoked directly for command line use, or it may be used indirectly as the backend for an integrated development environment such as Eclipse. Typical command-line usage for a ROM startup application would involve:

$ m68k-elf-gdb --quiet hello
(gdb) set remote memory-write-packet-size 128
(gdb) set remote memory-read-packet-size 128
(gdb) target remote localhost:9000
Remote debugging using localhost:9000
0x0000045c in main (argc=9146, argv=0x0) at hello.c:53
(gdb) set $pc=hal_m68k_exception_reset
Current language:  auto; currently asm
(gdb) hbreak main
Hardware assisted breakpoint 1 at 0x420: file hello.c, line 48.
(gdb) c
Continuing.

Breakpoint 1, main (argc=9146, argv=0x0) at hello.c:48
48          CYG_TEST_INIT();
Current language:  auto; currently c
    

In typical usage most of these commands will be automated via a macro in the user's .gdbinit file. The first two commands limit the size of data transfers between gdb and the stub. This may or may not be necessary, but problems in this area have been observed with some versions of the tools. The target command connects gdb to an m68k-elf-cfpe-stub invocation running on the current machine and listening on TCP/IP port 9000. The entry point for an M5213EVB eCos application is hal_m68k_exception_reset. Normally the entry point is set automatically by gdb when the application is loaded into memory, but when debugging an application in flash there is no load phase so the program counter has to be set explicitly.

Normally gdb uses software breakpoints which means that it will modify the instructions in RAM to trigger a breakpoint exception. That is not possible for code in flash. Instead hardware breakpoints must be specified via the hbreak command instead of the more usual break command. The MCF5213 only supports four hardware breakpoints, one of which may be needed by gdb to implement functionality such as single-stepping at the C level, so debugging a flash-based application can prove more difficult than a RAM-based application. It should also be noted that m68k-elf-gdb has no built-in awareness of eCos data structures so there is no support for thread-aware debugging. On other platforms it is the target-side gdb stubs embedded into RedBoot that provide such support.

For very simple applications where both code and data will fit into the 32KB of available SRAM it is possible to set the configuration option CYG_HAL_STARTUP to RAM and then build eCos and the application for that startup. Running such an application via command-line gdb involves:

% m68k-elf-gdb --quiet hello
(gdb) set remote memory-write-packet-size 128
(gdb) set remote memory-read-packet-size 128
(gdb) target remote localhost:9000
Remote debugging using localhost:9000
(gdb) load
Loading section .ram_vectors, size 0x200 lma 0x20000000
Loading section .m68k_start, size 0x48 lma 0x20000200
Loading section .text, size 0x46ac lma 0x20000248
Loading section .rodata, size 0x585 lma 0x200048f4
Loading section .data, size 0x17c lma 0x20004e7c
Start address 0x20000200, load size 20469
Transfer rate: 50385 bits/sec, 108 bytes/write.
(gdb) break main
Breakpoint 1 at 0x2000038e: file hello.c:48
(gdb) c
Continuing.

Breakpoint 1, main (argc=9146, argv=0x0) at hello.c:48
48         CYG_TEST_INIT();
(gdb)
    

The same commands are used to connect to the stub and to set the communication parameters, and again a gdb macro would normally be used for this. The application is then loaded into RAM, which automatically sets the program counter. Ordinary software breakpoints can now be used.

HAL Port Implementation Details

The M5213EVB platform HAL has very limited functionality compared with more typical eCos platform HALs. Because there is no external memory bus much of the work normally done by the platform HAL can instead be done higher up in the MCF521x processor HAL, and hence the code can be shared with other MCF521x-based platforms.

The M5213EVB platform HAL does not override the behaviour of any of the higher-level HALs. The M68K architectural HAL handles the bulk of system startup, interrupt and exception handling, thread context management, and the main linker script. The MCFxxxx variant HAL provides the diagnostics support, interrupt controller management, the system clock, reset, microsecond delay, and the LSBIT and MSBIT utility macros. The MCF521x processor HAL defines the memory map and provides processor-specific startup code, idle thread support. It also initializes the GPIO pins, and instantiates flash, SPI and I2C bus devices. The platform HAL mainly provides the default settings for the GPIO pins and the system clock.

When the configuration option CYGHWR_HAL_M68K_M5213EVB_LED_EN is enabled, indicating that the four LEDs are connected to the appropriate GPIO pins, the platform HAL package provides a utility function for manipulating the LEDs:

#include <cyg/hal/hal_arch.h>

externC void hal_m5213evb_led_set(int, int);
    

The first argument identifies the LED and should be a number between 0 and 3. The second argument should be 1 to switch the LED on, 0 to switch it off.

When SPI support is enabled in the processor HAL via the configuration option CYGHWR_HAL_M68K_MCF521x_SPI the platform HAL will instantiate a cyg_spi_device structure cyg_spi_zigbee_mc13192 for the on-board Zigbee chip. The platform HAL does not attempt to initialize or otherwise interact with this chip.

The platform HAL provides the necessary support for the ecoflash flash programming utility. The m5213evb.ecf configuration file and the m5213evb_flash.elf target-side executable may have been installed automatically when you installed eCos. If not, the misc subdirectory contains the configuration file and a configuration template ecoflash.ecm which can be used to rebuild the target-side executable.