Stationary

Introduction

This article describes how to create a new project for the hcs12 using Code Warrior Stationery. 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. More advanced stationery can include multiple targets and might, for example, include a Simulator initialization file (Simulator.ini) if we are going to run the Simulator.

The Stationery we use is called "_ee3376" and is based on the project which is detailed in the Assembly IDE Example EXCEPT that we have omitted the Simulator target in the "_ee3376" stationery. It is recommended that you have a look this web page so that you are familiar with the details of setting up a project from scratch (just have a look at it - don't do the actual demo there). Also, make sure to review the Assembly Overview to see an outline of the various steps needed to create a project and an executable program.

The Stationery file "_ee3376" we use in the project and in the labs in general should be located in the "HCS12 Stationery" folder in your base Metrowerks directory. Download it _ee3376.zip. Unzip this file in a directory called “_ee3376” in the HCS12 Stationary directory.

Step 1 - Create the Project

*** NB: Whenever you create a Code Warrior program or project as done below, make sure to save it in your project directory on the network drive. One suggestion is to creater a "master" folder called "ee3176" in your network drive, and then save each individual project or lab within this folder. For instance, after following the steps below, you would have a folder called "demo2_hcs12" in your "ee3176" folder on your network drive. You can also save your work to USB thumb drives if you so desire.

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_hcs12". This will be the name of your project (it will show up as "demo_hcs12.mcp" when you later look in your project folder).

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. In this tutorial we had first set up a topmost master folder called "temp" which we used for our project, but you can put the project in any convenient folder that you have set up (eg, put it in your "ee3176" folder if you created one).

4. In the "Create New Project" window, check that "demo2_hcs12" is the file name, and make sure that the Save As Type is "Project Files (*.mcp)". Also make sure the "Create folder" box is checked. All of this should be automatically set for you, but if something is different than above, then manually enter it as desired. Note that we will end up with a new folder called "demo2_hcs12" which will hold all of your project files. There will be a file called "demo2_hcs12.mcp" which will be the actual project file itself.

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_hcs12.mcp". If it is docked and you want to undock it, right click on the project title tab and select "MDI Child"; this is easier to work with than the docked version. 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 file labelled "labx_hcs12.asm" for the hcs12 hardware target. This file contains 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_hcs12" 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.

2. In the IDE window, click on "File > Save As" and choose the name "demo2_hcs12.asm" and save it in the "demo2_hcs12" directory. All we have done is renamed the original file "labx_hcs12.asm" to "demo2_hcs12.asm".

3. Now, by cutting/pasting or by typing in text, modify the source code of "demo2_hcs12.asm" to that below.

> Note that the program below contains a number of statements such as "dc.b" and 'EQU" called "directives". Directives are assembler specific statements that make it easier for us to write programs. Directives are not part of regular machine language. Go to the Code Warrior Directives link for further information.

> Also note the use of WHITE SPACE . "White space" is something which puts space at the beginning of a line, and is either a space character(s) or a tab character(s) or any mix of these. The incorrect use of whitespace is one of the most common problems encountered by beginning Code Warrior programmers. Note that some directives such as the EQU label have no white space. Labels such as "Entry:" also have no white space. Others such as ORG must have white space. Machine instructions such as "mov #ledson, portb" must also have white space. A machine instruction in Code Warrior will not work if there is no whitespace before it.

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

;*

;* UTEP EE3376

;* Program "demo2_hcs12.asm"

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

;* on port B. Designed for Code Warrior (absolute assembly), and

;* runs on the hcs12 chip on the Dragon12 EVB. Updated for Rev. E boards.

;*

;* 4 Feb 2005

;*

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

; 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 $2000 ; absolute address to place variables

portb_ddr EQU $0003 ; data direction register for portb

portb EQU $0001

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:

; the following two lines for Port J are needed for Rev.E boards

; it won't hurt to leave them with the Rev C and Rev D boards

movb #$FF,$026A ; make Port J output via DDR

movb #$00, $0268 ; make Port J low to enable Port B LEDs

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

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

Step 3 - Define Target Settings and Files

We now need make the actual executable. 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_hcs12" project window, click on the tab labelled "Targets". The target called "hcs12" (the only target in this project) is active and there is a black arrow pointing to it.

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

3. When the "hcs12 Settings" window opens up, click on the panel labelled "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_hcs12.abs" to the new name "demo2_hcs12.abs". This is the name of our output file for the hcs12 target.

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

5. Note that just to the left of the file named "demo2_hcs12.asm" we should see a red "touch" checkmark, which looks like a checkmark centered on a small box. This means that this file is new or has been changed and will thus be assembled in the "make" process. If there is not a red "touch" checkmark, to activate one simply click once in the leftmost column (with the green checkmark icon at the top).

> The "touch" concept stems from the use of large files in a project which can take a long time to compile. Rather than having to re-compile or re-assemble every file each time we "make" a project, it is more efficient to only compile those that have changed. That is, we only compile or assemble those which are "touched". Sometimes, however, we may wish to force the re-compile of a file even if it hasn't changed, so we need a way to manually activate the "touch" state.

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

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

1. 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.

2. If there were no errors in your source code, you should now have an executable called "demo2_hcs12.abs.s1" in your "demo2_hcs12" project folder. This is the file that you will download to the Dragon12 board using the D-Bug12 loader. In the "demo2_hcs12" 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.

3. The screenshot below shows what you should have once you have successfully made the executable:

Step 5 - How to Run the Executable

We now have an executable that we can run on the hcs12, and we need to load it into the Dragon12. First, in DBug12, type in 'load' at the prompt and hit the enter key. Then, in the top Hyperterminal menu, choose 'Transfer -> Send Text File', browse to the project directory, and then select the file 'demo2_hcs12.abs.s1' (you have to select 'All Files (*.*)' in the 'Files of Type' selection box for the .s1 files to appear). As the program loads in, you should see one or more asterisks on the line following the 'load' prompt line. Once your program has loaded in, type in "g 1000" at the prompt, and the LEDs 1 and 6 (of 0-7) should light, corresponding to the binary pattern for $42 (%0100 0010). You can type in 'md 2000' at the prompt to read the contents of memory. Press the yellow 'abort' button on the Dragon12 to stop the program (the abort button is on the lower right of the board)..

Click on the D-Bug12 Program Demo for complete details on how to load a program into the Dragon12 board and run it (note that the Program Demo uses RAM starting at address $1100 rather than $2000, so use "md 1100" to see the memory contents in that demo). See also DBug12 Demo for more information on using D-Bug12.

Simulator Stationery

The demo HCS12 and Simulator Stationery shows how to create a project from stationery when two targets are present, the hcs12 and the Simulator. This Simulator stationery demo is not required for the lab classes, but you may find it helpful if you are going to use the CodeWarrior Simulator.