Quadros Systems, Inc.

M523xBCC/M5282LITE Application Development Guide

This document is an extended version of the printed M523xBCC/M5282LITE Quick Start Guide included in the kit. Please use the procedure that follows in order to set up the kit’s hardware components, install the kit’s software, and run a demonstration application on the target board. Additional topics covered in this document include BDM interface usage and information on compiling and debugging programs.

The software has been configured to be compatible with both the MCF523x based M532xBCC hardware and the MCF5282 based M5282LITE hardware. While there are differences in the two types of hardware, the use of the kit's software is the same or similar for both cases. The main detail to be aware of is that the RTXC Quadros LITE example application source code for the M523xBCC is located in Quadros\Examples\Quadros_ss\Mcf523x while the M5282LITE source code is located in Quadros\Examples\Quadros_ss\Mcf5282. To avoid making the documentation overly convoluted, the documentation will assume that the M5282LITE hardware is being used, but the same steps can be followed for the M523xBCC hardware.

Executable code (.elf and .s19 files) built for the MCF523x will not run correctly on the MCF5282 and vice versa. Please make sure to use the appropriate directory tree for your target hardware.

1. Definitions

1.1. CDPATH: The file system path to the root directory of the CD-ROM. For example "D:\".

1.2. QUADPATH: The file system path to the RTXC Quadros LITE Edition installation directory. For example "C:\Quadros".

1.3. CYGPATH: The file system path to the GNU ColdFire Tools installation directory. For example, "C:\Cygwin".

2. Hardware Setup

2.1. Connect the target board to the development workstation using the DB9 serial cable.

2.2. Connect the power supply to the target and then apply power to the power supply.

2.3. Verify that the "+2.5V" and "+3.3V" LEDs next to the board’s power connector are lit.

3. Software Installation

Insert the CD-ROM into the development workstation’s CD-ROM drive. The ReadMe.html file should automatically display after a few moments. If the file is not displayed automatically, please open CDPATH\ReadMe.html.

3.1. RTXC Quadros LITE Edition

3.1.1. Click on the "RTXC Quadros" link in the left hand menu.

3.1.2. Press the "Open" button on the File Download prompt that appears. This opens the RTXC Quadros LITE Edition self-extracting archive.

3.1.3. Unarchive the RTXC Quadros LITE Edition to a convenient location, such as "C:\Quadros".

3.2. GNU ColdFire Tools

3.2.1. For Windows NT, Windows 2000, and Windows XP installations, you must be logged in with administrative privileges in order to install this software. This is necessary in order to install the driver used by the BDM interface.

3.2.2. Click on the "GNU Tools" link in the left hand menu.

3.2.3. Press the "Open" button on the File Download prompt that appears. This will execute the GNU ColdFire tools installation program. The file is large, so it may take a few moments for it to run.

3.2.4. Follow the instructions as prompted by the installation program. Avoid choosing an installation path for the GNU ColdFire tools that includes spaces, such as "C:\Program Files\Cygwin". The use of an installation path such as "C:\Cygwin" is preferred to insure that the software operates as expected.

4. Using the M523xBCC/M5282LITE Target

4.1. Configure A Terminal Program

4.1.1. Run a terminal program such as HyperTerminal. HyperTerminal is part of the Windows operating system, but may not be installed by default.

4.1.2. At the Connection Description prompt, enter "LITE_Target" for the Name.

4.1.3. At the Connect To prompt, select the serial port (COM1, COM2, etc.) that the target board was connected to in the Hardware Setup.

4.1.4. Set the Port Settings to 19200 Bits per second, 8 Data bits, No Parity, 1 Stop bit, No Flow Control.

4.2. Reset The Target Board

4.2.1. Press the button marked "RESET" on the target board. Your terminal program should now display a prompt similar to the one below:

External Reset

 

ColdFire MCF5282 on the M5282Lite

Firmware v3b.1a.1a (Built on Mar 2 2004 11:46:04)

Copyright 1995-2003 Motorola, Inc. All Rights Reserved.

 

Enter 'help' for help.

 

dBUG>

4.2.2. If your terminal program does not display the prompt, check the target board’s power connection, the serial port connections, and terminal program settings.

4.3. Download A Demonstration Program

4.3.1. In the HyperTerminal terminal window, enter the "dl" command at the dBUG prompt. This command will allow a program to be downloaded to the target board’s RAM using the S-record file format. You will be notified to "Escape to local host and send S-records now...".

4.3.2. Using HyperTerminal, choose "Send Text File" from the Transfer menu.

4.3.3. Choose QUADPATH\Examples\Quadros_ss\Mcf5282\M5282LITE\Projects\gnu\bin\quadros_ss.s19 for the filename and press Open. If browsing for the file, it will be necessary to set the "Files of type" selection to "*.*" in order to see the quadros_ss.s19 file. For the M523xBCC hardware, make sure to choose the QUADPATH\Examples\Quadros_ss\Mcf523x\M523xBCC\Projects\gnu\bin\quadros_ss.s19 file instead.

4.3.4. A rotating line in the bottom left corner of the terminal window will indicate the download progress.

4.3.5. After a minute or two, the message "S-record download successful!" should appear.

4.3.6. Enter the command "go 20000" at the prompt to start execution from address 0x20000. The terminal window should now display the following messages:

dBUG> go 20000

 

Hello World!

M523xBCC/M5282LITE example application

using RTXC Quadros Single Stack kernel

Thread: THREAD1 State: 1

Thread: THREAD1 State: 2

Thread: THREAD1 State: 3

Thread: THREAD1 State: 1

4.3.7. The downloaded program will continue to run until the target board is powered off or is reset.

5. BDM Interface Setup

5.1. Disconnect the power from the target board and shut down (power off) the development workstation.

5.2. Connect the P&E BDM Interface to the target board.

5.3. Connect the other end of the parallel port cable to the host computer. Four parallel port configurations are supported by the BDM driver software. The GNU ColdFire tools that use the BDM interface require a parameter of the form "/dev/bdmcfN" where "N" is 0, 1, 2, or 3. The configurations correspond to the following settings:

/dev/bdmcf0 --> I/O port: 0x378 --> LPT1

/dev/bdmcf1 --> I/O port: 0x278 --> LPT2

/dev/bdmcf2 --> I/O port: 0x3BC --> LPT3

/dev/bdmcf3 --> I/O port: 0x2BC --> LPT4

Typically, computer systems are configured to use parallel port LPT1 with base I/O port address of 0x0378. The documentation will assume that "/dev/bdmcf0" is the appropriate setting for your development workstation. If you experience difficulty using the BDM interface, please check the parallel port base I/O address on your development workstation and use the appropriate "/dev/bdmcfN" parameter as indicated.

5.4. The BDM interface may be tested at this time using the "bdmreset" command. From a Windows/MS-DOS command prompt, enter the command "bdmreset /dev/bdmcf0". This will reset the target board via the BDM interface. The terminal program should show output indicating that an External Reset has occurred.

5.5. If the "bdmreset /dev/bdmcfN" command does not work for any value of "N" and you have verified that your development workstation's parallel port base I/O address is one of the ones listed above, you may be experiencing a conflict with another parallel port driver. You may encounter this problem if, for example, the Metrowerks CodeWarrior for ColdFire development environment has been installed on your development workstation. With Metrowerks CodeWarrior, the conflict can often be resolved by starting CodeWarrior, using the debugger to connect to the target hardware, and then exiting the CodeWarrior application. After using CodeWarrior to connect to the target hardware, you should be succesful in connecting to the target hardware using the GNU ColdFire tools such as via the "bdmreset /dev/bdmcfN" command.

6. Building Example Applications

·         The example applications use RTXC Quadros LITE Edition as their foundation. RTXC Quadros LITE Edition is a feature-limited, binary-only version of the RTXC Quadros Single Stack Real-Time Operating System. Full-featured RTXC Quadros products that include full operating system source code are available for purchase from Quadros Systems, Inc.

·         The example applications are installed as part of the RTXC Quadros LITE Edition software installation procedure described earlier in this document. The relevant files are located in the subdirectories located in QUADPATH. The QUADPATH directory structure is configured to minimize the effort required for transitioning to the full RTXC Quadros RTOS products, other target hardware, and other tool chains.

·         The example applications are built using the GNU ColdFire Tools installed in CYGPATH. These tools are command line applications that may be executed from a Windows/MS-DOS command prompt, from a Cygwin shell prompt, or via editors and IDEs that support integration with external tools. This document will assume that commands are entered from a Windows/MS-DOS command prompt.

6.1. From the command prompt, change to the QUADPATH\Examples\Quadros_ss\Mcf5282\M5282LITE\Projects\gnu directory. This path will serve as the working directory from which the example applications are built and debugged.

6.2. To build the example applications, enter the "make" command. This will build the example application M5282LITE\C_Source\example.c and output the files M5282LITE\Projects\gnu\bin\quadros_ss.elf and M5282LITE\Projects\gnu\bin\quadros_ss.elf.

6.3. To delete example application object files created by the build process, enter "make clean".

6.4. Multiple example applications are included in the M5282LITE\C_Source directory. To build the other examples, overwrite example.c with the desired example application and then enter the "make" command. For example, copy "example2.c" to "example.c". Because the "make" program uses time/date-stamps in deciding which files to recompile, it may be necessary to enter "make clean" and then "make" after copying an example source file in this way. The default example.c file is identical to example1.c.

6.5. When developing your own RTXC Quadros applications, it can be convenient to use one of the example applications as a starting point to build on. For example, a good way to start would be to copy "QUADPATH\Examples\Quadros_ss" to "QUADPATH\Examples\MyApp" and then edit the files in the "QUADPATH\Examples\MyApp" directory as appropriate for your application.

7. Getting started with GDB, the GNU debugger

7.1. Debugging with gdb requires the use of the BDM interface. Please make sure that the BDM hardware has been set up using the procedure described earlier in this document.

7.2. To start debugging an example application, enter the command:

m68k-bdm-elf-gdb --command=5282.gdb bin/quadros_ss.elf

The 5282.gdb file is a text file read by gdb to initialize the target processor. Refer to the comments in the 5282.gdb file for more information. Modify this file to suit your own needs. For example, if your development workstation uses a parallel port I/O address other than 0x378 (refer to section 5.3), you will need to modify the line "target bdm /dev/bdmcf0" to be appropriate for your computer system.

7.3. You should now be at a gdb command prompt.

7.4. To reset the target board from within gdb, enter the commands:

bdm_release

or

bdm_reset

continue

bdm_release Resets the target and exits BDM mode.

bdm_reset Resets the target and enters BDM mode.

continue Allows the processor to run from its reset state.

7.5. To load the example application to the target board and run it, enter the command "run".

7.6. Answer "y" to the download prompt.

7.7. The example application should now be running. If you are working with the default example, the text shown below should be output to the serial port:

 

Hello World!

M5282LITE example application

using RTXC Quadros Single Stack kernel

Thread: THREAD1 State: 1

Thread: THREAD1 State: 2

Thread: THREAD1 State: 3

Thread: THREAD1 State: 1

7.8. As configured by the 5282.gdb script, gdb is set up to return to a gdb prompt immediately after executing a command. In order to use breakpoints, etc. we need to switch to another mode. The relevent commands are:

bdm_wait Cause GDB to wait for the target to stop when running.

bdm_no_wait Cause GDB to not wait for the target to stop when running.

bdm_stop Stop the target if running.

Enter the bdm_wait command now. You may need to issue the bdm_stop command before bdm_wait if the target is currently running.

7.9. There are many ways to set breakpoints. One way is to provide a function name. For example, enter the command:

break main

This will set a breakpoint at helloc's main() function.

7.10. To restart the example application and demonstrate the breakpoint feature, enter the command:

jump *0x20000

jump Continue program being debugged at specified line or address.

Here, we are telling gdb to start executing code from the address 0x20000. This is equivalent to entering "go 20000" at the dBUG prompt via the terminal program.

7.11. At this point, gdb should be outputting something like:

Breakpoint 1, main () at ../../C_Source/main.c:27
27         DISABLE;
This indicates that gdb has paused program execution at breakpoint 1 and is displaying the next line of code to be executed.  Enter one of the following commands:
next                     To "step into".
step                      To "step over".
continue             To continue execution.
If the continue command is entered, gdb will not display a prompt after the command has been entered.  This is because gdb is waiting for the example application to terminate.  However, the example application does not terminate.  It will be necessary to enter Ctrl-C in order to signal gdb to pause execution and allow other commands to be entered.

7.12. To exit gdb, enter the command "quit".

7.13. As a convenience, a second gdb initialization script called "5282run.gdb" is provided. This initialization script will execute the gdb commands necessary to download and run the executable code so that you don't have to do it manually as described above. The run_target.bat file in this directory executes gdb using 5282run.gdb after making sure that the executable has been rebuilt using the current source code.

8. General Notes Regarding GDB

8.1. Outside of gdb, help on gdb (and other GNU tools) may be obtained via the "info" command. For example, "info gdb" will display a help file for gdb.

8.2. Within gdb, help may be obtained by issuing the "help" command.

8.3. Within gdb, the "apropos" command will search for commands related to a keyword. For example, "apropos bdm" will list all of the commands related to the BDM interface.

8.4. BDM support for gdb is not yet a standard gdb feature. At the moment, the only BDM-related help information is what is available via "info", "apropos", and "help".

8.5. There are graphical front-ends for GDB such as Insight. Some BDM support may be available with these graphical front ends, but has not been tested for use with the M523xBCC/M5282LITE kit.

8.6. An excellent reference for general gdb usage is available from http://www.refcards.com/. A copy of the gdb-refcard-letter.pdf file from this site is located on the M523xBCC/M5282LITE CD in the CDPATH\Cygwin directory.

8.7. Within gdb, command name abbreviations are allowed if unambiguous. For example, instead of entering "continue", gdb will interpret "c" as the "continue" command. More examples:

step                  s
next                  n
break main     b main
backtrace        bt

8.8. Within gdb, pressing the <ENTER> key without a command executes the command issued most recently. For example, the "step" command can be executed repeatedly by entering "step" once, then pressing <ENTER> more than once. The up and down arrows allow you to scroll through a command history.

8.9. Gdb's prompt has a tab-completion feature. This feature works for commands as well as source code symbols. Examples:

b<TAB>                     displays a list of commands beginning with the letter "b".
br<TAB>                    expands to "break"
break _a<TAB>        expands to "break _atexit"