File:  readme.txt
Date:  9 July 1996
Revision:  April 1999 by Tom Almy


        Notes on the as12 cross-assembler for the Motorola CPU12


This distribution package contains the executable for as12, a PC-based
FREEWARE cross-assembler for the Motorola CPU12 family, including the
68hc12a4 microcontroller (MCU).  This package also includes a lengthy
test case and this file of notes.



                                DISCLAIMER

   I am releasing the executable for the as12 assembler, all supporting
  library and include files, and this document as freeware.  Feel free to
   use as12 for whatever non-commercial application seems appropriate.

     I make no warranty, representation, or guarantee regarding the
   suitability of as12 for any particular purpose, nor do I assume any
 liability arising out of the application or use of as12, and I disclaim
   any and all liability, including without limitation consequential or
                           incidental damages.

          You, as the user, take all responsibility for direct
    and/or consequential damages of any kind that might arise from using
                           as12 in any fashion.

    I do not warrant that as12 is free of bugs.  If you find what you
     think is a bug, kindly let me know what it is IN DETAIL, and I'll
     certainly consider fixing it in a later release, if there ever is
                                   such.

   I ported as12 as a tool for working with the CPU12 MCUs.  If you use
   as12 for developing robotics (or other) application code and find it
     useful, fine.  If you don't find it suitable in some fashion, then
                               don't use it.





History

The as12 assembler was originally developed by Motorola engineers and
used internally on a Unix platform to create test software during CPU12
development.  Following release of sample silicon for the 68hc12a4 in
late June 1996, Motorola was kind enough to release the source files to
me for porting to the PC platform.

Since as12 uses a command-line interface (CLI), porting to DOS made the
most immediate sense.  Thus, this version of as12 runs from the DOS
prompt; I don't have any plans to create a Windows version.



Invocation

To run the as12 assembler, type:

	as12

at the command prompt.  This will display a short help file describing
the command line arguments available to you.  To assemble a file, enter
a command such as:

	as12  foo.asm

Please note that as12 does not assume a default file extension for the
input file; you must specify the full file and extension.  Normally,
as12 writes its listing output to the console; you can use redirection
to save the listing output to a file.  For example:

	as12  foo.asm  >foo.lst

will create the listing file foo.lst.

Starting with version 1.1, as12 supports the -L option.  This option
allows you to specify a file path and name for holding the list output. 
By default, this listing output file uses an extension of .lst.  You
could accomplish the above example by:

	as12  foo.asm  -Lfoo               OR
	as12  foo.asm  -Lfoo.lst

Note that you must not use any spaces between the -L and the listing
output file name.

Starting with version 1.1, as12 supports the -o option.  This option
allows you to specify the output object file.  For example:

	as12  foo.asm  -ofoo.s19  >foo.lst

The object file carries a .s19 extension by default, so the above line
could have been:

	as12  foo.asm  -ofoo  >foo.lst

Note that you must not use any spaces between the -o and the object file
name.

Starting with version 1.2a (by Tom Almy), 

* A source file name with no extension defaults to the extension .asm
* The -L option, without a filename, uses the name of the first source file
* Error and Warning totals appear on the screen even if a listing file is specified
* The unary complement ("~") is implemented
* AS12 is compiled as a Win32 Console Application and allows long file names.
* The document file has been completed.


Documentation

What documentation is currently available came from the Motorola
engineers as the enclosed as12.htm file.  I have been editing this file
to clean it up a little, so you see it here in a state of flux.  Rather
than force everyone to wait until I get it edited the way I want it,
I've released it now.  Updates will follow, but the as12.htm file should
get you started.  Just point your web browser at the as12.htm file and
go for it.



Features

Those of you accustomed to the as11 68hc11 cross-assembler are in for a
pleasant surprise.  Although this is still an absolute (non-linking)
assembler, it has a very strong feature set, and can carry you a long
way with the CPU12 MCUs.

It supports #include files up to 5 deep, #ifdef statements,
command-line defines, and several cool pseudo-ops.  In particular, the
#ifp statement lets you test for the target processor in your source
code, so you can adjust your assembly depending on the CPU12 variant
that will ultimately execute the code.  For information on defining the
processor type on the command line, check the -p option in the as12.htm
file.



Known bugs and things I'd like to fix

If you #include a file, and that file contains an error, the as12 error
message incorrectly gives the input file name, not the included file
name.

Versions 1.1 and prior contain a bug that causes the assembler to lock
up if you try to assemble a source line containing a leading tab and a
label, though the bug doesn't appear if you use leading spaces.

If you find anything you think is a bug, please email me a copy of your
source file (at least the offending part) and a copy of the listing
output showing the bug.  I don't promise to fix it, mind you, but I
might (time permitting), so it's worth a shot.


						Karl Lunt
						karl@mav.com
						Bothell, WA