Setup

Overview

In a typical development environment the Cobra5329 board boots from flash into the RedBoot ROM monitor. eCos applications are configured for a RAM startup, and then downloaded and run via either ethernet or serial using the m68k-elf-gdb debugger. Preparing the board therefore involves programming a suitable RedBoot image into flash memory, replacing the existing dBUG monitor. Four different approaches can be used for this:

1. The board can be booted into its existing dBUG ROM monitor, which is then used to load and execute a dBUG startup build of RedBoot into RAM. The RAM-resident version of RedBoot can then be used to initialize the hardware, including uploading a ROM startup version of RedBoot and programming it into flash. If anything goes wrong during this procedure then the dBUG ROM monitor may have been wiped already, leaving the board unusable unless a hardware debug solution is available.

2. A BDM hardware debug module can be used in conjunction with a suitable debugger to load and run a RAM startup build of RedBoot. Again this can then be used to initialize the hardware, including programming a ROM startup version of RedBoot into flash.

3. The ecoflash flash programming utility can be used. Again this depends on a BDM hardware debug module and a suitable debugger. ecoflash can only be used to program a ROM startup version of RedBoot into flash, it cannot perform other tasks such as initializing the fconfig board settings. However those other tasks can be performed from inside RedBoot.

4. A third party flash programming utility may be available.

The following RedBoot configurations are supported:

The RAM startup version of RedBoot can be run either via BDM or on top of an already installed ROM RedBoot. Full eCos releases may come with prebuilt RedBoot images renamed to incorporate the startup type, for example redboot_ROM.bin.

For serial communications all versions run with 8 bits, no parity, and 1 stop bit. The dBUG version runs at 115200 baud. The ROM and RAM versions run at 38400 baud. These baud rates can be changed via the configuration option CYGNUM_HAL_M68K_MCFxxxx_DIAGNOSTICS_BAUD and rebuilding RedBoot. By default uart0 will be used for the diagnostics/debug channel.

Setting Up BDM

The recommended BDM debug solution is the Ronetix PEEDI. Other solutions such as the P&E USBMultilink device have proved unreliable on this board, so if a PEEDI is not available then it is recommended that application developers should debug their applications on top of RedBoot's gdb stubs.

The PEEDI 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 standard eCos applications, so applications can be loaded into RAM and run as normal. The configuration file will need minor edits, for example to specify the correct license keys. For full details see the Ronetix documentation. Once the PEEDI is correctly set up m68k-elf-gdb can then connect to it in the usual way:

$ m68k-elf-gdb install/tests/kernel/current/tests/tm_basic
GNU gdb 6.4.50.20060226-cvs (eCosCentric)
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=m68k-elf"...
(gdb) target remote peedi:9000
0x400008f6 in ?? ()
(gdb) load
Loading section .m68k_start, size 0x98 lma 0x40010000
Loading section .text, size 0xa918 lma 0x40010098
Loading section .rodata, size 0x114a lma 0x4001a9b0
Loading section .data, size 0x18c lma 0x4001bafc
Start address 0x40010000, load size 48262
Transfer rate: 260172 bits/sec, 3217 bytes/write.
(gdb) break cyg_test_exit
Breakpoint 1 at 0x40016172: file /home/bartv/ecos/ecospro-common/infra/current/src/tcdiag.cxx, line 310.
void cyg_test_exit(void);
(gdb) continue
Continuing.

Breakpoint 1, cyg_test_exit () at /home/bartv/ecos/ecospro-common/infra/current/src/tcdiag.cxx:310
310         if (code_checksum != cyg_crc16(_stext, _etext - _stext)) {
(gdb) quit
The program is running.  Exit anyway? (y or n) y
$
    

A P&E USBMultilink BDM device can be used in conjunction with CodeSourcery's m68k-elf-cfpe-stub server. Inside the device is a jumper which should be set to the NO CLK position. The server requires a configuration file cobra5329.cfg which can be found in the platform HAL's misc directory. It is recommended that the m68k-elf-cfpe-stub be restarted for every debug session to ensure that the board is properly reset. Power cycling the boards between debug sessions may also help to improve reliability.

$ m68k-elf-cfpe-stub -d USBMultilink -l 9000 -t <path>/cobra5329.cfg
    

It is also possible to use a P&E parallel port module or a senTec CobraConnect module with m68k-elf-cfpe-stub. The command line invocation for the later changes to:

$ m68k-elf-cfpe-stub -d ParallelPortCable -l 9000 -t <path>/cobra5329.cfg
    

For Linux hosts there is also an alternative to using m68k-elf-cfpe-stub. Cobra5329 boards come with a CD, including a toolchain build in the install/linux subdirectory. One of the tools is m68k-bdm-elf-gdb, a variant of m68k-elf-gdb which can access parallel port BDM modules directly. Unlike the PEEDI or m68k-elf-cfpe-stub, m68k-bdm-elf-gdb will not automatically initialize the hardware. Instead this can be achieved using a set of gdb macros which can be found in the bdm.gdb file in the platform HAL's misc subdirectory. A typical debug session would look like:

$ m68k-bdm-elf-gdb install/tests/kernel/current/tests/tm_basic
GNU gdb 6.3
Copyright 2004 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=m68k-bdm-elf"...
(gdb) target bdm /dev/bdmcf0
GDB target bdm connected to /dev/bdmcf0
 Coldfire debug module version is 9 (5307/5407(e))
(gdb) source /home/bartv/ecos/m68k/hal/m68k/mcf52xx/mcf532x/cobra5329/current/misc/bdm.gdb
(gdb) bdm_preload
(gdb) load
Loading section .m68k_start, size 0x98 lma 0x40010000
Loading section .text, size 0xa918 lma 0x40010098
Loading section .rodata, size 0x114a lma 0x4001a9b0
Loading section .data, size 0x18c lma 0x4001bafc
Start address 0x40010000, load size 48262
Transfer rate: 128698 bits/sec, 502 bytes/write.
(gdb) bdm_postload
Current language:  auto; currently asm
(gdb) break cyg_test_exit
Breakpoint 1 at 0x40016172: file /home/bartv/ecos/ecospro-common/infra/current/src/tcdiag.cxx, line 310.
(gdb) c
Continuing.
    

Initial Installation Using dBUG

This process assumes that the board still has its original dBUG ROM monitor and does not require any special debug hardware. Programming the RedBoot rom monitor into flash memory requires an application that can manage flash blocks. RedBoot itself has this capability. Rather than have a separate application that is used only for flash management during the initial installation, a special RAM-resident version of RedBoot is loaded into memory and run. This version can then be used to load the normal flash-resident version of RedBoot and program it into the flash.

It should be noted that some Cobra5329 boards have been shipped with a broken version of dBUG. This section describes two different ways of loading RedBoot into RAM, over a serial line or over the network.

The first step is to connect an RS232 cable between the Cobra5329 uart0 serial port and the host PC. Next start a terminal emulation application such as HyperTerminal or minicom on the host PC and set the serial communication parameters to 115200 baud, 8 data bits, no parity, 1 stop bit (8N1) and no flow control (handshaking). Apply power to the board and you should see a dBUG> prompt. Once dBUG is up and running the RAM-resident version of RedBoot can be downloaded:

dBUG> dl
Escape to local host and send S-records now...
    

The required S-records file is the dBUG startup build of redboot.srec, which is normally supplied with the eCos release in the loaders directory. If it needs to be rebuilt then instructions for this are supplied below. The file should be sent to the target as raw text using the terminal emulator:

S-record download successful!
dBUG>
    

If instead dBUG complained about the S-record addresses during the download then your board has the broken version of dBUG. Instead it will be necessary to run a tftp server on the local network and place the dBUG startup build of redboot.bin in the tftp server's directory. The details of this will depend on the tftp server being used. Once this has been accomplished, dBUG's network settings must be set appropriately using the set command. The dBUG documentation should be consulted for more information on this. Once networking is functional the RedBoot image can be downloaded:

dBUG> dn -i redboot.bin
Address:  0x40020000
Downloading Image 'redboot.bin' from 10.1.1.251
TFTP transfer completed
Read 93972 bytes (184 blocks)
dBUG>
    

When RedBoot has been loaded into RAM, either over serial or via the network, it can be run with the go command:

dBUG> go 0x40020000
+**Warning** FLASH configuration checksum error or invalid key
Use 'fconfig -i' to [re]initialize database
Ethernet eth0: MAC address 40:01:3b:e0:00:00
IP: 10.1.1.181/255.255.255.0, Gateway: 10.1.1.241
Default server: 0.0.0.0, DNS server IP: 10.1.1.240

RedBoot(tm) bootstrap and debug environment [DBUG]
Non-certified release, version UNKNOWN - built 21:15:30, Mar  5 2008

Platform: Cobra5329 (Freescale MCF5329)
Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008 eCosCentric Limited

RAM: 0x40000000-0x41000000, [0x4004204c-0x40fed000] available
FLASH: 0x00000000-0x00ffffff, 256 x 0x10000 blocks
RedBoot>
    

At this stage the RedBoot flash management initialization has not yet happended so the warning about the configuration checksum error is expected. In this example RedBoot is using a default MAC address and has contacted a local bootp server to get the address information. To perform the flash initialization use the fis init command.

RedBoot> fis init
About to initialize [format] FLASH image system - continue (y/n)? y
*** Initialize FLASH Image System
... Erase from 0x00ff0000-0x00ffffff: .
... Program from 0x40ff0000-0x41000000 to 0x00ff0000: .
RedBoot>
    

At this stage the block of flash at location 0x00FF0000 holds information about the various flash blocks, allowing other flash management operations to be performed. The next step is to set up RedBoot's non-volatile configuration values:

RedBoot> fconfig -i
Initialize non-volatile configuration - continue (y/n)? y
Run script at boot: false
Use BOOTP for network configuration: true
Default server IP address:
DNS server IP address:
GDB connection port: 9000
Force console for special debug messages: false
Network hardware address [MAC]: 0x00:0xff:0x12:0x34:0x01:0x13
Network debug at boot time: false
Update RedBoot non-volatile configuration - continue (y/n)? y
... Erase from 0x00ff0000-0x00ffffff: .
... Program from 0x40ff0000-0x41000000 to 0x00ff0000: .
RedBoot>
    

For most of these configuration variables the default value will be acceptable, at least initially. If there is no suitable BOOTP service running on the local network then BOOTP should be disabled, and instead RedBoot will prompt for a fixed IP address, netmask, and addresses for the local gateway and DNS server. The other exception is the network hardware address, also known as MAC address. All boards should be given a unique MAC address, not the one in the above example. If there are two boards on the same network trying to use the same MAC address then the resulting behaviour is undefined.

It is now possible to load the flash-resident version of RedBoot. Because of the way that flash chips work it is better to first load it into RAM and then program it into flash.

RedBoot> load -r -m ymodem -b %{freememlo}
    

The ROM startup build of redboot.bin should now be uploaded using the terminal emulator. The file is a raw binary and should be transferred using the Y-modem protocol.

Raw file loaded 0x40042400-0x4005936b, assumed entry at 0x40042400
xyzModem - CRC mode, 737(SOH)/0(STX)/0(CAN) packets, 3 retries
RedBoot>
    

Once RedBoot has been loaded into RAM it can be programmed into flash:

RedBoot> fis create RedBoot -b %{freememlo}
An image named 'RedBoot' exists - continue (y/n)? y
... Erase from 0x00000000-0x0001ffff: ..
... Program from 0x40042400-0x4005936c to 0x00000000: ..
... Erase from 0x00ff0000-0x00ffffff: .
... Program from 0x40ff0000-0x41000000 to 0x00ff0000: .
RedBoot>
    

The flash-resident version of RedBoot has now been programmed at location 0x00000000, and the flash info block at 0x00FF0000 has been updated. The initial setup is now complete. Power off the board, set the terminal emulator to run at 38400 baud (the usual baud rate for RedBoot), and power up the board again.

+... waiting for BOOTP information
Ethernet eth0: MAC address 00:ff:12:34:01:13
IP: 10.1.1.182/255.255.255.0, Gateway: 10.1.1.241
Default server: 0.0.0.0, DNS server IP: 10.1.1.240

RedBoot(tm) bootstrap and debug environment [ROM]
Non-certified release, version UNKNOWN - built 17:42:36, Mar 18 2008

Platform: Cobra5329 (Freescale MCF5329)
Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008 eCosCentric Limited

RAM: 0x40000000-0x41000000, [0x4000c030-0x40fed000] available
FLASH: 0x00000000-0x00ffffff, 256 x 0x10000 blocks
RedBoot>
    

When RedBoot issues its prompt it is also ready to accept connections from m68k-elf-gdb, allowing eCos applications to be downloaded and debugged.

Occasionally it may prove necessary to update the installed RedBoot image. This can be done using the RAM startup build of redboot.bin rather than the dBUG version of RedBoot used above. It should be loaded using the ROM RedBoot's load -r -m ymodem -b 0x40010000 and started with the go command. The ROM version can then be loaded into memory and programmed into flash as before.

Initial Installation Using BDM

Given a functional BDM setup, it is possible to run a RAM-resident version of RedBoot directly. This involves either m68k-elf-gdb or m68k-bdm-elf-gdb, together with the RAM build of redboot.elf, for example:

$ m68k-elf-gdb install/bin/redboot.elf
GNU gdb 6.4.50.20060226-cvs (eCosCentric)
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=m68k-elf"...
(gdb) target remote peedi:9000
0x00012086 in ?? ()
(gdb) load
Loading section .m68k_start, size 0x98 lma 0x40010000
Loading section .text, size 0x12a74 lma 0x40010098
Loading section .rodata, size 0x38e9 lma 0x40022b0c
Loading section .data, size 0xad4 lma 0x400263f8
Start address 0x40010000, load size 93897
Transfer rate: 280080 bits/sec, 3611 bytes/write.
(gdb) continue
Continuing.
    

RedBoot's output will be sent out of uart0 at 38400 baud, so an RS232 cable should be connected and a suitable terminal emulation application should be run. Once at the RedBoot prompt the procedure is the same as for the dBUG setup: initializing the flash, loading the ROM build of redboot.bin into memory, and then writing it to flash using fis create.

Initial Installation Using ecoflash

Given a functional BDM setup, the ecoflash utility can be used to program a RedBoot image directly into flash. Full information on ecoflash can be found elsewhere. It uses environment variables to determine the target hardware and how to access it. When using a PEEDI:

$ export ECOFLASH_BOARD=cobra5329
$ export ECOFLASH_TARGET='remote peedi:9000'
    

For m68k-elf-cfpe-stub a different remote address will need to be specified. When using m68k-bdm-elf-gdb:

$ export ECOFLASH_BOARD=cobra5329
$ export ECOFLASH_TARGET='bdm /dev/bdmcf0'
$ export ECOFLASH_GDB=m68k-bdm-elf-gdb
    

The ecoflash info can be used to verify that everything is working:

$ ecoflash info
Target board is cobra5329.
  gdb is "m68k-elf-gdb", gdb target is "remote localhost:9000".
  Target-side executable is version 1.
  Detected 1 bank of flash.
    Start 0x00000000, end 0x00ffffff -> 16384K.
      256 blocks of 64K.
  Flash block locking is not supported.
  Default program location for executables is 0x00000000.
  Target-side buffer for read and write operation is 64K.
    

If anything goes wrong then ecoflash -v info will run the same command in verbose mode, possibly providing additional information as to what is going wrong. Once everything is working a ROM startup build of RedBoot can be programmed into flash:

$ ecoflash program <path>/redboot.elf
Erasing 0x00000000 - 0x00016f6b
Writing 0x00000000 - 0x0000ffff (65536 bytes) from file "/tmp/redboot.elf.719", offset 0
Writing 0x00010000 - 0x00016f6b (28524 bytes) from file "/tmp/redboot.elf.719", offset 65536
    

When the board is next reset it should boot into RedBoot, with the output sent out of uart 0 at 38400 baud. A terminal emulator can then be used to connect to RedBoot and perform the fis init and fconfig -i initialization steps.

Rebuilding RedBoot

Should it prove necessary to rebuild a RedBoot binary, this is done most conveniently at the command line. The steps needed to rebuild the dBUG version of RedBoot are:

$ mkdir redboot_dbug
$ cd redboot_dbug
$ ecosconfig new cobra5329 redboot
$ ecosconfig import $ECOS_REPOSITORY/hal/m68k/mcf52xx/mcf532x/cobra5329/<vsn>/misc/redboot_DBUG.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make
    

At the end of the build the install/bin subdirectory should contain the required files redboot.srec and redboot.bin, as well as the ELF executable redboot.elf.

Rebuilding the RAM and ROM versions involves basically the same process. The RAM version uses the file redboot_RAM.ecm and generates a file redboot_ram.bin. The ROM version uses the file redboot_ROM.ecm and generates a file redboot_rom.bin.