CYGPKG_HAL_M68K_M5213EVB — eCos Platform HAL


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 a BDM device such as the Ronetix PEEDI 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, I²C 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 I²C 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 I²C package CYGPKG_IO_I2C. The M5213EVB board does not have any I²C devices on board but the I²C 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 I²C functionality then it will all be eliminated at link-time and the application will not suffer any unnecessary overheads. The I²C 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 I²C 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). The recommended BDM debug solution is the Ronetix PEEDI. This requires a configuration file peedi.cfg which can be found in the platform HAL's misc directory. The configuration file will initialize the hardware in the same way as the ROM startup code. It will need minor edits, for example to specify the correct license keys and to select the CORE_FLASH for the M5213EVB. For full details see the Ronetix documentation.


Application development using eCosPro releases prior to version 3.1 operated via the processor's BDM port, the on-chip debug module and a proprietary stub program m68k-elf-cfpe-stub. This is no longer supported.

Once the PEEDI is set up applications can be linked against an eCos configuration built with either RAM or ROM startup mode. Applications can then be debugged via m68k-elf-gdb either used directly at the command line or via an integrated development environment such as Eclipse.

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:

CLKSEL 1 and 2 in, 3 to 6 out
Use the external 8MHz reference crystal oscillator Y1 in PLL mode. This will be multiplied internally to give an 80MHz system clock.
UART0_EN all in, UART1_EN all in, UART2_EN all in
All on-chip UARTs have all of TX, RX, RTS and CTS connected to the RS232 transceivers.
COM_SEL all set tot UART
The DB9 socket for UART2_CAN carries the UART2 signals.
The processor can drive the LEDs.
The debug port is used for BDM and not JTAG.

The platform HAL does not concern itself with other jumpers such as those controlling the I²C 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 as well as the Ronetix PEEDI. Assumed that all the GNU tools are already installed, the examples below assume that a PEEDI JTAG/BDM debugger is attached to the M5213EVB and listening for connections on TCP/IP port 9000.

Programming ROM images with a Ronetix PEEDI

This section describes how to program ROM images using a Ronetix PEEDI debugger.

The PEEDI must be configured to allow communication with your local network, and configured with the parameters for interfacing with the target board. It must then be used to download and program the ROM image into the internal flash. The following steps give a typical outline for doing this. Consult the PEEDI documentation for alternative approaches, such as using FTP or HTTP instead of TFTP.

Preparing the Ronetix PEEDI JTAG/BDM debugger

  1. Prepare a PC to act as a host and start a TFTP server on it.
  2. Connect the PEEDI JTAG/BDM debugger via both serial and ethernet to the host PC and power it on. Use the serial cable supplied with the PEEDI (straight through, not null modem).
  3. Verify the PEEDI is using up-to-date firmware, of version 11.10.1 or later. If the firmware is not recent enough, follow the PEEDI User Manual's instructions which describe how to update the PEEDI firmware.
  4. Locate the PEEDI configuration file peedi.cfg within the eCos platform HAL package in the source repository. This will be in the directory packages/hal/m68k/mcf52xx/mcf521x/m5213evb/VERSION/misc relative to the root of your eCos installation.
  5. Place the PEEDI configuration file in a location on the PC accessible to the TFTP server. Later you will configure the PEEDI to load this file via TFTP as its configuration file.
  6. Open peedi.cfg in an editor such as emacs or notepad and insert your own license information in the [LICENSE] section.
  7. Install and configure the PEEDI in line with the PEEDI Quick Start Guide or User's Manual, especially configuring PEEDI's RedBoot with the network information. Configure it to use the peedi.cfg target configuration file on the TFTP server at the appropriate point of the config process, for example with a path such as: tftp://
  8. Reset the PEEDI.
  9. Connect to the PEEDI's CLI interface via TCP/IP on the standard telnet port 23. The telnet application is suitable for this. You should see output similar to the following:

    $ telnet peedi-0
    Connected to peedi-0.
    Escape character is '^]'.
    PEEDI - Powerful Embedded Ethernet Debug Interface
    Copyright (c) 2005-2011 - All rights reserved
    Hw:1.2, L:BDM v1.1 Fw:11.10.1, SN: PD-XXXX-XXXX-XXXX

Preparing the M5213EVB for programming with PEEDI

Follow the steps in this section in order to allow communication between the board and the host PC, and between the board and the BDM device.

If programming a GDB stub ROM or an application which uses serial output, you should first:

  1. Connect an adaptor from the serial pins on the board to an RS232 DB9 serial connector or cable, then connect from there to a serial port on the host computer with a null modem DB9 RS232 serial cable.
  2. Start a suitable terminal emulator on the host computer such as minicom on Linux or PuTTY on Windows. Set the communication parameters to 38400 baud, 8 data bits, no parity bit and 1 stop bit with no flow control.

For all applications, you must:

  1. Connect the board to the PEEDI using an appropriate cable from the BDM interface connector to the Target port on the PEEDI.
  2. Power up the M5213EVB.
  3. Connect to the PEEDI's telnet CLI on port 23 as before.
  4. Confirm correct connection with the PEEDI with the reset reset command as follows:

    m5213evb> reset reset
    ++ info: RESET and BKPT asserted
    ++ info: RESET released
    ++ info: BKPT released
    ++ info: core 0: initialized

Installation into Flash using the Ronetix PEEDI

The following describes the procedure for installing a ROM application into on-chip Flash using the Ronetix PEEDI, using the tm_basic test as an example of such an application.

  1. Use m68k-elf-objcopy to convert the linked application, in ELF format, into binary format. For example:

    $ m68k-elf-objcopy -O binary programname programname.bin
  2. Copy the binary file (.bin file) into a location on the host computer accessible to its TFTP server.
  3. Connect to the PEEDI's telnet interface, and program the image into Flash with the following command, replacing TFTP_SERVER with the address of the TFTP server and /BINPATH with the location of the .bin file relative to the TFTP server root directory. For example for the tm_basic test:

    m5213evb> flash program tftp://TFTP_SERVER/BINPATH/tm_basic.bin bin 0x0 erase
    ++ info: Programming image file: tftp://TFTP_SERVER/BINPATH/tm_basic.bin
    ++ info: Programming directly
    ++ info: At absolute address:    0x00000000
    erasing     at 0x00000000 (page #0)
    erasing     at 0x00000800 (page #1)
    programming at 0x00000000
    erasing     at 0x00001000 (page #2)
    erasing     at 0x00001800 (page #3)
    programming at 0x00001000
    erasing     at 0x00002000 (page #4)
    erasing     at 0x00002800 (page #5)
    programming at 0x00002000
    erasing     at 0x00003000 (page #6)
    erasing     at 0x00003800 (page #7)
    programming at 0x00003000
    erasing     at 0x00004000 (page #8)
    erasing     at 0x00004800 (page #9)
    programming at 0x00004000
    erasing     at 0x00005000 (page #10)
    erasing     at 0x00005800 (page #11)
    programming at 0x00005000
    erasing     at 0x00006000 (page #12)
    erasing     at 0x00006800 (page #13)
    programming at 0x00006000
    erasing     at 0x00007000 (page #14)
    erasing     at 0x00007800 (page #15)
    programming at 0x00007000
    erasing     at 0x00008000 (page #16)
    erasing     at 0x00008800 (page #17)
    programming at 0x00008000
    erasing     at 0x00009000 (page #18)
    erasing     at 0x00009800 (page #19)
    programming at 0x00009000
    erasing     at 0x0000A000 (page #20)
    erasing     at 0x0000A800 (page #21)
    programming at 0x0000A000
    erasing     at 0x0000B000 (page #22)
    erasing     at 0x0000B800 (page #23)
    programming at 0x0000B000
    ++ info: successfully programmed 48.00 KB in 1.45 sec

Once programmed into flash the application can be run simply by resetting the board. This may be acheived through the PEEDI telnet session by running the command reset reset and issuing the go command. For example:

m5213evb> reset reset
++ info: user reset
++ info: RESET and BKPT asserted
++ info: RESET released
++ info: BKPT released
++ info: core 0: initialized

m5213evb> go

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. In the case of the tm_basic image, output similar to the following should be visible:

Example 327.1. m5213evb Real-time characterization

INFO:<code from 0x00000000 -> 0x0000a900, CRC e654>
            Startup, main stack : stack used   356 size  2152
             Startup : Idlethread stack used    76 size  1280

eCos Kernel Timings
Notes: all times are in microseconds (.000001) unless otherwise stated

Reading the hardware clock takes 0 'ticks' overhead
... this value will be factored out of all other measurements
Clock interrupt took   14.28 microseconds (14 raw clock ticks)

Testing parameters:
   Clock samples:            32
   Threads:                   2
   Thread switches:         128
   Mutexes:                  32
   Mailboxes:                21
   Semaphores:               32
   Scheduler operations:    128
   Counters:                 32
   Flags:                    32
   Alarms:                   32

     Ave     Min     Max     Var  Ave  Min  Function
  ======  ======  ======  ====== ========== ========
   13.00   13.00   13.00    0.00  100% 100% Create thread
    2.50    2.00    3.00    0.50  100%  50% Yield thread [all suspended]
    3.00    3.00    3.00    0.00  100% 100% Suspend [suspended] thread
    3.00    3.00    3.00    0.00  100% 100% Resume thread
    4.00    4.00    4.00    0.00  100% 100% Set priority
    0.50    0.00    1.00    0.50  100%  50% Get priority
    7.50    7.00    8.00    0.50  100%  50% Kill [suspended] thread
    2.50    2.00    3.00    0.50  100%  50% Yield [no other] thread
    4.00    4.00    4.00    0.00  100% 100% Resume [suspended low prio] thread
    2.00    2.00    2.00    0.00  100% 100% Resume [runnable low prio] thread
    4.00    4.00    4.00    0.00  100% 100% Suspend [runnable] thread
    3.00    3.00    3.00    0.00  100% 100% Yield [only low prio] thread
    3.00    3.00    3.00    0.00  100% 100% Suspend [runnable->not runnable]
    8.00    8.00    8.00    0.00  100% 100% Kill [runnable] thread
    6.00    6.00    6.00    0.00  100% 100% Destroy [dead] thread
   12.00   12.00   12.00    0.00  100% 100% Destroy [runnable] thread
   16.00   15.00   17.00    1.00  100%  50% Resume [high priority] thread
    5.27    5.00    7.00    0.39   74%  74% Thread switch

    0.81    0.00    1.00    0.31   81%  18% Scheduler lock
    2.13    2.00    3.00    0.22   87%  87% Scheduler unlock [0 threads]
    2.13    2.00    3.00    0.22   87%  87% Scheduler unlock [1 suspended]
    2.13    2.00    3.00    0.22   87%  87% Scheduler unlock [many suspended]
    2.13    2.00    3.00    0.22   87%  87% Scheduler unlock [many low prio]

    1.16    1.00    2.00    0.26   84%  84% Init mutex
    3.56    3.00    4.00    0.49   56%  43% Lock [unlocked] mutex
    3.75    3.00    4.00    0.38   75%  25% Unlock [locked] mutex
    2.84    2.00    3.00    0.26   84%  15% Trylock [unlocked] mutex
    2.75    2.00    3.00    0.38   75%  25% Trylock [locked] mutex
    1.38    1.00    2.00    0.47   62%  62% Destroy mutex
   17.28   17.00   18.00    0.40   71%  71% Unlock/Lock mutex

    1.57    1.00    2.00    0.49   57%  42% Create mbox
    0.81    0.00    1.00    0.31   80%  19% Peek [empty] mbox
    3.52    3.00    4.00    0.50   52%  47% Put [first] mbox
    0.81    0.00    1.00    0.31   80%  19% Peek [1 msg] mbox
    3.57    3.00    4.00    0.49   57%  42% Put [second] mbox
    0.86    0.00    1.00    0.25   85%  14% Peek [2 msgs] mbox
    3.19    3.00    4.00    0.31   80%  80% Get [first] mbox
    3.48    3.00    4.00    0.50   52%  52% Get [second] mbox
    2.71    2.00    3.00    0.41   71%  28% Tryput [first] mbox
    2.76    2.00    3.00    0.36   76%  23% Peek item [non-empty] mbox
    3.00    3.00    3.00    0.00  100% 100% Tryget [non-empty] mbox
    2.57    2.00    3.00    0.49   57%  42% Peek item [empty] mbox
    2.57    2.00    3.00    0.49   57%  42% Tryget [empty] mbox
    0.95    0.00    1.00    0.09   95%   4% Waiting to get mbox
    0.95    0.00    1.00    0.09   95%   4% Waiting to put mbox
    1.57    1.00    2.00    0.49   57%  42% Delete mbox
   11.43   11.00   12.00    0.49   57%  57% Put/Get mbox

    1.09    1.00    2.00    0.17   90%  90% Init semaphore
    2.50    2.00    3.00    0.50  100%  50% Post [0] semaphore
    3.13    3.00    4.00    0.22   87%  87% Wait [1] semaphore
    2.63    2.00    3.00    0.47   62%  37% Trywait [0] semaphore
    2.50    2.00    3.00    0.50  100%  50% Trywait [1] semaphore
    1.25    1.00    2.00    0.38   75%  75% Peek semaphore
    1.25    1.00    2.00    0.38   75%  75% Destroy semaphore
    9.97    9.00   10.00    0.06   96%   3% Post/Wait semaphore

    1.66    1.00    2.00    0.45   65%  34% Create counter
    1.00    1.00    1.00    0.00  100% 100% Get counter value
    1.06    1.00    2.00    0.12   93%  93% Set counter value
    3.63    3.00    4.00    0.47   62%  37% Tick counter
    1.19    1.00    2.00    0.30   81%  81% Delete counter

    1.25    1.00    2.00    0.38   75%  75% Init flag
    3.00    3.00    3.00    0.00  100% 100% Destroy flag
    2.44    2.00    3.00    0.49   56%  56% Mask bits in flag
    2.91    2.00    3.00    0.17   90%   9% Set bits in flag [no waiters]
    4.78    4.00    5.00    0.34   78%  21% Wait for flag [AND]
    4.50    4.00    5.00    0.50  100%  50% Wait for flag [OR]
    4.81    4.00    5.00    0.31   81%  18% Wait for flag [AND/CLR]
    4.50    4.00    5.00    0.50  100%  50% Wait for flag [OR/CLR]
    0.88    0.00    1.00    0.22   87%  12% Peek on flag

    2.28    2.00    3.00    0.40   71%  71% Create alarm
    4.00    4.00    4.00    0.00  100% 100% Initialize alarm
    2.38    2.00    3.00    0.47   62%  62% Disable alarm
    4.88    4.00    5.00    0.22   87%  12% Enable alarm
    2.81    2.00    3.00    0.31   81%  18% Delete alarm
    3.91    3.00    4.00    0.17   90%   9% Tick counter [1 alarm]
   22.31   22.00   23.00    0.43   68%  68% Tick counter [many alarms]
    6.47    6.00    7.00    0.50   53%  53% Tick & fire counter [1 alarm]
  112.81  112.00  113.00    0.31   81%  18% Tick & fire counters [>> together]
   25.16   25.00   26.00    0.26   84%  84% Tick & fire counters [>> separately]
   13.00   13.00   13.00    0.00  100% 100% Alarm latency [0 threads]
   13.66   13.00   16.00    0.88   83%  67% Alarm latency [2 threads]
   13.68   13.00   16.00    0.90   82%  66% Alarm latency [many threads]
   21.02   21.00   23.00    0.03   99%  99% Alarm -> thread resume latency

    1.20    1.00    2.00    0.00            Clock/interrupt latency

    4.65    4.00    8.00    0.00            Clock DSR latency

  210    208     212  (main stack:   845)  Thread stack used (712 total)
           All done, main stack : stack used   845 size  2152
            All done : Idlethread stack used   188 size  1280

Timing complete - 37600 ms total

PASS:<Basic timing OK>

Programming the application with ecoflash

eCos comes with its own utility ecoflash that is an expect script. Your host must therefore also have expect installed in order to run ecoflash. The expect program is not distributed along with eCosPro but is available for most Linux distributions and from ActiveState for Windows. Assuming both ecoflash and expect have been correctly installed, to program an executable tm_basic into flash would involve a command such as:

$ ecoflash -b m5213evb -t 'remote peedi-0:9000' program tm_basic
Erasing 0x00000000 - 0x0000b6c7
Writing 0x00000000 - 0x00003fff (16384 bytes) from file "/tmp/tm_basic.1358785576", offset 0
Writing 0x00004000 - 0x00007fff (16384 bytes) from file "/tmp/tm_basic.1358785576", offset 16384
Writing 0x00008000 - 0x0000b6c7 (14024 bytes) from file "/tmp/tm_basic.1358785576", offset 32768

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 a Ronetix JTAG/BDM PEEDI with the hostname peedi-0 listening on TCP/IP port 9000. For repeated use ecoflash supports various environment variables:

$ export ECOFLASH_BOARD=m5213evb
$ export ECOFLASH_TARGET='remote peedi-0:9000'
$ ecoflash program tm_basic
Erasing 0x00000000 - 0x0000b6c7
Writing 0x00000000 - 0x00003fff (16384 bytes) from file "/tmp/tm_basic.1358785576", offset 0
Writing 0x00004000 - 0x00007fff (16384 bytes) from file "/tmp/tm_basic.1358785576", offset 16384
Writing 0x00008000 - 0x0000b6c7 (14024 bytes) from file "/tmp/tm_basic.1358785576", offset 32768

For the Windows CMD environment replace export with SET above. The separate ecoflash documentation in the section ecoflash Flash Programming Utility should be consulted for further details.

Debugging the application with gdb

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) shell ecoflash -b m5213evb -t 'remote peedi-0:9000' program hello
Erasing 0x00000000 - 0x00004ad7
Writing 0x00000000 - 0x00003fff (16384 bytes) from file "/tmp/hello.1358786211", offset 0
Writing 0x00004000 - 0x00004ad7 (2776 bytes) from file "/tmp/hello.1358786211", offset 16384
(gdb) set remote memory-write-packet-size 128
(gdb) set remote memory-read-packet-size 128
(gdb) target remote peedi-0:9000
Remote debugging using peedi-0: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

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 PEEDI. This may or may not be necessary, but problems in this area have been observed with some versions of the tools. The shell command invokes ecoflash to program the hello program into flash. The target command connects gdb to a Ronetix PEEDI 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 peedi-0:9000
Remote debugging using peedi-0: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

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

The same commands are used to connect to the PEEDI 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 I²C 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.