ICC11 - DOS based C Cross Compiler for MC68HC11
User Manual * freeware version

Copyright (c) 1993, 1994 by ImageCraft, Richard Man, and Christina Willrich

Oct. 6, 1993

LICENSE AGREEMENT

This is the freeware release of the ImageCraft C Cross Compiler for the
Motorola MC68HC11 processors.  There is no charge for a license to use
this release of the product.  This product is protected by copyright
laws and is not in the public domain.  This license will not cover the
general release version, nor any subsequent releases.

The general release has been available since June 1994.  An information
sheet is included at the end of this manual.

WARRANTY INFORMATION

There is no warranty available on this version of the ImageCraft C Cross
Compiler.  This product and all related documentation are provided "AS
IS." ImageCraft and the authors of this product do not warrant that this
product will be bugfree, and since this is a freeware version, there
are likely to be bugs.  UNDER NO CIRCUMSTANCES, INCLUDING NEGLIGENCE,
SHALL IMAGECRAFT OR THE AUTHORS OF THIS PRODUCT BE LIABLE FOR ANY
INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES THAT RESULT FROM THE USE OF
OR INABILITY TO USE THIS PRODUCT.

If you do not agree with the above licensing agreement and warranty
information, you have no right to use this product and you must destroy
this copy of the product immediately.

Introduction

The ImageCraft C Cross Compiler for the MC68HC11 is a set of low cost
standard conformance tools for programming in C and assembly on
Motorola's 68HC11 series of microcontrollers.  It consists of the
following component programs:

icc11.exe - the driver program.
icpp.exe - the C preprocessor.
iccom11.exe - the compiler.
ias11.exe - the assembler.
crt.s - C runtime assembly file.
printf.c - simple printf-like function.

This manual does not describe how to write C or assembly programs.  Any
textbooks on ANSI standard C can be used for reference on C, and the
assembler is based on the Motorola freeware version whose syntax is
fairly well known and documentation for it can be obtained in many
places.  These programs accept file paths in either the Unix-style forward 
slash format or the DOS-style backward slash format.

If you use this product, please send us a message with your contact
address so we may send you announcements of availability of new
versions.

The best way to register and contact us are:

		e-mail: imagecft@netcom.com, or

		ImageCraft
		P.O.Box 64226, Sunnyvale, CA 94088-4226

(408) 749-0702

Please report bugs to the contact address above.  Machine configuration
and a copy of the source code will help us to track down the bug.  The
compiler can generate information such as tables of variables' stack
offsets, and line numbers as labels in the assembler output, both of
which are helpful in tracking down your programming bugs and pinpointing
compiler errors.

Since this release contains several unimplemented features, we would
also appreciate it if you inform us which ones are most important to
you, so that they can receive a high development priority.

Machine Requirements and Program limitations

This program runs in 8086 real modes under DOS, Windows VDM, OS2 VDM and
probably most DOS emulators on the popular Un*x and Mac*ntosh
machines.  A 32 bit protected mode version that runs on OS2 2.X and
DOS can be obtained from us.  The 32 bit version supports HPFS long
filenames, wildcard expansion, has access to large memory space and
executes faster than the 16 bit version, but otherwise is identical to
it.  The compiler should also run inside Integrated Development
Environments such as IDEAL and Brief.

Unlike most other DOS-based compilers that have separate front end and
back end programs, this is an integrated compiler in that the front
end and the back end are a single monolithic program.  This improves
execution speed at the expense of requiring more conventional memory.
The compiler does not use extended or expanded memory, so if you
encounter an out-of-memory problem, your recourse is either: a) freeing
up more conventional memory, b) reducing the size of the program, or c)
acquiring the 32 bit version of the compiler.

The language preprocessor is close to ANSI C conformant and the C
language accepted by the language processor is ANSI C conformant.  The
code generator does not yet support floating point code generation.
long data type is the same size as the int data type, which is 2 bytes.
In addition, the lcc compiler front end defines char data type as
equivalent to signed char, which is unfortunate for the HC11 target
since all computations smaller than int are promoted to int, and signed
char promotions to int are more expensive than unsigned char
promotions on the HC11.

There is no linker, librarian, debugger,or standard C headers and
library in this release.  Lack of a linker is not too much of a
limitation since the assembler, compiler, and compiler driver have
been written so that files of multiple types can be compiled and assembled 
together.  A limited version of printf is provided.

Some of these limitations are fixed in the general release.

The generated code should run on any version of the HC11, in both
single-chip and expanded modes.

Installation

Put all the .exe files in a directory in your path.  Crt.s should be
placed either in the same directory as your source or in the directory
pointed to by the environment variable ICC11_LIB. Header files should be
placed in the directory pointed to by the environment variable
ICC11_INCLUDE.

To verify the system is set up correctly, type "icc11 -o dhry dhry.c
printf.c" on the command line.  You should see some (harmless)
warnings from the preprocessor and an output file dhry.s19 should be
produced.

Program Operation

This is a traditional compiler system where you invoke the compiler
driver with your C and assembly source files, and if there is no error,
an output file is produced.  The output is a Motorola hex format file,
suitable to download to a monitor program such as BUFFALO.

File paths can use either forward slash or backward slash format.  In
addition to the current directory, the preprocessor searches for
header files in a directory specified by the environment variable
ICC11_INCLUDE if it exists.  The compiler driver also directs the
preprocessor to search for system header files in /lcc/include by
default.

Even though there is no separate relocatable linker in this release, the
assembler can take multiple assembly source files and thus can be used
in lieu of one.  The code generator has been written such that any
local symbol defined in a source file is distinct from generated local
symbols in other source files (basically, local names are appended with
the source file name) so that there should not be any local symbol name
conflict.

The driver automatically invokes the assembler to assemble the file
crt.s before other files that you specify.  Crt.s contains several
routines that the code generator emits for code that is too large to be
generated inline.  For example, multiply, divide and structure
assignments routines are placed in there.

Crt.s also contains the startup code.  The starting address for the code
section (usually start of free RAM, or EEPROM), the starting address for
data (usually external RAM or HC11 internal RAM) and the initial stack
address are specified in here.  You should modify these addresses to
match your environment.  This code fragment defines the starting address
of the program, and the initial value of the stack pointer, then jumps
to the C function main.

To use the printf function, you must define a function called putchar
that outputs a single character and compile printf.c (or printf.s) with
your files.  The file crt.s contains a version of putchar that uses
BUFFALO to do the output.  You must replace it with something suitable
for your system.  This implementation of printf is very primitive.
Please refer to the source code comment to see what it does support.

For systems with small amount of memory, an assembler listing should be
generated to determine whether the program fits in the memory space or
not.  The compiler does not place any limit on the number or size of the
local variables.  However, due to the architecture of the HC11, you
should consider placing large objects in static storage rather than on
the stack since an indexed addressing mode can only access within 256
bytes of the frame pointer (as mentioned, the compiler does generate
correct code to access objects with offset larger than 256 bytes off the
frame pointer).

Debugging

The debug command line switch (-g) directs the compiler to emit labels
of the form filename.line in the assembly output file where line is
the source line number.  The assembler listing file contains these
labels and their actual code offset.  Using these code offsets,
breakpoints can be set in a debugger.

In the assembly output file, after each function label, the compiler
emits a list of local variables and parameters with their
corresponding offset off the frame pointer IX, as a comment block.
Along with the debugging line labels above, it is relatively easy to
inspect the source code and the listing file for debugging purposes.

Code Quality and Optimizations

Although the compiler does not perform register allocation or other
resource-demanding global optimizations, it does perform basic block
Common Subexpression Elimination in the front end, and branch shortening
in the back end.  Function arguments are passed in preallocated areas on
the stack so no stack adjustment code is necessary after function calls.
In addition, the compiler has a built-in peephole optimizer that walks
through the generated code and eliminates redundant loads and stores,
and replaces other inefficient code fragments with something shorter
and faster.

Space or time critical code can be  either be written as C callable
assembly routines, or assembler instructions can be embedded directly in
the C source files.

Interfacing C With Assembly Routines

C global function and data names are prefixed with an '_', and arguments
are pushed right to left and converted to their "natural size." That is,
char and short are converted to int, and float is (or will be) converted
into double.  All arguments are passed on stack.  D register contains
the return value, if any.  IX and IY registers can be used freely in an
assembly routine.  Argument stack space is allocated on function entry
and thus does not need to be freed by the callee.

The assembler supports the "sect" pseudo op.  "Sect 0" is the code
section and "sect 1" is the data section.  Each section has its own
program counter.  This is especially useful for using the HC11 in single
chip mode where you may assign the code section to internal EEPROM and
the data and stack sections to the internal RAM.

The compiler supports embedded assembly in the C source code.  The
format is

asm("string");

"string" may contain variable references in the form of "%name." If name
is a variable that is defined, the generated assembly replaces %name
with the assembler references.  If name is not a visible variable, then
the literal "name" will be output.  C escape sequences such as '\n' may
be used inside the string.  Note that an embedded assembly instruction
must begin with a space or tab if it does not start with a label.
Otherwise the assembler will generate an error.  For example, the
following fragment:


int external; foo(int param) { int local;

asm(" ldd %param"); asm("label: addd %local"); asm(" std %external");
asm(" ldd %xxx");/* xxx is not a variable */
...

may generate something like:

ldd +2,x 
label:addd -2,x 
std _external 
ldd xxx

You should not use "%?" inside the asm string, the output is
meaningless.  Note that the peephole optimizer does not optimize
embedded asm code.

Command Syntax

icc11 [options] filenames

compiles the input files by invoking the appropriate processors to
handle the input file types.  The output is a Motorola hex format file,
with an extension of .s19.  Acceptable file types are: .c for C source
file, .i for C source file after preprocessing, and .s file for assembly
source file.  Options are:

-v	verbose, prints out each action before execution.  If
specified more than once, no action gets executed.

-o filenames the output file, default iccout.s19

-l	creates an assembly listing file with name <output file
name>.lst

-E	preprocesses a .c file into an .i file

-S	compiles into assembly but does not assemble.

-s	silence mode.  Will not print out each file name as the files
are processed.

The following flags are passed directly to iccom11; please refer to
their descriptions under that section.

-P
-A
-w
-g
-O

icc11 also accepts other options, their behaviors are currently
undefined.

icpp [options] input [output]

A complete description of this preprocessor and the flags can be found
in cpp.mem.  Some of the more important flags are:

-Dname[=value] define the word name to have the value.  If value
is not specified, then 1 is assumed

-Idirectory add directory to the search path for locating
include files.

By default, icc11 specifies the -I/icc11/include to icpp.

iccom11 [options] input [output]

Compiles the preprocessed C source into assembly file.  Options are:

-v	prints out compiler version string.
-O0	disables the peephole optimizer.
-P	generates function prototypes for functions encountered.
Useful for converting non-ANSI programs to ANSI C.
-A	checks for strict ANSI conformance.  If specified more than
once, emits additional warnings.
-w	do not generate warning.
-g	generates debugging line labels.



ias11 [options] filenames

Assembles the input files into a hex format output.  All modules of a
program must be specified, otherwise, an undefined symbol value error
will result.  Options are:

-l	generates a listing file.
-o	filenames the output file.  Default is iccout.s19.
-s	creates symbol table dump.
-c	includes cycle counts in listing file.
-cre	includes cross reference in listing file.

Known Bugs

_asm() only works inside a function definition.  It also ought
to work outside a function.

The debugging line number labels only use the base file name,
and thus executable code defined inside an include file will not use the
correct file name in the labels.

REXIS

A prime reason this compiler is written is so that hobbyists can
experiment with REXIS (tm) (Real time EXecutive for Intelligent
Systems).  This release does not yet fully support REXIS since it is
lacking several library functions.  Here is an excerpt from the REXIS
user manual:

REXIS (Real-time EXecutive for Intelligent Systems) is a small
multitasking preemptive executive for embedded microcontroller systems.
Based on both the designs of traditional real-time kernels and
subsumption architecture as developed at the MIT Artificial
Intelligence Laboratory for programming autonomous robots, REXIS
provides a framework for implementing control programs for intelligent
systems such as those used in robotic and distributed networks.  It
includes functions for managing tasks, messages, events, semaphores,
scheduling, and memory allocation.

REXIS is written in portable ANSI C with a small assembly module for
fast and efficient task switching.  It is currently targeted for
Motorola MC68HC11 microcontroller systems with at least 24K of RAM.
Other targets are under consideration.

Please contact us if you are interested in REXIS or in using this
compiler system with REXIS.

Acknowledgments

Most of the components in this current version are either in the public
domain, or are copyrighted materials with permission for distribution.
icc11 and the front end component of iccom11 are based on the lcc
distribution written and copyright by David Hanson.  The copyright
information on these components are stated in the file readme.lcc.  icpp
is based on the public domain DECUS C preprocessor written by Martin
Minow.  The file readme.cpp is the readme file from the DECUS
distribution.  ias11 is based on the public domain assembler from
Motorola.  If you want information on how to obtain the sources for
unmodified versions of these programs, please look in the relevant
readme files or contact us.

The code generator component of the compiler, iccom11, is entirely of
Richard Man's creation and is not based on any existing compiler
technology.  Christina Willrich is the resident English language /
techwriting guru and helped to prepare anything that Richard has ever
published or distributed.  Thanks to Ariane (age 3) for letting us
finally use the computer after she played "Busytown" for the zillionth
time.

Copyright (C) 1993, 1994 by ImageCraft, Richard F. Man and Christina J.
Willrich. 

***** General Release Information Sheet *****
ICC11 is a high quality yet low cost compiler package that runs on DOS
real and protected mode environments.  Included in the package are:

A comprehensive 90 page manual.

A fast near-ANSI C  conformant compiler with built-in peephole optimizer.

Quality code generation.  Code size is typically only 5% to 20% larger 
than expensive ($500 to $1200) compilers.

Assembler, linker, and librarian.

Standard C header files and library functions.

HC11 specific support such as embedded assembly, pragma for
declaring interrupt functions, etc.

Calling conventions compatible with other compilers.

Both 16 bit and 32 bit executables.

Technical support over the Internet, including a mailing list
for discussions and product update information.

MIT Interactive C compatible multitasking kernel library!

Miniboard library.

Coming soon!  Add-on low priced multitasking executive with
subsumption architecture semantics.

Price: $39.95, plus $3.95 shipping and handling within the U.S., $5.00
S&H to Canada and $10.00 overseas.  CA residents please add 8 1/4% sales
tax.

To order, please send a check or money order (international orders may
use a "postal" check in U.S. dollars) to the address listed at the
bottom of the page.

Please direct email inquires to: imagecft@netcom.com.  To join the
mailing list, send the message "subscribe icc11-list" to
listserv@netcom.com.
***** End ICC11 Announcement *****