INTRODUCTION:

Getting Started With Metrowerks CodeWarrior Tutorial:

The aim of this tutorial is to help the first time user of Metrowerks CodeWarrior to be
able to create a project. In addition a clear explanation of every option that is used in the
process is provided. Also, a final tree structure of the contents of the project folder is
provided.

CodeWarrior IDE contains of all tools mentioned below:

• Project Manager: Handles top-level file items by major group, such as files and
targets; tracks state information (such as file modification dates); determines build
order and inclusion of specific files in each build; coordinates with plug-ins to
provide services like version-control.
• Text Editor: Enables the creation and manipulation of source code and other
textual files.
• Search Engine: Finds a specific text string replaces found text with substitute
text; allows use of regular expressions; provides file-comparison and differencing
functionality.
• Source Browser: Maintains a symbolics database for the program; examples of
symbols include names and values of variables and functions; uses the symbolics
database to assist code navigation; links every symbol to other locations in the
code related to that symbol; processes both object-oriented and procedural
languages.
• Build System: Uses the compiler to generate relocatable object code from source
code and uses the linker to generate a final executable image from object code

The CodeWarrior Integrated Development Environment (IDE) uses projects and build
targets to organize the files and settings for creating a program. A project is a file that
contains one or more build targets. Each build target in a project is a collection of files
that the IDE uses to create (build) an output file.

A build target can contain these elements:

• Source code files
• Libraries
• Settings
• Other projects

Build targets in a project can share the same files, but each build target has its own
settings.

88
LAUNCHING OF IDE:
CodeWarrior IDE can be invoked either using the command line option or through the
short cut that is placed after installation from the start menu.

Command line option:

Figure1
From the Windows task bar menu, click on the start and select Run to open command
window as shown in the Figure2.

89
Figure 2
Either type the path or use the Browse option to select the IDE.exe and then click OK.

Shortcut option:

Figure 3
Follow the path start Æ All Programs Æ Metrowerks CodeWarrior Æ CW12 V3
and then click on CodeWarrior IDE.

90
Figure 4
An IDE window pops as shown above.

Menu bar

Tool bar

Figure 5
We can observe that a toolbar is attached to the menu at the top of the IDE screen.
Toolbar contains the buttons that are shortcuts to frequently used menu items.

91
CREATING A NEW PROJECT IN C:
Step1:

Figure 6
Using the Menu bar:

Figure 7
Using the Tool bar:

92
Figure 8
A Project creation dialog box pops up

CodeWarrior project wizard presents three main options:

Empty Project Creates the very minimum of files required, essentially just
creating the project file. User has to write every thing from
scratch.

HC(S)12 New This option allows the user to choose the appropriate
Project Wizard device on which the project to be built on, and is most
commonly used wizard.

HCS12 Stationery Provides as a quick start to use one of the demo boards,
with some skeleton code. Also provides the HC12 board
support of the previous CodeWarrior and is not used for
HCS12 devices or board.

93
Figure 9
Select HC(S)12 New Project Wizard and click on the Set…

94
Figure 10
A window pops up with Create New Project… title. Choose the location, give a name in
the File name box and click on the Save

95
Step2:

Figure 11
A window pops up with title New Project Wizard – Page 1. Click on the Next >.

This option allows you to select the derivative i.e., the processor upon which you want to
build the project. In my case the I-PAC HSC12 board from EMAC inc. has
MC9S12DG256BCPV micro-controller built on it.

96
Step3:

Figure 12
A window pops up with title New Project Wizard – Page 2. Click on Next >.

This option allows you to select the language in which you want to code your program. In
this case I selected C as my language.

Note: IDE allows you to select multiple languages such as Assembly & C, Assembly &
C++.

97
Step4:

Figure 13
A window pops up with title New Project Wizard – Page 3. As per your choice you
either select Yes or No to select Processor Expert. Click on Next >.

Processor Expert suggests, connects and generates driver for the embedded system
hardware, peripherals or algorithms. This allows the user to concentrate on the creative
part of the whole design process.

98
Step5:

Figure 14
A window pops up with title New Project Wizard – Page 4. As per your choice you
either select Yes or No to select PC-lint. Click on Next >.

PC-lint is a software tool from Gimpel Software inc. It is used to thoroughly check your
C/C++ source code for bugs, glitches, inconsistencies, non-portable constructs, and much
more. If you possess this software tool then you need to use this option.

99
Step6:

Figure 15
A window pops up with title New Project Wizard – Page 5. As this processor doesn’t
support Floating point format select No. Click on Next >.

100
Step7:

Figure 16
A window pops up with title New Project Wizard – Page 6. As per your need of usage
of memory select one out of three models Small, Banked and Large. Click on Next >.

Metrowerks CodeWarrior Compiler supports three different memory models.

(i) SMALL memory model corresponds to flat memory map of 64K byte of code
addressing. By default, all functions are of type ‘near’ in this model.
(ii) BANKED memory model supports paged addressing of code. By default, all
user defined functions are of type ‘far’ in this model.
(iii) LARGE memory model supports both paged addressing of code and data. All
functions and data pointers are of type ‘far’ in this model. Due to the increase
in overhead of necessary runtime routines, this memory model is not widely
used.
Note: near and far are two non-ANSI keywords introduced by CodeWarrior compiler to
efficiently handle the paged memory.

101
Step8:

Figure 17
A window pops up with title New Project Wizard – Page 7. Depending upon the
interface that is available, select the corresponding option and then click Finish.

This window allows the user to select the type of connection/target upon which the
project to be build. The IDE even allows the user to create project for multiple
connections/targets at a time.

Figure 18
Above window pops up showing that the project creation is in process.

102
Once the project is created all the items are organized using three different pages Files,
Link Order and Targets. All the three pages are shown following the general complete
view of IDE after the creation of project.

Figure 19
Project creation is now complete!

103
Figure 20
Link Order page shows the order of the files in the project in which they are linked.

104
Figure 21
Targets page shows the build targets in the present project.

105
Figure 22
Files page shows all the individual files in the project in a tree form. Mainly it shows text
files, source files and library files.

106
General overview of files that are created in the project:
• readme.txt
- Initially contains a brief overview of the project structure, details of on-line
help and how to contact Metrowerks.
• Sources
- Contains the users source code, sample main.c provided by wizard with project
creation.
• Startup Code
- Start12.c – C/C++ startup code which initializes the C library and invokes the
user code (main function).
• Prm
- burner.bbl – details of how to generate the required S-Record for the debugger.
- *.prm – details of how to link code/data segments.
- *.map – generated by linker.
• Libs
- Required library files (ANSI library)
- Device header and device file
• Debugger Project File
- Contains an *.ini file for the debugger – essentially a project file for the
debugger.
• Debugger Cmd Files
- Contains sub-folders for each target connection method, along with command
files.

The new project wizard creates enough code to actually load into a board and run/debug.
The main program (main.c) being:

#include <hidef.h> /* common defines and macros */

#include <mc9s12dg256.h> /* derivative information */

#pragma LINK_INFO DERIVATIVE "mc9s12dg256b"

void main (void) {

/* put your own code here */
EnableInterrupts;
for (;;) {} /* wait forever */
}

Note: All the application code must be written in this main() function. The main function
shown above is the default function with minimal code created by IDE.

107
The parameter linker file being:
NAMES END

SEGMENTS
RAM = READ_WRITE 0x1000 TO 0x3FFF;
/* unbanked FLASH ROM */
ROM_4000 = READ_ONLY 0x4000 TO 0x7FFF;
ROM_C000 = READ_ONLY 0xC000 TO 0xFEFF;
/* banked FLASH ROM */
PAGE_30 = READ_ONLY 0x308000 TO 0x30BFFF;
PAGE_31 = READ_ONLY 0x318000 TO 0x31BFFF;
PAGE_32 = READ_ONLY 0x328000 TO 0x32BFFF;
PAGE_33 = READ_ONLY 0x338000 TO 0x33BFFF;
PAGE_34 = READ_ONLY 0x348000 TO 0x34BFFF;
PAGE_35 = READ_ONLY 0x358000 TO 0x35BFFF;
PAGE_36 = READ_ONLY 0x368000 TO 0x36BFFF;
PAGE_37 = READ_ONLY 0x378000 TO 0x37BFFF;
PAGE_38 = READ_ONLY 0x388000 TO 0x38BFFF;
PAGE_39 = READ_ONLY 0x398000 TO 0x39BFFF;
PAGE_3A = READ_ONLY 0x3A8000 TO 0x3ABFFF;
PAGE_3B = READ_ONLY 0x3B8000 TO 0x3BBFFF;
PAGE_3C = READ_ONLY 0x3C8000 TO 0x3CBFFF;
PAGE_3D = READ_ONLY 0x3D8000 TO 0x3DBFFF;
/* PAGE_3E = READ_ONLY 0x3E8000 TO 0x3EBFFF; not used: equivalent to ROM_4000 */
/* PAGE_3F = READ_ONLY 0x3F8000 TO 0x3FBFFF; not used: equivalent to ROM_C000 */
END

PLACEMENT
_PRESTART, STARTUP,
ROM_VAR, STRINGS,
VIRTUAL_TABLE_SEGMENT,
DEFAULT_ROM, NON_BANKED, COPY INTO ROM_C000, ROM_4000;

OTHER_ROM INTO PAGE_30, PAGE_31, PAGE_32, PAGE_33,

PAGE_34, PAGE_35,PAGE_36,PAGE_37,
PAGE_38,PAGE_39,PAGE_3A,PAGE_3B,
PAGE_3C,PAGE_3D;
DEFAULT_RAM INTO RAM;
END

STACKSIZE 0x100

VECTOR 0 _Startup /* reset vector: this is the default entry point for a C/C++ application. */
//VECTOR 0 Entry /* reset vector: this is the default entry point for a Assembly application. */
//INIT Entry /* for assembly applications: that this is as well the initialisation entry point */

Note: The above file shows the memory segmentation, the placements of routines in
memory segments and the placement of interrupt routines in the vector table.

Few examples are mentioned below that illustrates programming in C, Assembly and
both C & Assembly.

108
PROGRAMMING IN C:
This is a small program in which sum of two variables is stored in third variable. Also
this is the first program that is compiled to generate executable file and downloaded on to
the board and run. The output is observed on PC by looking at the memory location of the
result through debugger.

main.c (Source file):

#include <hidef.h> /* common defines and macros */
#include <mc9s12dg256.h> /* derivative information */

#pragma LINK_INFO DERIVATIVE "mc9s12dg256b"

void main (void)

{
/* put your own code here */
unsigned int x = 3, y = 4, z;

EnableInterrupts;

z = x + y;

for (;;) {} /* wait forever */

}

Notes:
hidef.h is the header file in which macros and few definitions related to processor are
done. For example the EnableInterrupts function used in the main function is defined in
this file.
mc9s12dg256.h is the header file in which device (register) definitions are done.

109
Once writing the source file is done, start debugging by clicking on the debug icon as
shown below

Figure 23

Or by pressing F5 from the key board

110
Or Select Project from the menu bar of IDE and then select Debug from the drop-down
box to start debugging the project:

Figure 24

111
The following True-Time Simulator and Real-Time Debugger window pops-up:

Source Procedure Data1 Assembly

Data2 Register Memory Command

Figure 25

112
OUTPUT IN THE CASE OF SIMULATOR AS BUILD TARGET:
The following data window in the simulator shows the values of variables before and
after the simulation.

Figure 26
Before Simulation

Figure 27
After simulation

113
OUTPUT IN CASE OF P&E ICD AS THE BUILD TARGET:

The following True-Time Simulator and Real-Time Debugger window with a another
small window saying mass erase of flash memory message pops-up as and when debug
option is opted in either way shown on pages 23 and 24:

Figure 28

Click Ok

114
In the following figure, the memory locations of the variables used in the program are
highlighted in the Memory window. The locations show the values before running the
program.

Figure 29

115
In the following window the locations of the variables are changed and this indicated by
change in the color from black to red. Also we can watch the output to be the same as the
output observed in the case of Simulator. Also we can observe that data is stored inside in
the ASCII format.

Figure 30

116
PROGRAMMING IN ASSEMBLY:
There are two kinds of projects that can be created in assembly language.
(i) Relocatable Assembly: In this case the code is placed in the memory
according at the time of linking. Code Sections are placed in the Default Rom
and Data Sections are placed in the Default Ram.
(ii) Absolute Assembly: In this case the starting address at which the code is
placed is determined at assembly time.

In the above process of project creation Step3 to Step7 are replaced by following two
steps.

CREATING A PROJECT IN ASSEMBLY - RELOCATABLE:

Step3:

Figure 31

A window pops up with title New Project Wizard – Page 2. Click on Next >.

This option allows you to select the language in which you want to code your program. In
this case I selected ASSEMBLY as my language.

117
Step4:

Figure 32

A window pops up with title New Project Wizard – Page 3 that allows selecting type of
Assembly option:

Select Relocatable Assembly and then click Next.

Rest of the steps is the same as described above.

118
The main program (main.asm) with minimal code that is created is:

; export symbols
XDEF Entry, main
; we use export 'Entry' as symbol. This allows us to
; reference 'Entry' either in the linker .prm file
; or from C/C++ later on

; variable/data section
MY_EXTENDED_RAM: SECTION
; Insert here your data definition. For demonstration, temp_byte is used.
temp_byte ds.b 1

; code section
MyCode: SECTION
main:
Entry:
CLI ; enable interrupts
loop:
MOVB #1,temp_byte ; just some demonstration code
NOP ; Insert here your own code

BRA loop ; endless loop

Note: All the application code must be written in this function. The main function shown
above is the default function with minimal code created by IDE.

119
The parameter linker file being:
NAMES END

SEGMENTS
RAM = READ_WRITE 0x1000 TO 0x3FFF;
/* unbanked FLASH ROM */
ROM_4000 = READ_ONLY 0x4000 TO 0x7FFF;
ROM_C000 = READ_ONLY 0xC000 TO 0xFEFF;
/* banked FLASH ROM */
PAGE_30 = READ_ONLY 0x308000 TO 0x30BFFF;
PAGE_31 = READ_ONLY 0x318000 TO 0x31BFFF;
PAGE_32 = READ_ONLY 0x328000 TO 0x32BFFF;
PAGE_33 = READ_ONLY 0x338000 TO 0x33BFFF;
PAGE_34 = READ_ONLY 0x348000 TO 0x34BFFF;
PAGE_35 = READ_ONLY 0x358000 TO 0x35BFFF;
PAGE_36 = READ_ONLY 0x368000 TO 0x36BFFF;
PAGE_37 = READ_ONLY 0x378000 TO 0x37BFFF;
PAGE_38 = READ_ONLY 0x388000 TO 0x38BFFF;
PAGE_39 = READ_ONLY 0x398000 TO 0x39BFFF;
PAGE_3A = READ_ONLY 0x3A8000 TO 0x3ABFFF;
PAGE_3B = READ_ONLY 0x3B8000 TO 0x3BBFFF;
PAGE_3C = READ_ONLY 0x3C8000 TO 0x3CBFFF;
PAGE_3D = READ_ONLY 0x3D8000 TO 0x3DBFFF;
/* PAGE_3E = READ_ONLY 0x3E8000 TO 0x3EBFFF; not used: equivalent to ROM_4000 */
/* PAGE_3F = READ_ONLY 0x3F8000 TO 0x3FBFFF; not used: equivalent to ROM_C000 */
END

PLACEMENT
_PRESTART, STARTUP,
ROM_VAR, STRINGS,
VIRTUAL_TABLE_SEGMENT,
DEFAULT_ROM, NON_BANKED, COPY INTO ROM_C000, ROM_4000;

OTHER_ROM INTO PAGE_30, PAGE_31, PAGE_32, PAGE_33,

PAGE_34, PAGE_35,PAGE_36,PAGE_37,
PAGE_38,PAGE_39,PAGE_3A,PAGE_3B,
PAGE_3C,PAGE_3D;
DEFAULT_RAM INTO RAM;
END

STACKSIZE 0x100

//VECTOR 0 _Startup /* reset vector: this is the default entry point for a C/C++ application. */
VECTOR 0 Entry /* reset vector: this is the default entry point for a Assembly application. */
INIT Entry /* for assembly applications: that this is as well the initialisation entry point */

Note: The above file shows the memory segmentation, the placements of routines in
memory segments and the placement of interrupt routines in the vector table.

120
A small program in which two constant values are summed up and stored in a variable is
illustrated below:

main.asm (Source file):

; export symbols
XDEF Entry, main
; we use export 'Entry' as symbol. This allows us to
; reference 'Entry' either in the linker .prm file
; or from C/C++ later on

; variable/data section
Var: SECTION
; Insert here your data definition. For demonstration, temp_byte is used.
temp_byte ds.b 1

; constant section
Const: SECTION
c1: dc.b $81
c2: dc.b $7e

; code section
Code: SECTION
main:
Entry:
CLI ; enable interrupts

ldaa c1
adda c2
staa temp_byte
bra main
end

121
The following data window in the simulator shows the values of constants and variables
before and after the simulation.

Figure 33
Before simulation

Figure 34
After simulation

122
CREATING A PROJECT IN ASSEMBLY - ABSOLUTE:

Only step that differs from above process is the step 4. This is shown below.

Step4:

Figure 35
A popup window will appear with title New Project Wizard – Page 3 that allows
selecting type of Assembly option:

Select Absolute Assembly and then click Next.

123