Absolute Assembly
This page describes the step-by-step procedure to produce executable programs for the Simulator and HCS12 using Code Warrior (ie, there are two targets). The demo program itself is very simple - it just adds two numbers and stores the result in memory - and is based on absolute assembly, where the memory addresses are assigned in the source code. Nevertheless, more complicated programs, including those using relocatable assembly (where the linker assigns memory addresses) can be generated in a manner similar to that noted below.
Note that the Code Warrior software we use is the HC(S)12 Special Edition, and is free. It is a complete development environment for the HCS12. If you want to download it to your home PC, you can get it free from the Freescale website. Download the HC(S) 12 Special Edition and follow the on-screen instructions to install it. When you register it, you will receive a free license by email which will allow you to run up to 12K of code. If the download link above is stale or doesn't work, go to the Metrowerks site and manually navigate to to the desired section. The downloaded version has a Simulator program (described below), so you can create and test programs without having access to an HCS12 board.
Quick Overview of The Code Warrior Development Process
Code Warrior is a graphical Integrated Development Environment (IDE) which allows you to create programs for embedded systems like the HCS12. It consists of a suite of integrated tools that perform the major tasks involved in creating and debugging an executable program. A conceptual overview of the process used to create an executable program using Code Warrior is given here.
The programs you create in Code Warrior are done in the context of a project. A project is a "superfile" which contains all the source, linker and debugger files associated with an executable program you are going to create. So, when we say we are creating a Code Warrior program, we actually end up creating a project. A project has a .mcp extension. Note that within a project, you can have several types of build targets which share the source files and all. The labs you do as part of this course will typically be stored as project files, eg, lab3.mcp.
To create the executable using Code Warrior, we first create a project called "demo". Within the project, we create two targets and define the configuration of each: one target is for the Dragon12 HCS12 board itself and one target is for the Simulator. The configuration of each target defines in detail how we will create or "make" the final executable files. Once the build targets have been defined within the project, we then create the assembly source files that contain our program code. These and a few other configuration files are then attached to the appropriate build targets. With a click of a button, we then "make" the executables, one for each target. One executable is a file called "demo_hcs12.abs.s1" that can be downloaded and run on the Dragon12 board. The other is a file called "demo_sim.abs" which can be run in the Code Warrior Simulator. The organization of the project is as shown below:
Note that since the procedure above uses absolute assembly rather than relocatable assembly, we don't need to generate a linker .prm file.
Also note that the procedure here creates a project with two targets - one target for the Code Warrior Simulator and one target for the HCS12 hardware. If you are not using the Simulator, simply omit the steps required for the Simulator target (ie, omit Part 3). It won't hurt if you do generate a Simulator target, but it will be unnecessary work.
The procedure outlined below is for creating a project step-by-step from scratch. Often a template called a "stationery" is used to automate the procedure. See the notes at the end of this document for information about creating and using stationery.
Part 1 - Create a New Project
1. Open a Code Warrior session by double clicking on the Code Warrior icon on the desktop or starting the program from the "Start" menu (it is in the "Metrowerks" group in the Start menu).
2. In the top menu, click on "File > New". You then get a pop-up window called "New". Click on the "Project" tab, choose "Empty Project" (it is highlighted if chosen), and then in the "Project Name" box enter "demo". Then, next to the location box, click on the "Set..." button and a new window called "Create New Project" will open up. Set the location by browsing to the folder where you want the project to reside, called "Demos" here. Note that the "Create Folders" box is checked, so Code Warrior will automatically create a folder called "demo" in the "Demos" directory. The screenshot of what you should have at this point is shown below. Click on the "OK" buttons so that your settings are all accepted. The project is named "demo.mcp". If the project window is docked, you can undock it by clicking on the "demo.mcp" tab and choosing either "MDI Child" or "Floating".
Part 2 - Create the Build Target for the HCS12 (demo_hcs12)
1. In the demo.mcp Project Window shown below, click on the "Targets" tab. There will be an existing target named "demo". Click on the "Settings" icon (which is highlighted in yellow in the screenshot below), or choose "Edit > demo Settings" from the topmost menu.
2. You should get the "demo Settings" pop-up window shown in the screenshot below. Click on panel named "Target Settings" so it is highlighted. In the "Target Name" box, enter "demo_hcs12" - this is the name of the build target for the Dragon12 HCS12 board. In the linker box, check "Linker for HC12". The screenshot below shows what you should have at this stage.
3. Now, choose the panel labeled "Assembler for HC12". An HC12 Assembler window will pop up - click on the "Options" button. A new window called "HC12 Assembler Option Settings" will open up. In this window, choose the "Output" tab (it is usually chosen by default). In the Output Tab window, check the "Object File Format" box. A box in the middle of the window will open up with a drop-down selection menu. Choose "ELF/DWARF 2.0 Absolute File" - this is required for making an absolute assembly program. The screenshot at this point is shown below.
4. After you select this, the window should show as below with "-FA2" in the "Command Line Arguments" box. Note that rather than graphically selecting the "ELF/DWARF 2.0 Absolute File" setting, you could alternatively enter the -FA2 option in the command line arguments box.
5. Click on the "Burner for HC12" panel. In the "Burner for HC12" window that pops up, click the "Burner" button. In the "Burner" pop-up window, click on the "Content" tab. In the Radio buttons, choose "Format = Motorola S", "Data Bus = 1 Byte", "Range to Copy: Orgin = 0, Range to Copy = 10000 (hex), Destination Offset = 0", "S-record Configuration = S1, Bytes per line = 32". Your window should look like the one below:
6. Now, click on the "Input/Output" tab and verify that Input File box reads"%ABS_FILE%". In the "Output" section, click on the "File" radio button and enter "%ABS_FILE%.s1" in the box. Check that "1st Byte MSB" is set and click OK. The window should look like below:
7. In the "Burner for HC12" window, we now select the "Options" button. In the "Burner Options Settings" window that pops-up, click on the tab labeled "Output". Select the "No S-records" box. A new menu will show at the middle of the page. Deselect the "No S9 Records" and "No S0 Records" boxes so that no check marks appear in these boxes (ie, we DO want S0 Records and S9 records). Make sure the box labelled "No Path in S0 Record" is checked (we DO NOT want the path in the S0 record). The screenshot of this stage is shown below. Note that you may need to scroll up/down for the different boxes. Click OK in the "Burner Options Settings" window for the system to accept your settings. The "Command Line Arguments" box will show "-Ns=78p" if you have set the options correctly.
> The reason for this step this is to keep Code Warrior from adding the path in the S0 record. The S0 record is essentially just a header, and when Code Warrior adds path information it sometimes makes it too long for the D-Bug12 loader. If you omitted this step, you could manually delete the long S0 header using Notepad or something. Since D-Bug12 doesn't actually use the S0 record, it would then load in fine.
> Also note that we later add a .bbl file to the project. When we "make" the target, the presence of the .bbl file tells Code Warrior to execute the Burner program using the options we entered in this step, thus creating our desired S-record.
8. Click on the "Linker for HC12" panel and in the pop-up window select the "Absolute, Single-File Assembly Project" radio button. In the box below this, enter "demo_hcs12.abs". This will be the name of our absolute file. By choosing "Absolute, Single-File Assembly Project", we are essentially telling Code Warrior to bypass the linker. The screenshot is shown here:
9. Once we have set all the options in the different panels noted above, click on the "OK" button. The Target Settings window will close and we will be back in the project window, with the target "demo_hcs12" showing.
10. We have now created a build target called "demo_hcs12". We will shortly create an assembly language source code file that we will attach to this target. We will also add a .bbl batch-burner language file to the target so that the S-record is automatically generated during "make". Assuming we have done everything right, when we "make" the project we will get a file called "demo_hcs12.abs.s1" that can be loaded into the Dragon12 board and run.
Part 3 - Create the Build Target for the Simulator (demo_sim)
To define the Build Settings for the Simulator target, we follow a procedure much like that shown above for the HCS12 target. Since many of the steps are similar, only a few screenshots are shown.
1. First, in the "demo.mcp" project window, create a new target by clicking on the "Target" tab, and then choosing "Create Target" from the Projects menu.
> This is a little tricky - if the "Create Target" selection in the Projects menu is greyed out, make sure that you have not inadvertently highlighted the text in the "Targets" tab. Text is highlighted if it has a dotted bounding box. If the text is highlighted, try clicking somewhere in the white space of the Targets window to deselect the text.
2. In the "New Target" popup window, select the "Empty Target" radio button and name the target "demo_sim". You should now have a new target in the "Targets" window as shown in the screenshot below:
> You will notice that there is a small black arrow pointing to the active target, and that the active target name is also shown in the top box of the project window. To select a target and make it active, double click on the target icon beside a target name, or choose from the dropdown list in the top box of the project window.
3. Make the "demo_sim" target active as noted just above, and then click on the "Settings" icon.
4. As we did in the above steps, in the project window with the "Targets" tab selected and the "demo_sim" target active, select the "Settings" icon. In the Target Setting pop-up window, make sure the target name is "demo_sim", and then choose "Linker for HC12". Then, in the Assembler selection, choose the "Output" tab, check the "Object File Format" box, and choose "ELF/DWARF 2.0 Absolute File" from the dropdown menu. In the "Linker" panel, set the file to absolute assembly named "demo_sim.abs".
5. Then in the "Build Extras" selection, click on the "Use External Debugger" check box. Three text boxes will then activate. In each enter the following:
Application: {Compiler}prog\hiwave.exe
Arguments: %targetFilePath -W -Prod=%projectFileDir\Simulator.ini -instance=sim
Initial Directory: {Project} The window will look as below:
> This assumes that you have the Simulator "hiwave.exe" located in the "prog/" directory of the base installation folder. If located elsewhere, click on the "Browse..." button and browse to choose the absolute location of "hiwave.exe". The default location depends on your system, but it is normally located in the home folder for the Metrowerks installation, eg, "C:\Program Files\Metrowerks\CodeWarrior CW12_V3.0\prog\hiwave.exe".<
6. You now have all of the necessary settings in place. Click the "OK" button for the Target Settings window. We now have completed setting up the build target for the Simulator.
Part 4 - Create the Assembly Source Code File "demo_hcs12.asm"
In this part, we will create a source code file and burner file that we attach to the "demo_hcs12" target.
1. In the Code Warrior IDE window, click on "File > New" then click on the "File" tab of the pop-up window. Enter "demo_hcs12.asm" in the File Name box, and then check the box "Add to project". The Project Name box should show "demo.mcp". Beneath this check the "Targets" box labelled "demo_hcs12" so that it is selected (do NOT check "demo_sim"); this step basically attaches the source code file that we are creating to the "demo_hcs12" target. Then click on the "Set..." button beside the location window. Browse to the "demo" directory we created above. The "demo_hcs12.asm" name should show in this directory as shown below - then click on the "Save" button. The screenshot below shows what you should have entered.
2. Enter or cut/paste the code shown below into the text window for "demo_hcs12.asm". Note that comments always begin with a semi-colon';'.
;****************************************************************
;*
;* UTEP EE3376 Assembly demo program "demo_hcs12.asm"
;* 18 Oct 03
;*
;* Simple absolute assembly program to demonstrate the steps to create an
;* executable program using Code Warrior software assembly tools. The
;* program simply adds two numbers and then stores the result in memory.
;*
;* This program runs on the Dragon12 HCS12 development board.
;*
;****************************************************************
; 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
;-----------------------------------------------------
; 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
; Enter your code following the "Entry" label.
Entry:
ldaa num1 ; the first number
adda num2 ; add second number to A and store in A
staa res1 ; store result in memory
swi ; end the program
;****************************************************************
3. A .bbl file must also be added to tell the burner how to make the .s1 file (our S-record output) from the .abs file that the assembler/linker creates. As above, in the Code Warrior IDE window, click on "File > New" then click on the "File" tab of the pop-up window. Enter "burner.bbl" in the File Name box, and then check the box "Add to project". The Project Name box should show "demo.mcp"; beneath this check the "Targets" box labelled "demo_hcs12" so that it is selected (do NOT check "demo_sim"). Then click on the "Set..." button beside the location window. Browse to the "demo" directory we created above. The "burner.bbl" name should show in this directory as shown below - then click on the "Save" button.
4. Enter or cut/paste the code shown below into the text window for "burner.bbl".
/* logical s-record file */
OPENFILE "%ABS_FILE%.s1"
format=motorola
busWidth=1
origin=0
len=0x1000000
destination=0
SRECORD=S1
SENDBYTE 1 "%ABS_FILE%"
CLOSE
Part 5 - Create the Assembly Source Code File "demo_sim.asm"
1. We next create a source file for the simulator which is the same as for the HCS12 except that at the end of the source code listing we add code to create an interrupt vector for reset. This allows us to easily reset the program when running in the Simulator. Note that we do not need this extra code when running on the HCS12 since D-Bug12 is running (and the reset vector location $FFFE is essentially locked, so DBug12 won't let us load any code there). Note also that we do not need a .bbl burner file for the Simulator.
2. As above, in the Code Warrior project window, click on "File > New" then click on the "File" tab. Enter "demo_sim.asm" in the File Name box, and then check the box "Add to project". The Project Name box should show "demo.mcp"; beneath this check the "Targets" box labelled "demo_sim" (do NOT check "demo_hcs12"). As before, this attaches our source file to the desired target. Then click on the "Set..." button beside the location window. Browse to the "demo" directory we created above. The "demo_sim.asm" name should show in this directory - then click on the "Save" button.
3. Enter or cut/paste the code shown below into the source window.
;****************************************************************
;*
;* UTEP EE3376 Assembly demo program "demo_sim.asm"
;* 18 Oct 03
;*
;* Simple absolute assembly program to demonstrate the steps to create an
;* executable program using Code Warrior software assembly tools. The
;* program simply adds two numbers and then stores the result in memory.
;*
;* This program runs on the HCS12 Simulator, and needs the reset vector.
;* Based on code from "demo_hcs12.asm"
;*
;****************************************************************
; 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
;-----------------------------------------------------
; 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
; Enter your code following the "Entry" label.
Entry:
ldaa num1 ; the first number
adda num2 ; add second number to A and store in A
staa res1 ; store result in memory
swi ; end the program
;------------------------------------------------------
; Interrupt Vectors - we need this to run on the Simulator correctly
ORG $FFFE
fdb Entry ; Reset
;****************************************************************
Part 6 - Run the "Make" Utility to Build the Executables
1. First, verify that the source files we just created are associated with the correct targets. To do this, in the project window click on the "Files" tab, and then activate the target "demo_hcs12" from the drop down list at the top of the window. Look to see that there is a black dot in the target column beside the file names. Both "demo_hcs12.asm" and "burner.bbl" should be associated with the target "demo_hcs12", as shown in the screenshot below:
> There will also be green check marks in the leftmost "touch" column. This means that the files have been "touched" or marked for being included in the "make" process. A file is "touched" whenever it is changed, the idea being that only files that have been changed since the last make process need to be re-assembled.
2. Click on the "make" icon (highlighted in yellow in the screenshot above) or choose "Project > Make" from the IDE menu. This actually "makes" the executable. You should now see the files "demo_hcs12.abs" and "demo_hcs12.abs.s1" in the "demo" directory - these are the outcome of the "make" process. We will later load the .s1 file into D-Bug12. The green "touch" checkmarks have disappeared, and won't show again unless a file is changed, or unless we manually change the file to be "touched".
3. Repeat the procedure for the "demo_sim" target/source combo. Verify that the "demo_sim.asm" source file is associated with the "demo_sim" target (black dot in the target column beside the file name). Also verify that the debugger is activated for this by checking that a black dot appears in the debug column (has a "green bug" icon at the top) beside the name. Then, run the "make" process as above. You will now see the files "demo_sim.abs" and "demo_sim.dbg" in the "demos" folder. We will use the .abs file when we open the Simulator, and the .dbg file is needed to show source code in the Simulator during the debug session.
> Note that if you click on the Debug icon (green arrow in the Project window) or choose "Project > Debug" from the IDE menu, "make" will run, and the Simulator will automatically start up.
Part 7 - Procedure to Create Project Stationery
After a project has been created, it can be used as Stationery, which is a type of template useful for creating other projects. Using Stationery as a template will save you the tedious work of entering all of the Build Target settings and the like.
1. To create a Stationery, first open up the project that will serve as the Stationery. Then, strip out all of the project-specific code so that you are left with the essential base code that is needed by the programs that will be based on this stationery. Make sure that all the paths are relative and not full paths. Save the project. Finally, copy the project and all the project files to the Stationery folder in the Code Warrior home folder.
2. To use Stationery when you create a new project, just click on "File > New" click on the "Project" tab, choose the desired Stationery ,and then save it using the new project name. You must enter source code and project-specific data, but most of the common Build Settings will have already been entered.
3. Zipped files of stationery useful for this course are available for the Simulator and HCS12 targets (_ee3376sim.zip) for just the HCS12 target (_ee3376.zip).
4. A step-by-step example of how to create a project from stationery when both hcs12 and Simulator targets are present is shown here .
5. A step-by-step example of how to create a project from stationery for an hcs12 only (without using the Simulator) is shown here .
Projects in Code Warrior