Pkgcfz Pro Quick Start Guide Mcf51jm128

Quick Start Guidefor the

ColdFire MCF51JM128P&E Microcomputer Systems, Inc.

Visit us on the web: www.pemicro.com© 2009 P&E Microcomputer Systems, Inc. All Rights Reserved

2

CONTENTS1 TOPICS INCLUDED IN THIS GUIDE...................................................................................................................3

2 PKGCF PRO - SOFTWARE OVERVIEW...........................................................................................................3

3 INSTALLING THE PKGCF PRO DEVELOPMENT ENVIRONMENT........................................................4

3.1 CHANGING THE DEFAULT INSTALLATION LOCATION.............................................................................................4

4 PKGCF PRO – QUICK START GUIDE ...............................................................................................................5

4.1 CONFIGURING THE TARGET BOARD.......................................................................................................................54.2 STARTING WINIDE.................................................................................................................................................54.3 CREATING A NEW PROJECT WITH A WINIDE TEMPLATE ......................................................................................64.4 FILES IN THE TEMPLATE PROJECT..........................................................................................................................94.5 WINDOWS LAYOUT FOR C-COMPILATION............................................................................................................104.6 VIEWING SOURCE FILES TO COMPILE - THE BUILD DIALOG ..............................................................................124.7 VIEWING COMPILER OPTIONS .............................................................................................................................134.8 COMPILING THE APPLICATION, INTERPRETING THE RESULT...............................................................................144.9 PROGRAMMING FLASH USING PROGCF............................................................................................................164.10 STARTING THE DEBUGGER ...................................................................................................................................194.11 STEPPING THROUGH C INSTRUCTIONS.................................................................................................................224.12 USING CODE WINDOW QUICK EXECUTION FEATURES .......................................................................................234.13 USING CODE WINDOW POPUP DEBUG EVALUATION HINTS...............................................................................244.14 USING THE VARIABLES WINDOW ........................................................................................................................25

4.14.1 Modifying a Variable's Value ..................................................................................................................274.14.2 Modifying a Variable's Properties...........................................................................................................28

4.15 EXECUTING THE COLDFIRE APPLICATION...........................................................................................................29

3

1 Topics Included In This Guide

This document is a step-by-step guide to using PKGCF PRO with a ColdFire MCF51JM128board, such as the P&E DEMOJM evaluation board. The guide covers creating a C applicationfor the ColdFire MCF51JM128, compiling the source code with the GNU compiler, programmingto Flash with the PROGCFZV1 software, and using the P&E ICDCFZV1 in-circuit debugger todebug the application in Flash and SRAM.

For detailed instructions on creating a ColdFire project with a WinIDE template, see the"Application Framework and Solutions Guide". This guide provides details on the architecture ofthe ColdFire application and describes the process of customizing the ColdFire application foryour system.

The "PKGCF PRO User's Manual" includes detailed information about using WinIDE toconfigure the GNU compiler.

2 PKGCF PRO - Software Overview

The P&E PKGCF PRO Windows development environment for ColdFire includes software toedit and compile C source code for the ColdFire V1 and V2 family of processors. For anyColdFire processor, PKGCF PRO contains software for programming Flash and RAM and fordebugging.

PKGCF PRO includes the following software:

WinIDE – Integrated Development Environment for the ColdFire architecture. This is theprimary editing environment for the software kit. It is the launch pad for other applications, suchas the P&E in-circuit debugger, P&E in-circuit Flash programmer, and the GNU C compiler.Control the settings for the GCC compiler within the WinIDE environment.

ICDCFV1 – In-Circuit Debugger for ColdFire V1 series devices.The debugger supports reading and writing memory and variables, programming code to Flash orRAM, controlling processor execution, and more. Use the debugger to step through bothassembly language and C language source code. The debugger loads the Elf/Dwarf (version 2.0)debug file format, which many compilers produce, such as the included GNU compiler.

M68K ELF GCC Compiler – Windows GNU C compiler for ColdFire targets.

Without requiring a UNIX shell, this compiler operates under the Windows operating system.WinIDE controls the operation of the compiler, providing one-touch compilation of a C project.The GNU software produces both the Elf/Dwarf 2.0 and S19 file formats. P&E’s in-circuit Flashprogrammer will program with the S19 or Elf/Dwarf 2.0 file, and P&E’s in-circuit debugger willload the Elf/Dwarf file for debugging Flash or RAM.

4

The GNU toolset includes the following components:

GCC version 2.95.3Binutils version 2.10Newlib version 1.9.0

PROGCFV1 – In-circuit Flash Programmer for ColdFire V1.

CASMCFZ – P&E command-line assembler for ColdFire.Note that the GNU compiler does not use the P&E command-line assembler. Rather, the GNUtools include and utilize the GNU Assembler.

REGCF – Register File Viewer for ColdFire.This software simplifies viewing and editing ColdFire registers and register bits on selectedtargets.

3 Installing the PKGCF PRO Development Environment

You must have administrator privilege on the Windows 95/98/ME/NT/XP computer that will hostthe software. After launching the installer, follow the instructions to install all of the software inthe default location, C:\pemicro\pkgcfz_pro or C:\pemicro\pkgcfz_pro_starter.

Take note of several subdirectories in the PKGCF PRO installation directory:

\pkgcfzP&E application software

\gnuGNU/GCC software (P&E Build)

\gnu\binGNU/GCC executables (P&E Build)

3.1 Changing the Default Installation Location

The default installation location for PKGCF PRO is C:\pemicro\pkgcfz_pro orC:\pemicro\pkgcfz_pro_starter. Using the installer software, you may install the software at anylocation.

We do not recommend that you manually change the location of PKGCF PRO after installation.Do not copy-and-past the GNU compiler to a different location. However, you may place yoursource code and WinIDE project files at any location.

5

4 PKGCF PRO – Quick Start Guide

The following sections walk you through select tasks using PKGCF PRO. For more informationregarding each of the P&E software components, see the Windows help files for WinIDE, ICD,and PROG.

4.1 Configuring the Target Board

This guide will demonstrate creating, programming, and debugging a ColdFire application thatresides in on-chip Flash and on-chip Ram. Refer to the documentation for the board forinformation regarding hardware settings.

4.2 Starting WinIDE

After installing PKGCF PRO, launch the WinIDE development environment by using theWindows Start menu. Select the WinIDE icon in the program group for the P&E ColdFire Prokit. Alternatively, double-click on the WinIDE32.exe icon in the directoryC:\pemicro\pkgcfz_pro\pkgcfz or C:\pemicro\pkgcfz_pro_starter\pkgcfz .

When the WinIDE development environment launches for the first time, it will display a filecontaining a description of the documentation included with PKGCF PRO.

6

A WinIDE project file contains the names of user files associated with a project as well as a widerange of compilation and editing settings. The WinIDE project name appears in the title bar ofthe main WinIDE window, shown above as ReadMe_pkgCFpro.ppf.

4.3 Creating a New Project with a WinIDE Template

Use a WinIDE template to create a C language project for your target system. Use the templateto create a target application and to automatically configure the GNU C compiler. After WinIDEcopies default source files to your new project folder, it will tailor the compiler settings for yourtarget system.

7

Begin by selecting the WinIDE Environment menu, New Project from Template. A list ofprocessors or evaluation boards will appear. Select the template " MCF51JM128_DEMO" tocreate a project for on-chip Flash and on-chip RAM.

A dialog will ask you to select an empty directory for the new project.

8

Type the path and name of a new folder in the edit box. Then, hit the Create New Folder button,and then hit OK. WinIDE will create the new, empty folder.

Next, type the name of your new project file.

WinIDE will ask if you want to save the initial project, ReadMe_pkgCFpro.ppf; select No or Yes.

The default project files will now be located in the new project directory, C:\new_project.WinIDE will open the new WinIDE project file, project.PPF.

9

4.4 Files in the Template Project

A P&E template includes header files and initialization code for the ColdFire processor, theP&E's linker script, and the WinIDE project file.

10

The template "MCF51JM128_DEMO" creates a project that uses the RTC module to implementa real-time clock. You will view the clock within the debugger's Variable window.

Take note of several files within the new project directory:

See "pe_vectors_MCF51JMx.c" for the vector table and interrupt service routines.

See the linker script "pe_MCF51JM128.ld" for the memory map of the application. This fileworks in conjunction with the source code to control the memory map of the ColdFireapplication. The top of the linker script contains user-defined settings, such as stack location andother memory settings.

The "pe_crt0_MCF51JM128.S" file contains P&E's startup code for this device.

The WinIDE project file (*.PPF) contains all of the WinIDE settings, including compiler settings.Do not alter this file manually in a text editor.

4.5 Windows Layout for C-compilation

After creating your new project with a template, WinIDE will open the project file. Close theinitial file, ReadMe.txt, which appears. WinIDE's window contains two areas, a left windowpaneto display open project files and a right windowpane to display the names of the files in thecurrent WinIDE project. Open the file main.c, whose file name appears on the right pane. Clickon the file name to open main.c, maximize the file, and WinIDE will appear as below:

11

The file, err.log, will contain the output messages of the GNU compiler, including warnings anderrors. If this file is not already open during compilation, WinIDE will automatically open err.log.Opening the error log before running GCC will maintain the log's state, its window size andlocation. Open the error log and arrange the windows, as pictured below:

12

4.6 Viewing Source Files to Compile - The Build Dialog

WinIDE project files appear in WinIDE's right windowpane. These files are not automaticallypassed to the GNU compiler. To view the files that will be compiled, select WinIDE'sEnvironment menu, Environment Settings, Assembler/Compiler tab, Build Dialog. Add files,remove files, or change the compilation order from within this dialog. It is not necessary to alterthe Build Dialog for this example.

13

4.7 Viewing Compiler Options

WinIDE configures the GNU compiler to build the ColdFire application. To view the compilersettings, select WinIDE's Environment menu, Environment Settings, Assembler/Compiler tab.

14

Use this screen, including the Compiler Options (General), Compiler Options (Paths), WinIDEError Options, and Build Dialog, to configure the GNU compiler. It is not necessary to changethe GNU compiler settings for this example.

4.8 Compiling the Application, Interpreting the Result

The default memory map for the template "MCF51JM128_DEMO" uses on-chip RAM and on-chip Flash memory. For this example, use the default memory map, making no changes to thelinker script, pe_MCF51JM128.ld.

To compile the ColdFire application, either press the F4 function key or click the compilation

button on the tool bar at the top of the WinIDE screen. When compiling, WinIDE willgenerate a Windows batch file to control the GNU compiler. The batch file will contain thecompiler settings from WinIDE.

The user may be prompted to confirm that the existing batch file should be overwritten.

15

Click OK. WinIDE will execute the batch file, and the batch file will execute the GNU compiler.WinIDE will read the results of the compilation and display the compiler messages in the fileerr.log.

If there are no errors during compilation, WinIDE's status bar will indicate that WinIDE detectsno errors.

To ensure that no error has occurred, always refer to the output in err.log to view all compilermessages.

16

If there is an error during compilation, WinIDE automatically opens the file containing the firsterror and attempts to highlight the line with the error using a stop sign.

WinIDE's status bar, at the bottom of the window, displays the first compiler error message.WinIDE recovers error messages from the file err.log. For more information on a specific error,refer to the compiler output in err.log. Certain errors, such as those that occur during the linkingprocess, may not have a corresponding source line. To be sure that no error has occurred duringthe build process, always refer to the log file.

4.9 Programming Flash Using PROGCF

The template "MCF51JM128_DEMO" creates a ColdFire application that will execute in the on-chip RAM and on-chip Flash memory. Use the default memory map for this example. Theapplication base address in Flash is 0x00000000, and the application uses RAM at 0x00800000.These values are specified in the linker script pe_MCF51JM128.ld.

17

After compiling the application, program the application to on-chip Flash memory. Beforelaunching the Flash programming software, connect the host PC to the MCF51JM128 board.Note that the P&E DEMOJM board does not require a separate P&E hardware debug interfacebecause the interface is embedded on the board. Connect the host PC to the board using a USBcable.

Launch the Flash programming software from within WinIDE by using the F7 hotkey or the

programming button on the tool bar. Alternatively, there is an icon for PROGCFV1 thatappears in the Windows Start menu under the program group for PKGCFZ_PRO.

Upon starting the Flash programmer, the connection assistant dialog will appear.

Use this screen to set the proper PC port connection, DEMOJM.

Select the Connect button, and PROGCFV1 will attempt to contact the target processor.PROGCFV1 will establish communications and then prompt you for a programming algorithm

18

file. If PROG does not prompt for the file, then double-click on the PROG command CM,Choose Module.

Select the file Freescale_51JM128_1x32x32k.CFP in the \pkgcfz\Algorithms folder of theinstallation directory, and then click Open.

At this point, double click the "EM Erase module" command and allow the command tocomplete.

19

Issue the "BM Blank check module" command, and wait for the command to complete. Then,issue the "SS Specify Object File" command. The software will prompt for the Elf/Dwarf 2.0 file.Select the file "main.elf" in the new project directory. Next, execute the commands "PMProgram module", and then execute "VM Verify module". If PROGCFV1 reports no errors, thenthe Flash memory on the processor has been programmed properly.

4.10 Starting the Debugger

After compiling and programming the ColdFire application to Flash, launch the debugger from

within WinIDE by using the F6 key or the “run debugger” button on the tool bar.Alternately, use the debugger icon in the Start menu program group for PKGCFZ_PRO.

Upon starting the debugger, the connection assistant dialog appears.

20

Use this screen to set the proper PC port connection, DEMOJM.

Click the Connect button, and ICDCFV1 will attempt to establish communications with theprocessor. After establishing communications, the main debugger screen will appear.

21

At this point, use the ICDCFV1 software to step through the ColdFire source code. Afterlaunching ICDCFV1 and establishing communications with the board, type RESET in thedebugger status window, resetting the processor. Next, issue the HLOADMAP command in thedebugger and select the Elf/Dwarf file "main.elf". This will load the debug information thatcorresponds to the ColdFire application, now located in Flash.

After loading the Elf/Dwarf 2.0 file, the debugger status window will display the amount of debugand object information loaded from the file.

22

By default, when the debugger loads an Elf/Dwarf 2.0 file, the debugger sets the program counter(PC) to the start address of the ColdFire application.

4.11 Stepping through C Instructions

After loading the Elf/Dwarf file, the debugger code window displays disassembly and does notshow the application source code. Before running the application's main function, the processorexecutes initialization code that may not have corresponding debug information. After loadingthe file, main.elf, the code window should show valid disassembly instructions.

To run past the initialization code, issue the debugger command, GOTIL main, in the statuswindow. Note that the labels are case sensitive and that the “main” label should be lowercase.This will set a breakpoint at the beginning of the main function in main.c and start the processorrunning. Execution should stop almost immediately, and the program counter will be pointing tovalid source code.

23

Instead of using the GOTIL command, you may step through the initialization disassembly,using the STEP command, until the application reaches the main function.

The P&E debugger features a high-level language source step command. Use this feature by

typing the HSTEP command in the status window or by clicking the high-level step button on the debugger tool bar. Each time the HSTEP command executes, the debugger will rapidlysingle step assembly instructions until it encounters the next source instruction, at which pointtarget execution will cease. When the debugger reaches the next source instruction, all visiblewindows will be updated with data from the board.

After reaching the main function, step through several C language instructions. Notice that someinstructions will take longer to step through than others because each C instruction may consistof a greater or fewer number of underlying assembly instructions.

4.12 Using Code Window Quick Execution Features

In the source code window, there will be a small red dot and a small blue arrow next to eachsource instruction that has underlying object code. If a large blue arrow appears on a source line,this indicates that the program counter (PC) points to this instruction. If a large red stop signappears on the source line, this indicates that a breakpoint exists on this line.

Set a breakpoint at an instruction by double-clicking the tiny red dot. To remove a breakpoint,double-click the large red stop sign. When you issue the HGO command or click the high-level

language GO button on the debugger tool bar, execution will begin in real-time. If thedebugger encounters a breakpoint, execution will stop on this source line. If it does notencounter a breakpoint, target execution will continue until you press a key or use the stop buttonon the debugger tool bar.

By double-clicking the small blue arrow, you will be issuing a GOTIL command to the address ofthis source line. A GOTIL command will set a single breakpoint at the desired address, and theprocessor will begin executing code in real-time from the point of the current program counter

24

(PC). When the debugger encounters the GOTIL address, execution stops. If the debugger doesnot encounter this location, execution continues until you press a key or use the stop button onthe debugger tool bar. Note that all user breakpoints are ignored when the GOTIL command isused.

You may also double-click the red and blue symbols in the disassembly window. Thedisassembly window may display an additional symbol, a small, blue "S" enclosed in a box. Thisindicates that that a source code instruction begins on this disassembly instruction.

4.13 Using Code Window Popup Debug Evaluation Hints

When debugging source code, it is convenient to view the contents of a variable while viewingyour source code. The in-circuit debugger has a feature, debug hints, which displays the value ofa variable while the mouse cursor is held over the variable name. The hint may be displayed inany of three locations, as shown below. Turn on the debug hint in the Configuration menu,Debug Hints menu item. Check all options at this menu.

25

The three locations for the debug hints are the code window title bar, the status window captionbar, and a popup hint that appears over the variable in source code. You can configure the hintsto display in any combination. Set the locations in the configuration menu of the debugger.

The information displayed in the popup hint box is similar to the information displayed in thevariables window.

The information includes the variable name, value, and type. In this case, the variable value isuninitialized.

4.14 Using the Variables Window

The variables window displays the current value of application variables. The following windowshows a display of variables from the example application.

26

Variables that are pointer types are displayed in red. Normal variables are displayed in black.Real-time variables are displayed in blue. A real-time variable is a variable that is updated whilethe processor is running.

Add the real-time variables, above, by using the RTVAR command in the status window. Enterthe following commands in the debugger status window:

rtvar GlobalMillisecondsrtvar GlobalSecondsrtvar ClockHoursrtvar ClockMinutesrtvar ClockSecondsrtvar.s ClockString[0] 8

You may also enter the variables by right clicking the variables window and choosing “Add avariable”. Delete a variable by selecting it in the variables window, right clicking, and choosing"Delete variable".

When adding a variable using the pop-up menu, the debugger displays the following screen.

27

In the variable field, type the address or name of the variable. Typically, set the type of thevariable to “Default”, which means that the variable will be displayed as it is defined in thedebugging information. When adding a variable, you may specify the numeric base of thevariable.

4.14.1 Modifying a Variable's Value

To modify the current value of a variable, double-click the variable name in the variables window.If the debugger supports modification of this type of variable, it will display the modify variabledialog. Check the “Modify value” checkbox, and type the variable’s new value. After you clickthe OK button, the debugger updates the variable value in the processor’s memory, and thedebugger refreshes the variable window to display the new value. Note that the debugger will notedit certain user-defined types, such as enumerated types.

28

4.14.2 Modifying a Variable's Properties

To modify a variable’s display properties, such as the type or numeric display base, double-clickthe variable name in the variables window. Check “Modify display properties” in the modifyvariable dialog. Change the variable type and base. Click the OK button, and the debugger willupdate the variable's display properties in the variables window.

29

4.15 Executing the ColdFire Application

Issue the HGO command in the debugger. The ColdFire application that you created from thetemplate will execute in real time. As it executes, the application will display the real time valueof a clock. The clock appears in the variables window.