Metrowerks Code Warrior - 68HC12 - Part 3

Your first impression of the Metrowerks Code Warrior tool chain is probably, "Gee, why is this all so complicated?"  The complexity is due to the nature of embedded applications.  Much of the complexity is eased by the use of stationary, though which is like a premade project template.

Our New Stationary

Building and executing the traditional hello world program in an embedded system like that based on the 68HC12 microcontroller is a more profound experience in that there is no operating system and there is no standard output stream.  In the College of Engineering (COE) at the University of Hartford we use 68HC12 development boards from Axiom Manufacturing.  The part number is CME12BC32.  To get you started, download the zip-file, and uncompress in the stationary folder.  Depending on the version of Code Warrior, this is likely to be one of two places:

• C:\Metrowerks\Stationary\HC12\
• C:\Metrowerks\Stationery\HC12\

Axiom12B32.zip stationary folder

With the file save, use a program like WinZip to uncompress the file, producing a stationary folder.  In creating a new project, the tools will find the folder here.

A New Project From Stationary

With the stationary folder in place, start Metrowerks Code Warrior.  From the Windows task bar, select the following to open the Metrowerks IDE:

Start => Programs => Metrowerks => Code Warrior IDE

File => New

New Project Window

In the next window left click to select AxiomPE_CME12-B32 and then click OK.  Congratulations, you just created a new project from stationary.  To implement this program, we will use the file main.c provided with the stationary.  Back in the project File View pane, double click to open the file main.c.  Make the necessary changes to the file so it contains the following:

/*************************************************************
 * main.c - Jonathan Hill - Dec. 26, 2003
 * A not-so traditional version of "Hello World!"
 ************************************************************/
#include <stdio.h>
#include <termio.h>
#include "includes.h"
									
void main(void)  {
  int val;
 
  TERMIO_Init();
  val = printf("Hello World! \n");

}									

The standard input/ouput library header file (stdio.h) includes prototypes and other declarations associated with the standard input/output library.  The terminal input/output library header file includes like information regarding the terminal library.  The header is needed by the call to TERMIO_Init() which initializes the serial port for use as the standard input/output device.  No value is passed to the function to set the communications Baud rate, to set the Baud rate it will be necessary to modify the corresponding file.

Despite the controversy, this main() returns void, as this program will runs without an operating system of any kind.  The printf() call returns an integer equal to the number of succcessful conversions to standard output that were performed.  If we remove the assignment to val, the compiler will warn that the returned value is not being used.  If we leave the assignment, the compiler will warn that an unused variable is being removed.  Doesn't it all seem silly.

Building the Project

In the project window change the build target to Simulation.

Build target setting

Click the build button to make the build target. 

Build button

After a few moments the message window appears, indicating success or failure of the build.  If you have any errors, go back and fix your code.  Assuming success, click to close the message window. 

Simulating the Project

If you are running an early version of Metrowerks Code Warrior, before you can simulate the project, it is necessary to enable the debugger:

Project => Enable Debugger

Next, start the debugger.  In the project manager click the debug button.  Newer versions of Metrowerks Code Warrior embellish the icon with a small insect figure.

Debug button

The simulation build target differs from the others in the stationary in that an I/O subsystem model is loaded along with a simulator.  You will next use a model that simulates the behavior of an serial communications terminal.  In the debugger window select:

Component => Open

In the pop-up window that appears, select the item titled Terminal and click OK.  Newer versions have a graphical listing rather than text listing.

Component selection

The default size of the terminal component is quite large. Using the mouse, drag the left, right, and bottom borders to reduce the size of the new window. 

Running the Simulator

The 'C' code first listed in the source pane is the program start-up code; with PC tools this code is normally hidden from you.  Click the Start button to start the simulation, the stationary has a predefined break point that stops execution at main().

Start/continue button

The debugger window has a number of tools open and in view.  There are windows that list all the variables, procedure calls, CPU register values, memory contents, and disassembled code.  Rather than closing the three lower left windows and possibly having to reopen them them later, click to minimize each window.

Window minimize button

With the windows minimized, point the mouse cursor at the lower edge of the Source window.  Next press the left mouse button and drag to stetch the pane edge downward. 

Debug source window

Click the step-over button, shown next.  This button causes the debugger to execute one 'C' text line, stopping at the next line containing executable code.  If the text line is a function call, then the entire function is executed and execution stops at the next line at this level.

Debug step-over

Click the step-over button again to execute the printf() instruction.  The familiar greeting should clearly be visible in the terminal window.  Program execution ends near the end of main().

The way the standard input/ouput library is written, the printf() function may return before trailing charaters are actually transmitted.  Continuing the program at the point returns to the startup code but may also give the UART a chance to catch-up.  If you accidentally lose control of the execution of your program, just the Halt button to stop program execution. 

Halt button

Before you exit the simulator, take a moment to look at each window and try a few things.  If you like, set a break point.  Click left to select a line in the source code, then right click.  In the pop-up window make a selection to insert a break point.  The reset button resets the program, so you can restart it. 

Getting Practical

To be able to use the standard input/output library include the stdio.h and termio.h header files, and call the TERMIO_Init() function before using any standard input/output library function.  But in all honesty the standard input/output library is not used much in embedded applications.  We use the standard input/output library here as a vehicle in our review of 'C' programming, but thats about it.  There are several points worth considering;

• Embedded applications tend to have limited memory resources.  The standard input/output is quite large, the needed functionality can be handled by a much reduced library.
   
• In all honesty, embedded applications don't make much use of standard input/ouput library functions.  A collection of library routines provides necessary communications.
   
• New programmers traditionally have used printf() statements to perform debugging.  However with background debug capability there is no need to use printf() instructions.
   
• The standard input/output library provided with the Metrowerks Code Warrior tools relies on the use of a spin-lock to synchronize with the UART.  Except for interrupts, during the time a spin-lock is active, the system is locked-up and is incapable of doing other work.

In closing, there are several topics left for discussion later: Using the other build targets, programming the Baud rate, programming the actual hardware, and selecting a serial communications program.