Sim Stationary

Code Warrior: Creating a New Project Using Stationery (HCS12 and Simulator Targets)

This article describes how to create a new project using Code Warrior Stationery that includes the target for the simulator. Stationery is a kind of project template which automates setting up new projects. The stationery has most of the build target settings already configured for the assembler, linker, burner, etc. It includes the base source code that contains the essential directives for creating an absolute assembly program. It also includes other configuration files such as the batch burner language (.bbl) file for creating the S-records, and the Simulator initialization file (Simulator.ini) we use when running the Simulator.

The Stationery we use is called "_ee3376sim" and is based on the project which is detailed in the Assembly IDE Example. It is recommended that you carefully review this web page and the Assembly Overview to see the various steps needed to create a project and an executable program.

The "_ee3376sim" stationery should already be located on your PC in the "HCS12 Stationery" folder in your Metrowerks base directory, but if it is not there, you can download a zipped version from here (_ee3376sim.zip).

Note that the stationery here assumes you have two targets: a simulator target, which will be run in the Simulator, and an hcs12 hardware target which will be used for actually downloading code onto the hcs12 chip. If you are only using the hcs12 chip, see that tutorial here. The "_ee3376" stationery used for just the hcs12 target is also available as a zip file.

Step 1 - Create the Project

1. Open Code Warrior. In the IDE menu, click on "File > New". Note that we refer to the main menu of Code Warrior simply as the IDE menu.

2. You will get a pop-up window titled "New". In this window, choose the "Project" tab, and then highlight the entry that says "HCS12 Stationery". In the Project Name box, enter "demo2".

3. Click on the "Set..." button next to the "Location" box so that we can set the project location. This will create another pop-up window called "Create New Project". Browse to the folder where you want the project to reside, which is the folder "Demos" here.

4. In the "Create New Project" window, enter "demo2" for the file name (project name), and make sure that the type is "Project Files (.mcp)". Also make sure the "Create folder" box is checked.

5. Enter "Save" to select the location. The screenshot below shows what you should have at this stage:

6. You will then be back in the "New" project window with the Project tab active and the project location set as desired. Click on "OK".

7. This will bring up a new popup window called "New Project" where you choose the project stationery. As shown in the screenshot below, expand the selections in the HCS12 Stationery section, choose the stationery called "ee3376" and then click "OK".

\

8. We have now created a new project, and you will now get a project window called "demo2.mcp". If it is docked and you want to undock it, right click on the project title tab and select "MDI Child". The image below shows the project window you should have at this point:

Step 2 - Create Source Code

Now that we have a new project set up, we must write the assembly language programs that we will use in this project. The project already has the base code in the files labeled "labx_hcs12.asm" for the hcs12 hardware target, and "labx_sim.asm" for the Simulator. These files contain the essential directives needed for setting up an absolute assembly program. We now need to add the actual assembly instructions. The program we are going to create is a simple program that adds two numbers, stores the result in memory, and lights the LEDs on port B according to the binary pattern of the sum.

1. In the "demo2" project window with the "Files" tab active, double click on the file named "labx_sim.asm". A text window will open containing the source code.

2. In the IDE window, click on "File > Save As" and choose the name "demo2_sim.asm" and save it in the "demo2" directory.

3. Now, by cutting/pasting or by typing in text, modify the source code to that below:

;****************************************************************

;*

;* UTEP EE3376

;* Program "demo2_sim"

;* Adds two numbers, stores result and displays results on LEDs

;* on port B. Designed for Code Warrior Simulator. Remove

;* interrupt vector line at end for running on the hcs12 with

;* DBug12 running.

;*

;****************************************************************

; export symbols

XDEF Entry ; export 'Entry' symbol

ABSENTRY Entry ; for absolute assembly: mark this as application entry point

PSEUDO_ROM EQU $1000 ; absolute address to place code/constant data

RAM EQU $1100 ; absolute address to place variables

portb_ddr EQU $0003 ; data direction register (ddr) for portb

portb EQU $0001 ; memory address of port B

output EQU $FF ; set port B ddr to output

;-----------------------------------------------------

; variable/data section

ORG RAM

; Insert your data definitions here.

num1: dc.b $2a ; first number = 42 decimal

num2: dc.b $18 ; second number = 24 decimal

res1: ds.b 1 ; reserve one byte for result

;------------------------------------------------------

; code section

ORG PSEUDO_ROM ;set PC to $1000

; Insert your code following the label "Entry"

Entry:

movb #output, portb_ddr ; make port B an output

ldaa num1 ; the first number

adda num2 ; add second number to A and store in A

staa res1 ; store result in memory

staa portb ; light LEDs on port B to binary pattern of res1

swi ; end the program

;------------------------------------------------------

; Interrupt Vectors - we need this to run on the Simulator correctly

ORG $FFFE

fdb Entry ; Reset

;****************************************************************

4. Once the code above is entered, click on "File > Save" in the IDE menu to save it.

5. Now we do the same thing for the source code for the hcs12 target. In the "demo2" project window with the "Files" tab active, double click on the file named "labx_hcs12.asm". A text window will open containing the source code.

6. In the IDE window, click on "File > Save As" and choose the name "demo2_hcs12.asm" and save it in the "demo2" directory.

7. Now, by cutting/pasting or by typing in text, modify the source code so that it is the same as the "demo2_sim.asm" source code above with the exception that we remove the interrupt code at the bottom (just delete all lines below the "swi" instruction).

8. Once the desired code is entered, click on "File > Save" in the IDE menu to save it.

9. We have now created the source code we need, and can move on to the next step.

Step 3 - Define Target Settings and Files

We now need make the actual executables. We already have our source code and most of the build target settings in place, but we do need to change just a couple of things before we do the actual make.

1. In the "demo2" project window, click on the tab labelled "Targets". Activate the target called "sim". If it is active, its name will show in the top text box of the project window, and there will be a black arrow pointing to the target icon for "sim".

2. Click on the "Settings" icon description right next to the target name at the top of the project window.

3. When the "sim Settings" window opens up, click on the panel labeled "Linker for HC12". When the linker page appears, at the bottom of the page you will notice that the radio button labelled "Absolute, Single-File Assembly Project" is selected. Change the name from "labx_sim.abs" to the new name "demo2_sim.abs". This is the name of our output file for the Simulator target.

4. The screenshot below shows what you should see at this point:

5. Now, we'll do the same for the hcs12 target. Activate the hcs12 target, click on the "Settings" icon, and in the Linker Panel change the name of the absolute assembly file to "demo2_hcs12.abs".

6. Now, in the "demo2" project window, click on the files tab; this view will show the files that are in the project.

7. Activate the "sim" target. Just to the left of the file named "demo2_sim.asm" we should see a green "touch" checkmark, meaning that this file is new or has been changed and will thus be assembled in the make process. If there is not a green "touch" checkmark, to activate one simply click in the leftmost column (with the green checkmark icon at the top).

8. We need to check that the files are associated with the correct targets. With the "sim" target still active, look in the rightmost columns. The "target" column has a target icon at the top of the column, and the "debug" column has a green bug icon at the top of the column. Check that there is a black dot in both the target and debug columns for the "demo2_sim.asm" file, and that there is a black dot in the target column next to the file "Simulator.ini". A black dot means that the file is associated with the target. If the black dots are not there, highlight the name "demo2_sim.asm" and click in target or debug column to create the black dot. The screenshot below shows what your window should look like:

9. Repeat the procedure for the "hcs12" target. Activate the hcs12 target, and check that the files "demo2_hcs12.asm" and "burner.bbl" are associated with the hcs12 target by looking at the black dots in the target column. Both files should also show "touch" checkmarks. The image below shows what you should have:

Step 4 - Run the "Make" Utility to Build the Executables

We are now ready to "make" the executables. This involves just a couple of clicks.

1. In the "demo2" project window, activate the "sim" target.

2. With the "sim" target active, click on the "make" icon description just to the right of the "settings" icon at the top of the project window. With a click of this button, the whole process of making the executable was initiated.

3. If there were no errors in your source code, you should now have an executable called "demo2_sim.abs" in your "demo2" project folder. This is the file that you will run in the Simulator. In the "demo2" project window, note that the "touch" checkmark has disappeared. It will re-appear if we change the file and thus need to re-assemble it.

> If there were errors, read the error messages and take corrective action accordingly. Usually there is a simple typo or something in the source code; the error message will usually give you a clue at to what this is. If after several tries you just cannot get it to work, call the TA over and see if they can help.

4. We'll now make the hcs12 executable. In the "demo2" project window, activate the "hcs12" target.

5. Click on the "make" icon. If there were no errors in your source code, you should now have an executable called "demo2_hcs12.abs.s1" in your "demo2" project folder. This is the file that you will download to the Dragon12 board using the D-Bug12 loader.

Step 5 - How to Run the Executables

We now have two executables that we can run. The file "demo2_sim.abs" can be run on the Simulator. Click this tutorial for a simplified introduction to the Simulator. Click on the D-Bug12 Program Demo to see how to load a program into the Dragon12 board and run it. See also DBug12 Demo for more information on using D-Bug12.