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