                        INSTRUCTIONS FOR ASM11
             Copyright (c) 1998 by Tony G. Papadimitriou, M.S.
                        e-mail: tonyp@acm.org

Hi 68HC11 enthusiasts,

PLEASE TAKE THE TIME TO READ THE ENTIRE DOCUMENT (SPECIALLY IF THIS THE FIRST
TIME YOU USE THIS PROGRAM).  THIS WILL HELP YOU AVOID UNNECESSARY
HEAD-SCRATCHING FOR WHAT'S ALREADY DOCUMENTED.

This archive should contain the following files:

              (      136355 bytes) for README.TXT      This file
CRC $7DF0FE81 (       36542 bytes) for ASM11.EXE       The assembler
CRC $1403C6FF (         540 bytes) for ASM.BAT         Batch to report ERRORLEVEL
CRC $904FCEED (       14586 bytes) for M.EXE           A file viewer
CRC $E28C63E0 (          28 bytes) for README.BAT      Run this to read docs
CRC $1195411D (       13630 bytes) for TERM.EXE        Terminal/S19 downloader
CRC $ECEAA6E2 (        8278 bytes) for SB2ASM11.EXE    SBasic ASM to ASM11
CRC $B88FA01F (        5573 bytes) for EXBIN.EXE       Convert S19 to binary
CRC $00C1C79C (       72957 bytes) for ASM11QRG.PDF    Quick Reference Guide
CRC $249CFF33 (         822 bytes) for FILE_ID.DIZ

This README.TXT file is not intended to be an assembly language manual or
tutorial.  It assumes the user knows how to program in 68HC11 assembly or has
the desire to learn and has relevant literature to consult.  If you are not
familiar with 68HC11 you should get a 68HC11 Assembly Language Reference,
some of them are free, if you know where to look.

If you are converting your source from some other assembler, please read the 
relevant section in this file.  It will save you time.

To most of the experienced 68HC11 users, a lot of the information in this
document may seem obvious and unnecessary to be mentioned.  I have to take
into account that some potential users are new to 68HC11 and assembly
language programming in general, so I've tried to make it a bit more
comfortable for them.

Several source files are included in the archive SAMPLES.ZIP.  All example
programs are only meant to illustrate acceptable assembly language syntax for
ASM11 more than to provide accurate working programs.  These programs,
although carefully reviewed, may contain errors, or not do exactly what they
claim to do.  They only provide examples for you to work with.  I believe
they are correct, but some bugs may exist in them so please take the time to
verify their correctness yourself (ie., don't use them blindly).

711E9.INC and 811E2.INC are a couple of files you can import (or $INCLUDE) at
the very top of your source to define commonly used symbols for the 711E9 or
811E2 MCUs, respectively.  Modify the files accordingly if you commonly work
with a different MCU that requires different values.  You may also wish to
enrich them with additional symbols that I left out.

FRAME.ASM is a source code skeleton I've been using which you may find useful
each time you start to write a new program.  It still needs a lot of
"refinement" and is not necessarily optimized or complete and (given enough
free time) I will try to make it better in possible future versions.  If you
happen to improve it and wish to share it with others, send it to me, and I
might post it along with the next version. You may change it to suit your
needs, preferences, and coding habits.  FRAME.ASM file includes 711E9.INC,
rather that have the file repeated inside it.

MULTBOOT.ASM is a source code skeleton for making programs that can be
extended after you have burned an OTP EPROM (such as in the 711E9).  This is
useful while test running your code to help cut down on wasted chips.  It's
commented enough to be able to follow it.  The technique will also apply to
EEPROM, although the need isn't so great there.  It's a demo, so remove all
unnecessary comments and code fragments that aren't actually needed.

S19LOAD.SUB is a subroutine you can include in your program to provide an S19
loader with offset adjustment capabilities.  It also provides subroutines for
hex conversion, reading the SCI port, etc.  It uses only stack space so you
don't need to define any variables.  The S19TEST.ASM file sets up an example
run for the S19LOAD subroutine.

FLASH.ZIP contains a complete working program for programming Flash memories 
(written for ASM11 and kindly provided by Mark Schultz).

ABOUT THE EXTRA UTILITIES INCLUDED:

There is an extra utility included in this archive, M.EXE (a MORE type
program).  This is a Freeware utility for viewing text files.  Type M on the
command line by itself to get a comprehensive help screen.  You may use this
utility to view listings, source files, etc.  It will adjust to any screen
display, whether you're working at 40, 80, or 132 column widths.  (In case
you didn't know, most systems support wider than 80-column displays -- even
under DOS, which for one thing makes it easy to view assembler listings in
all their beauty without printing them out.)

Another function of this utility is that it will act as a Unix-to-PC file
converter.  The assembler expects regular DOS text files and it will not
correctly read files that aren't such, eg., files that do not end with CR/LF
or simply a CR.  Please note that assembling such files does not always
produce errors or warnings because if, for example, there is a CTRL-Z
(end-of-file) character, the assembler will stop reading the source file
assuming its the end of it.  Also, files having only LF as end-of-line marker
will only have their first line processed, and in most cases this will not
give any errors, since usually the first line is either a comment or some
equate.  This may give you the impression you source has assembled correctly
when in reality, only a portion of it has and it simply happened not to
produce errors.  One way to quickly check for such problems is to look at the
line number counter at the end of the assembly.

If you still have problems, there may be nulls (ASCII 0) or other strange
control characters left in the file.  You could try clearing those away by
loading the file into an ASCII editor, and re-saving it.  Not all ASCII
editors will do that, though.

Yet another function of M.EXE is to de-tab a file, ie., expand its tabs.
Although ASM11 can use the -Tn option or the $TABSIZE directive to control
tab expansion of the source file, you may wish to convert someone else's
source to a no-tabs text if you don't normally save your sources in tabbed
form.  You set the -Xn option to whatever tab size the original is using,
then redirect the output to the new file, eg.,

M -X10 TABBED.ASM >UNTABBED.ASM

will create the file UNTABBED.ASM by expanding possible tabs inside
TABBED.ASM and using a tab size of 10.  What tab size to use is not easy to 
tell.  Normally, most editors use a default value of 8, but they also allow 
changing this value to any number.  Before converting, try viewing the file 
with different -Xn settings until you see instruction, operands, and comments
align properly (although that's not always the case).

Note, however, that M.EXE wraps lines at the width of the current video mode, 
so if run from an 80-column display, everything beyond column 80 will be
placed on a new line.  This may require some further editing to bring wrapped
lines back up to the line they belong.

One other extra freeware program included is TERM.EXE (a very basic terminal 
program).  Type TERM -? to get a comprehensive help screen.  Set the options 
(such as COM port, BAUD, etc.) that apply to your setup, then save them with 
the -W option inside the TERM.EXE file so it will remember them.  TERM is not
only meant for use with evaluation boards (actually it was written for
remotely controlling a DOS PC using DOORWAY), but this is the reason for
being included here.

TERM has been updated to allow uploading even without the -E option (so that
it can be used with other systems that do not accept the LOAD T command).

Once configured, typing TERM brings up a screen that let's you talk to an 
EVBU, EVM, or EVS system.  You can use the PgUp key on your keyboard to give 
the filename of an S19 file to upload to your system.  Note that PgUp does 
not require having typed the "LOAD T" command beforehand, actually, you 
shouldn't (when the -E option is on, otherwise you should type LOAD T in 
advance).  It will take care of it, automatically.  Although not tested with 
every system, it should work on all evaluation boards that accept the BUFFALO 
command LOAD T to load an S19 file.  It has been tested on an EVBU and an 
EVS.  You may exit the terminal mode by pressing the SysRq key (usually
CTRL-PrintScreen, laptops may require a different sequence).

There are some reports that when the -E option is enabled the upload won't 
work.  This is very likely a problem with delayed responses from the LOAD T 
to the beginning of the upload (I'll look into it).  If you have problems 
like this, turn off the -E switch and manually type the LOAD T command before 
commencing the upload.  It should work at speeds upto 9600; you may encounter 
problems at higher speeds as the MCU itself (running at 2MHz) isn't ready to 
read another line and gets out of sync.  This will also depend to a certain 
extent on the length of your S19 records (longer ones are more likely to 
cause errors).

The SB2ASM11 utility is a "quick and *very* dirty" program to make SBasic 
produced assembler programs ASM11 compatible.  It does not do any syntax 
checking, so it could make mistakes.  What it does, actually, is change all 
occurences of -*- to -$- in every line (wherever they may be found, even 
inside comments).  It also changes " incl " to " $include " in every line
(wherever they may be found, even inside comments).  I have found these two
changes to get all sample programs that come with SBasic compatible to ASM11.
If you find more changes are needed, let me know so I can upgrade it
accordingly.

To use SB2ASM11, first compile your SBasic code to an .SBA (SBasic Asm) file,
using a command similar to: SBASIC MYPROG.BAS >MYPROG.SBA

Then, use SB2ASM11 to make it ASM11 compatible.  SB2ASM11 accepts the same
file parsing as ASM11, so you could type SB2ASM11 . to convert all .SBA files
to .ASM files.  Note, that since this is a simple utility, I haven't taken
the time to add luxuries such as options, etc.  So, input files should always
be with the extension .SBA and output files will always have the extension
.ASM (ASM11's default).  Perhaps you could write a small filter yourself that
is more efficient, does a better job, and allows something like: SBASIC
MYPROG.BAS | filter >MYPROG.ASM

EXBIN.EXE lets you convert S19 files to binary.  A simple utility with no 
error handling or other niceties (on errors, such as file not found, you will 
get cryptic numeric messages).  It will simply convert an *ordered* S19 file
(one whose addresses are in ascending sequence, if not you can use BSORT
FILE.S19 -5 to put it in ascending address sequence but this will destroy the
S19 file for other purposes because it will also misplace the S0 and S9
lines).  If the S19 if unordered, the conversion will be wrong.  EXBIN allows
you to also give a fill-value for unused bytes that are within various
code/data sections.  The default is $FF which is the erased state of E(E)PROM
for the 68HC11.  The image will contain all bytes from the first to the last
bytes used (filling missing bytes with the fill-value).

I mention BSORT in several places within these instructions, but I am not
including this utility here because there isn't a direct relationship with
the purpose of this package, and it could easily be replaced by your favorite
text sort utility.  BSORT is yet another freeware utility of mine, which you
can get directly from me on request.

Or you can try downloading the file from:

ftp://www.aspisys.com/public/freeware/bsort.exe

This is also a good place to check for updates to ASM11 (if you have received
your copy from a different source).  Look for filenames in the format
ASM11_xx.ZIP where xx is a number; higher numbers indicate newer versions.

(However, I cannot be certain for the continuous service of this site, it's 
likely to be on and off.  If you can't get an upgrade anywhere else, write to 
me directly at tonyp@acm.org and I'll send you the file by e-mail 
attachment.)

FEATURES AND (FEW) LIMITATIONS:

   Two-pass DOS based command-line 68HC11 cross-assembler.  You may also run
    the program from within a Windows DOS box, or have your favorite IDE (DOS
    or Windows) call it automatically at the press of a key.

   To get a full-screen of help simply type ASM11 without any filename
    specifications.

The following is ASM11's help screen (displayed when you type ASM11 <ENTER>).
----------------------------------------------------------------------------
ASM11 v1.46  Copyright (c) 1998 Tony Papadimitriou (tonyp@acm.org)
Usage: ASM11 [options] [@][path][/][mask][[,mask]...] [options] [> errfile]
       MC68HC11 two-pass cross-assembler for DOS-based systems
    Extra mnemonics         Equivalent [series of] standard instructions
     LDA/STA/LDB/STB/ORA/ORB LDAA/STAA/LDAB/STAB/ORAA/ORAB
     PSHD/PULD/CMPD/CMPX/CMPYPSHB,PSHA/PULA,PULB/CPD/CPX/CPY
     CLRD/CLRX/CLRY/INCD/DECDCLRA,CLRB/LDX #0/LDY #0/ADDD #1/SUBD #1
     COMD/NEGD/XGAB          COMA,COMB/COMA,COMB,ADDD #1/PSHA,TBA,PULB
     CLS/CLX                 PSHA,TPA,ANDA #$7F/#$BF,TAP,PULA (Clear S/X flag)
     SES                     PSHA,TPA,ORAA #$80,TAP,PULA (Set S flag)
     WAIT/OS(W) x/LBRA/LBSR  CLI, WAI/SWI, DB x/SWI, DW x/see docs
    $IF(N)DEF IF(N)Z ELSE ENDIF IF expr1 [=,<>,<,>,>=,<=] expr2  TABSIZE n
     #INCLUDE LISTx WARNING ERROR FATAL S19FLUSH CASEx EXTRAx MAPx (x=ON/OFF)
    Modes: #IMM @DIR <DIR >EXT AUTO ,X or ,Y INDEXED  String delimiters ' " `
    Operators: + - * / \mod >shr <shl &and |or ^xor ~swap [lobyte ]hibyte
      OPTIONS (+ stands for active, - for inactive, none will toggle)
   -   -C[] Case sensitive labels -Tn set Tab every n columns [8]
   -   -E[] create *.ERR file(s)  -EH[] On E+ Hide errors from screen: YES
   +   -L[] create *.LST file(s)  -LS[] create List of Symbols *.SYM: NO
   +   -M[] create *.MAP file(s)  -MTx source-level Map Type (x=P,A) [P]
  74   -Rn set n max S19 rec size  -R.ext sets default ext [.ASM]
   +   -S[] create *.S19 file(s)  -SH[] Create S0 header: NO
   +   -X[] allow eXtra mnemonics -W Write options inside EXE
----------------------------------------------------------------------------

   Assembles many files at once using wildcards or list files.  Examples:
    Command              Files to be matched
                  
    ASM11 .              *.ASM
    ASM11 .A11           *.A11 (Any extension may be specified except for
                               those used for files created by ASM11, ie.,
                               S19, LST, MAP, ERR, and SYM.  I hope you won't
                               find this too much of a restriction.)
    ASM11 *.S19          None  (S19 is used by ASM11 as object code output
                               and cannot be used for source programs.  ASM11
                               will ignore the invalid extension and skip
                               over the file.)
    ASM11 OS,TEST*       OS.ASM and any file matching TEST*.ASM in the order
                         they are found in the directory.
    ASM11 /              \*.ASM
    ASM11 /temp          \TEMP.ASM
    ASM11 /temp/,?       \TEMP\*.ASM and any files matching ?.ASM
    ASM11 file1 file2    FILE1.ASM and FILE2.ASM in the order specified
    ASM11 .,.a11         *.ASM and *.A11 files in the current directory
    ASM11 ,.a11          -//- (note the missing dot)

    ASM11 @FILELIST      all files that match each wildcard spec inside
                         FILELIST.  If FILELIST contains the lines:
                              SAMPLE,DEMO
                              /PROJECT/
                              /PUBLIC/.A11
                         then files that match:
                              SAMPLE.ASM
                              DEMO.ASM
                              \PROJECT\*.ASM
                              \PUBLIC\*.A11
                         will be assembled

  NOTE: You may change the default extension from .ASM to some other of your 
        liking.  See the -R.ext option later in this document.  The above 
        examples assume you haven't changed the default .ASM extension.  Both 
        forward and backward slashes may be used wherever you specify 
        filenames (even inside the source code).

   Many options are single letter (except for -EH, -LS, -SH, -MTx, -RTS,
    -REL, and -R.ext), always begin with a - and may be placed anywhere on
    the command line.  They may not be merged together, so to specify, say, S
    and M, you must type -S -M but not -SM.

    All options (except for -W, -R, and -T) may be followed by a + or - sign
    to indicate that the option is to be turned on or off, respectively.  An
    option (that can take a plus or minus after it) without the trailing sign
    will toggle the current (saved default) switch state.  To see the default
    switch settings, run ASM11 without any arguments.  You will get a help
    screen along with the active switch settings.  If, however, you supply a
    switch but no filename mask (eg., ASM11 -X-), you will see the settings
    after this switch has been processed (ie., not necessarily the saved
    default).

    The same switches may appear on the command line as many times as you
    like.  Toggles will apply each time a switch without a + or - is
    encountered.  If you use + and - signs, the last one processed will be
    effective.

    All options (regardless of their position with respect to supplied
    filenames) will be processed before filename parsing begins.  This means,
    you cannot use something like:

    ASM11 -S- FILE1 -S+ FILE2

    expecting to assemble FILE1.ASM with no *.S19 and FILE2.ASM with *.S19.
    Since the last option sets S19 production on, both files will produce
    *.S19 files (on successful compilation).  This applies to all options.

    The -W option (actually a command so it cannot be saved itself) does not
    expect a + or - after it.  It is used to save (Write) the state of all
    options appearing before it inside the ASM11.EXE file.  I never liked 
    separate configuration files for such trivial things that get lost when 
    copying the program from one location to another.  For example, ASM11 -S+ 
    -M- -W -L+ will make default the production of *.S19 files and the 
    omission of *.MAP files while leaving the L option unchanged because it 
    follows -W.  You will get a message saying that the configuration was 
    saved (or not, if there was some error, normally, a disk-write or 
    disk-protected error).  Make sure the file's attributes allow writing to 
    it (no read-only flags).  Once you save your new defaults you may wish to 
    protect ASM11 from accidental modifications by setting its Read-Only 
    attribute with the DOS command ATTRIB +R ASM11.EXE No assembly will take 
    place when the -W command is used.

    *** ALL COMMAND-LINE OPTIONS (EVEN THOSE NOT SHOWN) ARE SAVEABLE ***

  NOTE: If you use the -W option even once, the ASM11.EXE file will grow in
        size just by a few bytes (only the very first time) and its CRC
        checksum will change (almost everytime).  This may make some
        anti-virus programs think there was some sort of an infection.  Don't
        panic, it's normal for them to think so, that's how many anti-virus
        programs work.  (I know what some of you are thinking; if your copy
        of ASM11 ever does get infected by a virus and you also happened to
        have used the -W switch, how will you know if the anti-virus program
        is telling the truth?  Well, let's just hope that the virus will be
        an equal-opportunity one and strike other program files as well!
        This will be a good indication.)

    Having saved your default options, you may alter the current state of any
    of them, by giving the option without a trailing + or - sign.  However,
    if you create DOS batch (*.BAT) files to call the assembler, or invoke
    the assembler from within an IDE which has been configured to run ASM11
    by hitting a single key, you may want to supply all available switches
    with trailing + and - signs as appropriate to guarantee the desired
    operation.  For example, call ASM11 with a command similar to this:

                    ASM11 -S+ -M- -L+ -C- -X+ -LS+ ...

    but not like this:

                    ASM11 -S -M -L -C -X -LS ...

    This is to avoid problems when after having saved some configuration, you 
    create a batch file (or setup your IDE) assuming that initial
    configuration, then later change the saved configuration to some other.
    The first example will set each option explicitly on or off, in effect
    ignoring the saved defaults, while the second will simply toggle what's
    the current default.  If you don't specify options with + and - signs in
    your batch files (or wherever else the program is invoked automatically,
    such as from within an IDE), you will have to remember to modify them
    (batch or IDE), also.  All this, of course, assuming you want your batch
    file or IDE to behave the same regardless of what happens to ASM11's
    default settings from time to time.

   Optionally produces *.S19 object files.  Turn this option on with the
    command line switch -S+ (or simply -S to toggle on/off depending on
    the current state).  The default for this switch is ON.

    For those not familiar with them, S19 files are standard object code
    files.  They are accepted by most eprom programmers, simulators,
    emulators, and so on (especially if they are related to 68HC11 which is
    of interest to us, anyway).  They are ASCII files and can be edited by
    any ASCII text editor.  If your programmer (device, not human) or loader
    require a different format, you can get one of the several freely
    available utilities for converting from one format to another.

    Most S19 files of interest to us consist basically of two types of 
    records, one for code/data (those lines starting with S1) and one for end 
    of file (the line starting with S9, there should be just one of this 
    type).  Actually, you may even change the order of all S1 type records 
    without causing any damage, as each record holds its own address
    information.  S9 records normally hold the starting address of the
    program or module which some assemblers (including this one) produce
    based on the label next to the END statement, but since in an MCU this is
    always fetched from the appropriate reset vector, which you must
    explicitly define in your program, this record will normally point to
    address $0000, and you shouldn't worry about it.  However, if you do
    specify an END statement with a label, that label's value will be used
    when creating the S9 record.  This is sometimes useful for some programs
    (such as the example S19 loader supplied) that expect the execution
    address to show in the S9 record.  (By the way, many programs that *read*
    S19 files have wrongfully hardcoded the S9 record assuming a zero address
    "S9030000FC", so using a different S9 record will confuse them.  Do not
    use an END label or expression in those cases.)

    Although most S19 loaders will read files with just these two record
    types, some will try to be "cute" and require a third type of record (the
    header/info type that starts with S0).  Although, they should not be
    bothered by a missing S0 record, some will (just to make your life
    harder).  If you come across such as program, use the (v1.39B added) -SH+
    option to enable dummy S0 record creation.  If you commonly use such a
    system, you may save the option with the -W command.

    To define the maximum S19 record length use the -Rn option (see below).
    The default length is 74.  Larger numbers produce smaller file sizes on
    average.  Please note that some programs will load any length S19
    records, while others have a limit of less than 80, or so, characters per
    line.  The default value provides reasonable file size while being
    compatible with most S19 loaders.

    S19 files normally hold data in sequence until the full width of the
    record is reached, unless a new address forces a "break" sooner.  You may
    wish to force this break yourself, see the $S19FLUSH directive.  One use
    for this is to compare your S19 output to that of other assemblers that
    incorrectly break the S19 record when encountering an ORG even if the
    addresses are in sequence and, thus, not justify breaking to a new line.
    Another use is to make certain sections of code (perhaps debugging code)
    appear separately in the S19 file so you may easily edit those sections
    out by deleting the respective lines without worrying about affecting
    neighboring code/data.

    Some S19 loaders incorrectly use greater than 16-bit addresses after 
    $FFFF, although they are dealing with S1 type records that are intended 
    for 16-bit addresses only.  Instead, they should wrap around and start 
    over from zero.  To avoid problems with them, you could again use the 
    $S19FLUSH directive to "manually" break to a new record when reaching 
    address $FFFF + 1.  To illustrate one example of when this might happen, 
    consider the following (which has been corrected with the use of the 
    directive):

               ORG       $FFFE
               DW        Start
    $S19FLUSH  ;Force the above and below lines on separate S1 records
               ORG       0
    Start      LDS       #$1FF

    The minimum record size value of 12 may be useful in circumstances during
    testing where you want to have each byte on a separate line so as to make
    editing of certain bytes a lot easier.  The *.S19 file size will grow
    significantly, however.

    Having the option to set the S19 record size is also useful when you'd
    like to compare your object code to an existing S19 file produced by some
    other assembler/compiler (say, when assembling BUF34 and then comparing
    it to the original BUF34.S19 or the one dumped from your EVBU).  Make
    your S19 output match the size of the original and then simply do a file
    comparison to find if any bytes are justifiably different.

   Optionally produces *.MAP source-level map files.  Two types of MAP 
    formats are supported.  The first is compatible with P&E's simulators and 
    aevms.  The older P&E map format used in EVMs and older simulators is not 
    supported as it does not allow source-level debugging, only symbolic 
    debugging (and it has a lot of other inherent problems as well).  The 
    second type of map format is pretty much an ASCII version of the same 
    information.  Turn this option (map file creation) on with the command 
    line switch -M+ (or simply -M to toggle on/off depending on the current 
    state).  The default for this switch is ON.  I added the ASCII 
    source-level map file in hopes that others will add support for it in 
    their products (be it freeware/shareware, or commercial).  It is a lot 
    easier to implement a loader for the ASCII map file than the secretive 
    binary P&E one.  Although the ASCII version of the map file is 
    considerably larger than the binary P&E format, the purpose of MAP files 
    is only valid during debugging, so it can be deleted afterwards.  The 
    format of the ASCII file is self-explanatory.  Only the [FILES] and 
    [LINKS] sections are required, [COMMENTS] is optional and may be left out 
    (this assembler generates it to help others understand its format).
    Assemble the supplied FRAMES.ASM program with the command ASM11 FRAMES
    -MTA (assuming you haven't yet changed the default settings), then look
    at the resulting FRAMES.MAP (it should be clear enough to be able to
    follow it).

    To define which of the two formats to produce, use the -MTx switch 
    replacing x with either P (for P&E binary format) or A (for my own ASCII 
    version of the same format).

    The -MTP MAP file format cannot be read directly.  You need specially 
    written software to read these files.  One such utility (SHOWMAP.EXE) may 
    be available for free from P&E.  However, even without this utility you 
    can get the same information using the -MTA switch for an ASCII version 
    of the map file.  The default format is P&E (for consistency, because 
    that was the only format supported in previous versions).  So, if you 
    would like to always use the ASCII version of the map, give the command: 
    ASM11 -MTA -W to make ASCII maps the default.  Be advised, however, that 
    since this is a new format, at the time of this writing (Oct 98), nobody 
    is expected to support it.  It will only be useful if you're willing to 
    write a conversion utility from this to some other format your 
    development tools use (assuming you have enough information about that 
    other format).  As time goes by, I expect others will be willing to adopt 
    it.

    Source-level Map files are useful for tracing code in a simulator or 
    emulator while looking at source code rather than disassembled 
    instructions.  If you're using a P&E simulator, such as my favorite 
    SIM11E and its counterpart, the EVM/EVS control program AEVM11 (both of 
    which, although far from being the ideal tools, are good enough and I can
    highly recommend to those who haven't already decided yet), you will be
    able to single-step through your source code (using the command SS
    [Source Step], see your documentation for those products).  What's also
    nice with this assembler is that extra commands that are a series of
    instructions will appear as if they were single instructions, just the
    way you intended.  If this is not what you want you can always Trace
    through your code, or not use the extra instructions.

    Just a couple of quick notes on parsing the ASCII MAP file.  Search for 
    lines starting with a left square bracket to identify sections.  Others 
    may be willing to add more sections to accomodate their tools, also.  For 
    compatibility reasons, they should also generate the [FILES] and [LINKS] 
    section (as described) in addition to their own sections, even if there 
    is duplication of information.  From ASM11's point of view, only [FILES] 
    and [LINKS] are needed.  [COMMENTS] is optional and it only appears to 
    give a short description of the MAP file itself, so others need not 
    produce it.  Only these three sections are defined by myself, other 
    sections may be defined by others (I would appreciate those doing so 
    keeping me informed).  Blank lines within any section are for readability 
    only and should be ignored.  The sequence of file names (which may 
    include paths, either relative or absolute as obtained from the source 
    code definitions) in the [FILES] section defines the file numbers used in 
    the [LINKS] sections.  File numbers start from 1, 0 is used to indicate a 
    non-file linked symbol, for example an equate that although definitely 
    found in some file, has no source-line associated with it for the 
    purposes of tracing code.  If the file number is zero, the possibly 
    non-zero line number should be ignored as well, and the whole line is 
    used only to associate the symbol name with the hexvalue.  Zero file 
    numbers with non-zero line numbers are the result of $MAPOFF being in 
    effect (but others may choose to zero both values and completely hide the 
    origin of those symbols).

    If you don't have software that utilizes any of the supported formats for
    a map file, turn the -M option off and save it with the -W command.

    If case-sensitive assembly was requested with the -C+ option, this will
    also be reflected in the MAP and SYM files.  That means you must give
    mixed- or lower-case symbol names using the same case as that in the
    source program, or it won't work.  Unless you really have to do
    case-sensitive assembly, I recommend leaving the -C option off.  There
    are, however, some programs out there that make extensive use of upper
    and lower case symbols that are the same, except for the case.  If when
    assembling a file, you get too many "duplicate symbol" type errors along
    with "phasing errors", try re-assembling with -C+ and you might be
    surprised to see them go away.  If that's the case, edit the file and add
    the $CASEON directive at the top (not to have to remember to use the -C+
    option next time).

   Optionally produces *.LST assembly listing files.  Turn this option on
    with the command line switch -L+ (or simply -L to toggle on/off depending
    on the current state).  The default for this switch is ON.

    The listing format is:

    1. Source File Line Number (5 digit space filled decimal number).  The
       line number may be displayed more than once (in consecutive lines) if
       the data produced for a line is longer than can fit in one (such as
       when an FCB with a relatively long string operand is encountered).

    2. Instruction/Data Address (4 digit hex number).  This is both for
       instructions and pseudo-instructions (such as RMB and FDB) that cause
       the Program Counter to change value.  This is followed by a colon (:)
       to visually aid the separation from the code/data columns.

    3. Up to three words (as 4 digit hex numbers) of the opcode/data bytes 
       produced by the given [pseudo-]instruction, separated by single 
       spaces.  For Branch-type instructions (except for the extra LBRA and 
       LBSR), the effective address is also shown within parentheses.

    4. A cycle counter in [xx] format where xx is a 2-digit space filled
       decimal number indicating the number of cycles required for the
       instruction to execute.  The minimum cycle count is displayed in cases
       where there are variations based on execution.  The special test mode
       instruction TEST is shown with a cycle count of 0, since this
       instruction, once executed, runs forever (or until a reset) and is not
       really meant for normal program use.  Built-in macros will display the
       aggregate cycle count of their component instructions, thus giving the
       impression they are actual 68HC11 instructions.

    5. The original source text.  This is unmodified, just the way it was
       read from the source file.  However, if the -Tn option is used with a
       non-zero value (as with the default value of 8) tabs will be expanded
       using spaces.  All other characters will be left as is.  To not have
       tabs expanded, use -T0 (zero).  Please note that the author of the
       source (assuming it's someone else's code) may have specified the
       $TABSIZE directive (if the source was specifically written for ASM11).
       In that case using the -Tn option has no effect (unless, you edit the
       file and remove the $TABSIZE directive).

    Those pseudo-instructions, such as the FCB, that can take multiple
    operands have their data and beginning address displayed separately for
    each operand.  This makes it easy to see where each starts and ends, even
    though they may be together in the source file.

    One way to look at a sample of a listing, is to do the following with the
    source that's included with ASM11 (assuming you haven't changed the
    default options yet):

                         ASM11 FRAME
                         M FRAME.LST -T

    Starting with version 1.10B, at the end of the listing you will get a 
    small report of the number of code/data/image bytes produced by your 
    program.  This is useful for knowing EPROM requirements of your code.

    CODE represents the total byte size of opcodes and operands (including 
    the implied FCB and FDB following the SWI in the OS and OSW extra
    instructions).

    DATA represents the total byte size of all FCB, FCC, and FDB type 
    statements that cause data bytes to be produced (excluding the implied 
    FCB and FDB in the OS and OSW extra instructions).  This will also
    include vectors (eg., at the FFD6-FFFF range) you have defined using DW,
    etc.  It does not count RMB or DS sizes as these two do not produce data, 
    they only advance the address/program counter.  (Since I added this, I
    have found it to be quit useful when trying to cut down the size of a
    program in order to fit smaller devices, such as the 811E2.  Some
    programs showed me CODE would fit, but DATA was too big in proportion.
    So I shortened messages and made them fit.)

    IMAGE represents the sum of CODE and DATA sizes, and is probably the one
    you're more interested in, since it's the total memory requirement of
    your program.  Note, however, that image size is only the number of bytes
    of storage required if the bytes were to be placed in sequence, without
    gaps in between. In other words, if an image size is less than 512, it
    doesn't necessarily mean that it will fit your 711E9 EEPROM.

    Here's a sample of that section of the listing:

    -------------------------------------------------------------------
    Total CODE  size:   1071   $042F    1.05 KB
    Total DATA  size:    248   $00F8    0.24 KB
    Total IMAGE size:   1319   $0527    1.29 KB

    Lowest address  :  53248   $D000
    Highest address :  65535   $FFFF
    Address Range   :  12288   $3000   12.00 KB   (Used Range: 10.73%)

    Number of INCLUDE files: 2

    Assembled 500 lines (No Errors, Warnings: 0)
    -------------------------------------------------------------------

    The second group of three lines shows the lowest and highest addresses
    used by either code or data, along with the calculated distance (range)
    between those two extremes.  This, in effect, gives you for many cases
    (but not all), the actual size and mapping of memory required to fit the
    program.  The "User Range" percentage is in relation to the Address
    Range.  In the example above, we see that we need an E9 chip (based on
    addresses used, $D000..$FFFF, 12KB), but we have only utilized 10.73% of
    that chip's memory.  If the internal EEPROM is also mapped the results
    will not be as obvious (because there are gaps in the physical mapping of
    memory) but will again give a pretty good idea of what's required in
    terms of memory.

    Finally, the last line will always show "No Errors" because in case of 
    errors *.LST files are deleted.  The "Warnings:" part will show the 
    number of warnings for this assembly.  Please note that the actual 
    warnings will NOT appear within the listing but only in the *.ERR or 
    redirected error file assuming one was requested (and/or the screen).

   Optionally produces *.ERR error files (provided there are errors or
    warnings).  Turn this option on with the command line switch -E+ (or
    simply -E to toggle on/off depending on the current state).  The default
    for this switch is OFF.

    There may appear several errors and/or warnings for a single source code
    line.  This is normal.  Usually, fixing the problem indicated by one of
    the errors, will make all of them (and some for different lines that
    somehow relate to this one) go away.  For example an unknown instruction
    will cause both a Syntax Error and a more specific error indicating the
    string that cannot be recognized.  Sometimes, especially for less
    experienced users, examining all error messages pertaining to a single
    line will give you enough clues as to the needed action to correct the
    problem.

    In the event of errors, corresponding *.S19, *.MAP, and *.LST files will
    be deleted, provided the corresponding option was turned on (otherwise,
    they will not be affected so that older versions of the corresponding
    files will not be deleted).  Errors and warnings do not go into the *.LST
    file (as with other assemblers) but into the *.ERR file as well as the
    screen, so deleting the incomplete *.LST on a unsuccessful assembly does
    make sense.

    *.ERR files are deleted whenever there are neither errors nor warnings,
    regardless of the state of the -E option.

    NOTE: Starting with version 1.16B you may also send warning and error
          messages to whatever file you like and in whatever directory you
          choose, using standard DOS output redirection.  This ability does
          in no way interfere with normal *.ERR file processing, and the -E
          and -EH switches have no effect.  Also, in case of no
          errors/warnings, this file will not be deleted (it will be blank),
          since ASM11 has no way of knowing which file this is.  Another
          difference between *.ERR files and redirected errors is that the
          latter will contain full path information, sometimes used by IDEs
          to place the cursor at the appropriate file and line number.  One
          good shareware editor that easily understands ASM11 error messages
          is WinEdit (for Windows).

    You may even cause your own errors or warnings from within the source
    (normally under conditional assembly) to alarm the user to some fact s/he
    must know about or, perhaps, correct in the code.

    Using -EH followed by an optional + or - (just like most other options)
    lets you send error and warning messages to the *.ERR file but not the
    screen.  This is only meant to be used when the -E option is turned on,
    otherwise, it has no effect.  This option is useful when you assemble
    many files in a single operation, use the -E+ option because errors just
    have to be directed somewhere (don't they?), and only care to see on
    screen the summary of errors and warnings for each file that is displayed
    at the end of the assembly next to the file name.  You can then go and
    look at the *.ERR files for each one that had either errors or warnings.
    If you always want errors and warnings to go the screen, regardless of
    the state of -E switch, turn this option OFF with -EH- save it with -W
    and never worry about the -EH option again.  The default for this option
    is ON.

   Optionally produces *.SYM files, a plain list of symbols and their 
    associated values in hex.  This list is not sorted in any particular 
    order and does not have fancy headers or extra messages.  Turn this 
    option on with the command line switch -LS+ (or simply -LS to toggle 
    on/off depending on the current state).  The default for this switch is 
    OFF.  SYM files provide only some of the information available in an 
    ASCII map file produced with the -MTA option.  For more detailed symbol 
    information, you may wish to use that instead.

  NOTE: All files produced (except for the stdout redirected one) will always
        reside in the same directory as their source files, regardless of
        what directory the user was in when giving the ASM11 command.  For
        this reason, it would be best to organize your projects in
        subdirectories each dedicated to a single project.  That also makes
        it easy to assemble all files in that directory by either going into
        the directory and giving the command "ASM11 ." (without the quotes)
        or giving only the directory name as a parameter, followed by a
        slash, eg. "ASM11 C:/ASM/OS11/" (this will assemble all
        C:\ASM\OS11\*.ASM files).

   Optionally becomes case-sensitive for user-defined symbols/labels.  This
    option does not apply to mnemonics or pseudo-instructions which are
    always case-insensitive.  Turn this option on with the command line
    switch -C+ (or simply -C to toggle on/off depending on the current
    state).  The default for this switch is OFF.  Note that case is also
    reflected in the MAP and SYM files (read the MAP section for more
    information).

   Optionally recognizes additional mnemonics that are either an alias to an 
    original mnemonic or a built-in macro that translates (internally) to a 
    series of instructions.  Turn this option on with the command line switch 
    -X+ (or simply -X to toggle on/off depending on the current state).  The 
    default for this switch is ON.  This is also controlled from within the 
    source with the $EXTRAON/$EXTRAOFF directives.

    Here's a list of all extra instructions and their equivalence.
    Instruction          Equivalent instruction (or series of instructions)
              
     LDA                 LDAA
     STA                 STAA
     LDB                 LDAB
     STB                 STAB
     ORA                 ORAA
     ORB                 ORAB
     PSHD                PSHB, PSHA
     PULD                PULA, PULB
     CMPD                CPD
     CMPX                CPX
     CMPY                CPY
     CLRD                CLRA, CLRB
     CLRX                LDX #0
     CLRY                LDY #0
     COMD                COMA, COMB
     NEGD                COMA, COMB, ADDD #1
     XGAB                PSHA, TBA, PULB
     INCD                ADDD #1
     DECD                SUBD #1
     CLS                 PSHA, TPA, ANDA #$7F, TAP, PULA  (Clear the S flag)
     CLX                 PSHA, TPA, ANDA #$BF, TAP, PULA  (Clear the X flag)
     SES                 PSHA, TPA, ORAA #$80, TAP, PULA  (Set the S flag)
     WAIT                CLI, WAI
     OS <byte value>     SWI, DB <byte value>  (Useful for calling OS
                         functions, eg. OS fWriteln)
     OSW <word value>    SWI, DW <word value>  (Useful for calling OS
                         functions, eg. OSW fWriteln)
     LBRA                A 24-byte/76-cycle sequence that jumps to a location
                         using relative-mode emulation (ie., with the help of
                         the assembler, it adjusts the PC using appropriate
                         offsets).  Not meant for casual use.
     LBSR                A 34-byte/99-cycle sequence that jumps to a
                         subroutine using relative-mode emulation (ie., with
                         the help of the assembler, it adjusts the PC using
                         appropriate offsets).  Not meant for casual use.

    NOTES: The XGAB instruction is implemented as a B to A transfer (TBA),
           and not the other way around, because this sets/clears the N flag
           correctly.  Doing a "PSHB, TAB, PULA" sequence will give the same
           result in D, but because of the A to B transfer (TAB) the N flag
           is inverse from what is should be assuming the N flag at the end
           of the operation should indicate whether D's new value is negative
           or not.

           The PSHD and PULD instructions are implemented so as to read 
           from/write to the stack the correct D value, so that PSHX and then 
           PULD (or the inverse), for example, will work correctly.  (By the 
           way, does anyone know if there was a reason for the interrupt 
           stack frame to have the D value in reverse order which prevents a
           direct ldd 1,x type instruction to be used?)

           The OS and OSW instructions require special treatment in the SWI
           handler to operate properly, or else the 8-bit or 16-bit opcode
           that follows SWI will be treated as an instruction with
           unpredictable results.  If you're not familiar with this
           technique, see the example source code FRAME.ASM to get an idea of
           how to write such handlers.  Keep in mind that normally, either
           one or the other can be used within the same program, rarely both,
           as it becomes very difficult for the SWI handler to decode whether
           one or two bytes follow the SWI.  Although their names imply using
           those for Operating System calls, imaginative programmers could
           use them for other purposes.

           The CLRD instruction is implemented as CLRA followed by CLRB.
           This sequence is preferred to LDD #0 which although faster (3
           cycles instead of 4) it produces larger code (3 bytes instead of
           2).  If in your application you must save every cycle you can,
           replace CLRD with LDD #0.

           CLX, CLS, and SES save and restore the value of register A which
           is modified during execution.  This was done so you use the
           instructions without worrying about side-effects.  In some
           situations, however, you may not be interested in preserving
           register A's value so you may want to avoid using this macro and,
           instead, explicitly modify the flags yourself.

           In case you thought I forgot about complementing CLX with a SEX
           (Set X mask) instruction, I didn't.  A method for setting the X
           bit is not documented, although there are at least two known
           methods of setting the X bit once cleared.  Both are relatively
           complicated and not used frequently enough to justify making a
           built-in instruction for them.  (Besides, it keeps the assembler
           rated PG-13.)

           WAIT was added because WAI by itself will "hang" the CPU (until
           Reset or XIRQ) if the I bit is accidentally left set.  WAIT, just
           like its homonymous instruction in the 6805, will first enable
           interrupts and then enter the wait phase, which is what most
           circumstances require.

           Due to their size and speed, LBRA/LBSR are not meant for casual 
           use.  They could be useful when (1) you absolutely *must* use
           relocatable code, and (2) your code branches from one "side" of
           the program to the "other" where using a series of intermediate
           BRA "hooks" is too messy or more costly in terms of size and/or
           speed than the two macros offered by ASM11.  I'm so against using
           these without careful thinking that I had originally planned to
           leave these two extras undocumented, but then again what good is
           it to have them only for my own use?  However, let me stress this
           one more time, using these macros casually or in place of JMP/JSR
           is definetely wrong, but it's you writing the program, so what do
           I care?  (They do, however, make wonderful toys for confusing a
           bit someone trying to disassemble your code, it will take them a
           while to figure out what happens.)

           Both LBRA and LBSR preserve all CCR flags and all unrelated 
           registers, so they are totally transparent (and behave just like 
           the real thing, only much slower and with possible interruptions, 
           real instruction are atomic -- non-interruptable).  They do use
           quite a few bytes on the stack to do all this, though.  I don't
           claim to have the best possible (in terms of size and speed)
           coding for these two, if you come up with a better one, let me
           know.

           In case you were wondering, there is no need for a "long" version
           of the remaining branch instructions, such as BEQ, etc.  Only the
           LBRA and LBSR are enough to accommodate every possible situation.
           For example, a LBEQ isn't required because to do the equivalent
           of:

           ...
                    LBEQ      FAR_AWAY
           ...

           one could do this:

           ...
                    BNE       Local.1
                    LBRA      FAR_AWAY
           Local.1  EQU       *
           ...

           Similarly for the rest (I'm sure you got the idea).


   Frequently used options may be "permanently" saved inside the ASM11.EXE
    file.  Use the -W option to save the state of all switches appearing
    before the -W switch while leaving the rest unchanged.  The word
    "permanently" is quoted because you may the -W option as often as you
    like.

   You are given the option to change the S19 record length to any length 
    from 12 (minimum possible for one byte per record) to 250 (maximum 
    allowed by this program), use the -Rn option, replacing n with the actual 
    number desired.  Note that the number must be even (exactly divisible by 
    2) because odd sizes do not make correct S19 records.  You will not be 
    allowed to enter an invalid record length, anyway.  The default S19 
    record length is 74 which holds 32 bytes of code/data [ie., (74-10)/2].  
    Incidentally, most assemblers use either 74 or 42.

   You may also use another variation of the -R option to specify a new
    default source filename extension.  The default for this option is .ASM
    but you can change it to any valid extension (ie., any except for blank,
    S19, LST, MAP, ERR, and SYM).  You should use the -W option somewhere
    *after* the -R.ext option to save the new default extension inside the
    ASM11.EXE.  If you only need to specify a different extension
    temporarily, you should do so directly at the command line (eg. ASM11
    .A11 to assemble files matching *.A11 in the current directory).  To make
    the .A11 permanent so you no longer have to type it, do ASM11 -R.A11 -W
    and from then on typing ASM11 . will match *.A11.

    By the way, please note that listfiles have only one requirement.  That
    the filename mask and/or path be the very first non-blank entity.  After
    that there may be comments or whatever else you like.  Incidentally, most
    of the little utilities I've written from time to time, produce output
    that can be directly used as a listfile (eg. WHERE, FD, etc.).

   Another option is -Tn, where n is the actual number of the tab size, for
    setting both the output listing tab size and, more importantly, the
    parsed input lines so that strings with embedded tabs will expand
    correctly.  The default for this option is 8 (which is the default tab
    size for most editors).  If you know a source file uses different tab
    size (or if you have set your own editor to different tab stops and
    enabled saving with tabs), use this switch to match it to the source
    file's tab size.  To make it permanent, just like with all other options,
    use the -W command.  Note, however, that if the file contains the
    $TABSIZE directive, this option will be overriden for lines following the
    embedded directive.  The embedded $TABSIZE will only have effect for the
    current main file and all its included files (until a new one is
    encountered).  When a new main file is started, the tab size will again
    default to the one set with the -Tn option, and so on.

   Addressing modes are invoked as follows:
    Mode       Prefix    Examples
               
    Immediate    #       LDX #TABLE
    Direct     @ or <    LDX @COUNTER   LDX <COUNTER
    Extended     >       LDX >COUNTER
    Auto Dir/Ext None    LDX COUNTER (if COUNTER < $100 use DIRECT, else EXT)
    X indexed            LDA ,X    LDA 0,X   LDA OFFSET,X
    Y indexed            LDA ,Y    LDA 0,Y   LDA OFFSET+3,Y

    Beginning with version 1.27B, this assembler automatically attempts to
    use direct mode when possible (that is, when the resulting address has a
    most significant byte of 0).  It will be successful if no forward
    references are used, otherwise, it will use extended addressing.  You
    should explicitly define direct mode addressing by using the @ or <
    prefix or extended addressing mode using the > prefix for situations
    where you want to override the assembler's automatic choice of mode.

    Forward references will force extended addressing in PASS1, but in case
    that choice proves wrong, PASS2 will produce appropriate warning messages
    to aid you so that you may add the < prefix to explicitly use direct
    mode.  In no case should there be phasing errors because of auto-direct
    mode detection.

   BSET/BCLR and BRSET/BRCLR instructions require commas between all
    operands.  This is one common conversion you may have to do when porting
    from another assembler that uses spaces (such as Mot's AS11) or other
    characters.  You will be assisted by appropriate messages.

    If you get a warning about "extra operand ignored" check to make sure you
    either haven't left the R out of the BRCLR/BRSET and typed BCLR/BSET
    instead, or that you actually haven't supplied a branch address to
    BCLR/BSET instruction (perhaps due to cutting and pasting from another
    line).

    All of the following examples are valid Bit instructions:

               BSET      ,X,#$80
               BRCLR     1,Y,3,*
               BRSET     2,Y,#128,$
               BCLR      0,X,1
               BSET      Flags,mskDirection
               BRCLR     Flags,x,mskDirection,LeftRotate
               BRSET     Flags,x,mskDirection|mskRightAllowed,RightRotate

    Note that the use of # in the mask is optional (and in fact is accepted
    only to make it compatible to a wider range of assemblers).

    (By the way, a BRCLR or BRSET instruction with a zero mask will always
    branch, ie., it's equivalent to a BRA instruction, only twice the size
    and half the speed.  On the other hand, a single BCLR or BSET instruction
    with a zero mask is equivalent both in size and speed to three
    consecutive NOPs.  This may not apply to special registers where a
    read-modify-write operation actually does something even when no value
    changes.)

   Pseudo-instructions that are supported are:
    ORG        for specifying the ORiGinating address of a code/data section
    RMB        for Reserving *unitialized* Memory Bytes
    DS         for Defining Storage (the same as RMB)
    FCB        for Forming Constant Bytes (numeric values or strings)
    FCC        for Forming Constant Characters (actually same as FCB)
    DB         for Data Byte definitions (yet another alias for FCB)
    FDB        for Forming Double Bytes
    DW         for Data Word definitions (the same as FDB)
    END        is supplied mainly for compatibility.  If used, however, with
               any label (or expression) next to it, the S9 record produced
               will have the address indicated by END's argument.  If 
               multiple END statements are used, the last one's value will be 
               used.  If the last one has no label next to it, or no END is 
               ever used in the program, the S9 will point to zero address.

    FCB, FCC, DB, FDB, and DW accept multiple operands separated from one
    another by single commas.  All others, depending, expect either a single
    or no operand (eg., END).  Each may be preceded by a label, except for
    ORG and END in which case the label is ignored and you get a warning.

    EQUs, ORGs, and RMBs may not refer forward (actually RMBs may do so, but
    pay much attention to this one warning and check your listing for
    correctness).  All others may do so, although in some instances where
    there is a phasing value difference (a different value for the same
    symbol between PASS1 and PASS2), you will get a warning.  Normally, you
    should ignore such warnings (if they don't show along with other warnings
    or errors), as the resulting code will be correct using the most current
    value.  You can always avoid such conditions but eliminating unnecessary
    forward references.

   The default number base is 10.  As a default, it cannot be changed to
    anything else.  Of course, you may specify hex values by using the $
    prefix, binary values with the % prefix, and decimal values with the !
    prefix.  (Although decimal is the default, the ! is provided for
    compatibility with some other assemblers).

   Any line beginning with any number of spaces or tabs followed by a * or ; 
    is a comments line.  Anything other than a comment and a space on the
    very first character of a line (or an assembler directive starting with $
    or #) indicates a probable symbol definition (pending symbol syntax
    check).  Non-labeled instructions must have at least a tab or a space in
    the beginning of the line.  Comments that follow instructions may or may
    not start with the ; character.  Although this makes it a bit more
    flexible than requiring a ; for comments, it also poses a few threats.
    For example, the source line:

               CLRA      COUNT     ;comment line

    will not cause any errors, since CLRA is an inherent addressing mode 
    instruction that does not need any operands and, thus, COUNT is 
    considered the beginning of the comment.  Something like this actually 
    appears in a file called AMOTOR.ASM from Mot's web site.  The reader may 
    misread this as "CLR COUNT ;comment line" and since the assembler won't 
    give any errors or warnings, s/he may have a hard time figuring out
    what's wrong.

   Operators allowed are:
    Operator   Function
       
       +       Addition.
       -       Subtraction.
       *       Multiplication.  Note that * is also used to specify the
                                current address, eg. START EQU *
                                To avoid ambiguous expressions using the *
                                (current PC value) and * (multiplication
                                operator), change the * (current PC) to its
                                alias $, eg.  START EQU $*2 (a nonsense
                                statement that is only meant to illustrate
                                the point).
       /       Integer division, remainder is ignored.
       \       Modulus.         Division remainder.
       >       Shift right.     SPEED > 2 shifts the value of SPEED to the
                                right by 2, effectively dividing SPEED by 4.
       <       Shift left.      SPEED < MULT shifts the value of SPEED to the
                                left by as many places as indicated by the
                                value of MULT, effectively multiplying SPEED
                                by 2^MULT.
       &       Bitwise AND      $81 & $0F will produce $01
       |       Bitwise OR       $81 | $0F will produce $8F
       ^       Bitwise XOR      $81 ^ $0F will produce $8E
       ~       Swap Hi/Lo       ~$1234 will produce $3412  (PRECEDENCE)
       [       Lo 8-bits        [$1234 will produce $34    (PRECEDENCE)
       ]       Hi 8-bits        ]$1234 will produce $12    (PRECEDENCE)

    NOTE: Although some of the examples above are shown with spaces for 
          clarity, actual code should not include spaces (except within 
          strings or character constants).

    Operations are carried out from left to right with NO special precedence, 
    except for the ones marked so.  This means, that addition and 
    multiplication have equal rights.  I know this is a little bit unorthodox 
    (although AS11 and other assemblers do the same, so I'm not all alone
    here).  Also, there is no way to change precedence by parenthesizing,
    because parentheses are currently not allowed (and if you use them you
    will get an error).  The new (v1.15) operators ~, [, and ] do not act on
    two operands but only on the one which follows them.  So, you could say
    1+3*[$1234 to have 1+3*$34 evaluated.  Of course, you could use symbols
    rather than numbers.  Note that [ comes right before the number or symbol
    (eg., [VALUE) but, in case of numbers, before the $ which is the symbol
    for hex and is part of the number.

    There are ways around the limitations imposed by lack of precedence.  Use
    intermediate symbols if necessary, or rearrange (when possible) the order
    in which operations are to be performed.

    Also, remember to examine expressions carefully when porting from another
    assembler (or simply assembling someone else's code you don't know for
    which assembler it was written originally) to assure they evaluate the
    same with this one, and that all operators (especially the less common
    ones) perform the exact same functions.

    Example              Evaluates to
                  
    1. LDA #3+4*2        3 + 4 = 7 * 2 = 14

    2. TEMP EQU 4*2      8              ;One way to give precedence to *
       LDA #3+TEMP       3 + TEMP = 11

    3. LDA #4*2+3        11             ;Another way to give precedence to *

    One "neat" use for the [ is shown below:

    REGS       equ       $1000
    PORTB      equ       $1004
               ldx       #REGS
               lda       PORTB               One way to load PORTB
               lda       PORTB-REGS,x        A second way to load PORTB
               lda       [PORTB,x            A third way to load PORTB

    You could also use the simpler:

               lda       PORTB,x             A fourth way to load PORTB

    and get the correct code produced, but you would also get a warning
    because of the attempted use of a 16-bit operand in place of the expected
    8-bit one.  The [ provides a more elegant (warning-free) solution.

    Both of the above save you the need to define two symbols, PORTB and
    _PORTB (for example), the first with the 16-bit value and the second with
    the 8-bit $1000-based offset value.  Now, you only need to define the
    16-bit one and depending on what's required use either the lower ([) or
    higher (]) 8-bits.

   Strings and character constants may be delimited by (placed within)
    single ('), double ("), or back (`) quotes.  However, what starts a
    string must also end it.  For example, the following are all valid
    strings:

    'Hello World!'
    "Hello again"
    `"Goodbye now" is an embedded string`

    Please note that some other assemblers use the / character as a delimiter 
    (or any other character).  This assembler has specific string/character 
    constant delimiters, and it will try to do a division (or other funny 
    things) when an / (or other character) is encountered.  This is likely to 
    lead to "Division by zero" or other misleading errors.

    Also, please note that instructions such as LDX #'00' will do the "right"
    thing, ie., LDX #$3030, while LDX #'0' will act as LDX #$0030. Also, a
    LDA #'00' will act as LDA #'0' (ie., LDA #$30) but will produce a warning
    about using a 16-bit operand with an 8-bit instruction.

    What is a bit unusual is that you can also do LDX '00' (with the # sign
    missing for extended mode) which will be treated as LDX $3030.  You can
    use any of the operators with string constants, eg. to convert Register
    A's value to uppercase, you could write:

    Uppercase       cmpa      #'a'
                    blo       Uppercase.Exit
                    cmpa      #'z'
                    bhi       Uppercase.Exit
                    suba      #'a'-'A'
    Uppercase.Exit  rts

    If you don't put the ending delimiter, your string will most likely be
    defined alright, unless there are operators, spaces, or comments
    following.  For example,

                    lda       #'a

    will give you a warning about an unclosed string but will produce the
    correct code.  However,

                    lda       #'a            this is a comment

    will not produce the expected operand, it will probably produce a space
    value ($20)!

    Some other things you can do with string constants:

                    lda       'A',x
                    rmb       'Z'-'A'+1

   Labels and symbols may begin with an alphabetic character (A through Z), 
    or a dot (.), or an underscore (_).  After that they may have any 
    combination of characters (special and alphanumeric), except for space or 
    any of the operators (such as *, -, +, [, ~) or string delimiters.  If 
    the last character is a colon (:) it will not become part of the symbol, 
    for compatibility with other assemblers.  However, if there are two (or 
    more) colons at the end, one of them will be ignored and the others will 
    become part of the symbol.  Although there aren't any strict rules for 
    labels at the moment, try not to get too wild about using special
    characters, as this will render your programs incompatible with most
    other assemblers, simulators, and emulators.

    You can use anything for a symbol, even if it's the same as a mnemonic or
    pseudo-instruction, eg., the following is perfectly legal code of
    perfectly bad programming style:

          bra       bra       jmp       jmp
          jmp       jmp       bra       bra
    Label                             
    Instruction                   
    Branch/Jump address          
    Comment 

    The maximum length for a symbol/label is 19 characters.  Although you may
    define longer symbols for the sake of readability, only the first 19
    characters are significant, and if they collide with another symbol's
    first 19 characters, a "duplicate symbol" message will be displayed.
    Please note that versions prior to 1.08Beta accepted upto 30 character
    long symbols but that luxury had to go too soon.  The reduction was done
    for two reasons: to preserve heap memory for larger symbol tables used in
    larger programs, and (finally, the real reason) to be compatible with P&E
    map files that appear not to handle longer than 19 character symbols (I
    may be wrong on this, but although SIM11E appeared not to get confused
    with longer symbols, SHOWMAP gave some wierd displays with longer ones,
    and since I don't know the official symbol size for P&E Map files, better
    be safe than sorry).

   INCLUDE files are also supported.  You may use the $INCLUDE (or #INCLUDE)
    directive, followed by the filename to include (with as many spaces in
    between the INCLUDE and the filename as you like), followed by whatever
    comments you like.  The filename may be plain or embedded in any of the
    allowed string delimiters.  Any path you give will be relative to the
    directory of the *main* file processed even for nested includes that are
    located in some totally different directory and/or drive.  For example,

    FILE1.ASM (in directory C:\ASM\68HC11\LCD)
    ---------
          $INCLUDE ../LCD.INC
          ...

    LCD.INC (in directory C:\ASM\68HC11)
    -------
          $INCLUDE ../EQUATES.INC
          ...

    EQUATES.INC should be in the *same* directory as LCD.INC for this to work
    because the ../EQUATES.INC in LCD.INC is relative to FILE1.ASM's, not
    LCD.INC's location.

    Of course, to avoid problems with relative paths pointing the wrong
    place, the path could be absolute, ie., contain the full path of the file
    (eg., C:/ASM/LCD.INC).  Both forward and backward slashes may be used.

    There is no default INCLUDE extension.  Also, INCLUDEd filename
    extensions are not restricted.  Although I don't see why you must do so,
    this will allow you to use any of the forbidden extensions by setting up
    a file that includes the one(s) with the illegal extension(s).  Be
    forewarned, you may be looking for trouble, and you will most likely lose
    your source code if for example you try to assemble an include with an
    illegal extension (such as .LST) that is located in the same directory as
    the main file!  INCLUDEs with illegal extensions should only be used for
    files outside the main file's directory.

   You may want to turn off certain portions of your code in the listing
    output (eg., INCLUDEd equates).  You can do this by using the $LISTOFF
    (to turn off) and $LISTON (to turn back on) directives within your code,
    where appropriate.  This directive is initially ON for every main file.
    An example follows:

    ...
    $LISTOFF                       ;Turn listing off
    $INCLUDE EQUATES.INC           ;General symbol definitions
    $LISTON                        ;Turn listing back on
    ...

   Those of you who make use of the generated MAP files will find the 
    directives $MAPON and $MAPOFF handy.  Rather than generating detailed 
    line number information in the MAP file for all executable lines of your 
    code, you may want to turn off certain portions you know work well, so 
    that when you do SS to step over them, they will be executed as a single 
    instruction.  (This in a way overcomes AEVM11's and SIM11x's inability to 
    step over an instruction via a command, they will only step into it.) You
    can turn mapping off for whole files or single commonly used routines
    that you have traced a zillion times and don't need to, anymore.  This
    directive is initially ON for every main file.  For example:

    ...
                    LDA  CHAR
                    BSR  UPPERCASE
                    STA  ,X
    ...
                    $MAPOFF                  Turn off source-level map info
    Uppercase       cmpa      #'a'
                    blo       Uppercase.Exit
                    cmpa      #'z'
                    bhi       Uppercase.Exit
                    suba      #'a'-'A'
    Uppercase.Exit  rts
                    $MAPON                   Turn on source-level map info
    ...
                    ORG       $F800
                    $MAPOFF
                    $INCLUDE OS11.MOD        Fully-tested Operating System
                    $MAPON
    ...

    Turning the detail source-level info off does not affect symbols defined 
    within those sections of code (so turning map info off for a section of 
    EQU statements does not do any good, it is only good for code).  It also 
    provides a means of reducing the symbol table size for larger programs, 
    so if you should ever get an error saying that there was not enough heap 
    memory (memory used for the symbol table), turn off "mapping" for those 
    portions of your code that aren't really necessary to trace one line at a 
    time.  It hasn't occurred to me so far to run out of heap memory, but 
    your programs may be more symbol rich than most.  With detail source-line 
    map info turned on, the maximum program size will be approximately 11000 
    instructions.  With no source-level info, there should be no practical
    limit.

   The $TABSIZE is one method for the programmer to force the tab size of
    his/her source code to a specified number (any positive integer
    following, eg., $TABSIZE 10).  This makes it possible to distribute code
    to people who have different tab settings in their copy of ASM11, and
    still have them get the listing formatted correctly, and more
    importantly, code string data.  $TABSIZE will always override whatever
    value the user has given to the -Tn switch.  It should normally be one of
    the first (if not the very first) lines in the program, to avoid the
    lines before it to be formatted with the default tab setting.  If you
    save your files with tabs, it should definetely be included before any
    string data is encountered, or you could get wrong data produced (with
    the wrong number of spaces).  Be careful with included files that may
    change tabsize to something else, since tabsize is reset to its -Tn
    default only at the beginning of a new main file.

   $CASEON and $CASEOFF control the -C switch from within the source.  The
    initial setting for each main file is taken from -C switch.  Normally,
    you should set this at the beginning of the source so that no matter what
    the current default is for -C, your code will assemble correctly every
    time.

   $EXTRAON and $EXTRAOFF control the -X switch from within the source.  The
    initial setting for each main file is taken from -X switch.  Normally,
    you should set this at the beginning of the source so that no matter what
    the current default is for -X, your code will assemble correctly every
    time.

   $S19FLUSH causes the S19 file to break to a new line regardless of 
    whether the next address is in sequence or not.  Useful for comparison of 
    S19 files with those of other assemblers that incorrectly break the S19 
    when encountering an ORG statement, and for by-passing problems with some
    loaders that don't do a very good job.  Multiple consecutive $S19FLUSH
    directives are treated as one.

   $OPTRTSON (was OPTRTS but was renamed to OPTRTSON for consistency with 
    other directives) and OPTRTSOFF (new) stand for OPTimize RTS.  This 
    directive's command-line equivalent is -RTS and is initially OFF for 
    every main file.  Its use controls the display of the warning regarding 
    the possible optimization with JSR/BSR followed by unlabeled RTS, and is 
    intended for the last phase in programming, where we might want to 
    optimize "JSR/BSR followed by unlabeled RTS" sequences to their 
    equivalent JMP/BRA.  The $OPTRTSON directive will give us warnings for 
    each unlabeled RTS that *immediately* follows either a JSR or a BSR 
    instruction.  A blank line or anything else between the RTS and the last 
    JSR/BSR line will cause no warning.  A labeled RTS again will cause no 
    warning because the label could be used to branch directly to the RTS 
    from some other part of the program, so an optimization wouldn't be 
    possible (unless the label is never actually utilized, but ASM11 will not 
    check for that condition).  Some programs use tricks based on the PC 
    value saved on the stack during a JSR or BSR.  These programs should not 
    be optimized because the called subroutine will not work correctly.  If 
    you leave a blank line between the JSR/BSR and the RTS, the assembler 
    will not produce a warning and save you from inadvertedly replacing the 
    sequence with JMP/BRA.  You could also turn off this warning, around
    sections of code you shouldn't optimize, using the OPTRTSOFF directive.

   $OPTRELON and $OPTRELOFF control the display of the warning regarding the
    use of BRA/BSR for JMP/JSR when possible.  The command-line equivalent is
    -REL.  Initially (if you haven't saved your own defaults) this option is
    ON.  Normally, you would want to leave this option on except perhaps for 
    cases where you have a list of JMPs that you use based on indexing using 
    some calculation.  This would not make it easy if some of the entries 
    have JMPs and others BRAs.  Use the $OPTRELOFF to turn off this warning 
    just before the table, and re-enable the warning right after it.

   Conditional assembly is supported beginning with ver. 1.33B.  Conditional
    directives cause portions of your code to assemble or not based on
    whether a symbol is (or symbols in an expression are) defined, undefined,
    zero, non-zero, or if two expressions give true or false comparison based
    on the comparator used.  If used properly, they can be very powerful.
    Accepted conditional directives are listed below:

    Conditional     Becomes True when

    $IFDEF expr     All symbols in expr are defined
    $IFNDEF expr    Any one symbol in expr is not defined
    $IFZ expr       All symbols defined and expression evaluates to zero
    $IFNZ expr      All symbols defined and expression evaluates to non-zero
    $IF e1 COMP e2  COMP may be =, <>, <, >, <=, >= All symbols defined and
                    e1 COMP e2 is true based on COMParator used.
    $ELSE           Last unmatched IFx was False
    $ENDIF          Closes the last unmatched IFx used

    Nested conditionals are allowed.  Each ELSE is always matched to the last 
    unmatched IFx and similarly for ENDIF.  ELSE and ENDIF do not take 
    arguments.  The remaining take as argument an expression (IF needs two 
    expressions around a comparator), just like any other expression you use 
    in your program.  No comparator operators are allowed, just an expression 
    (except in the case of IF where a comparator is required between the two 
    expressions).  IF, IFZ and IFNZ produce warnings if the symbols in the 
    following expression(s) are not yet defined, and in that case always 
    evaluate to False (so, in such cases if there is an ELSE following, the 
    ELSE is always taken).  ELSE is optional.  ENDIF is required unless the 
    end is also the end of the main file (in which case it can be left out).  
    IFDEF and IFNDEF do not produce warnings for undefined symbols (that's 
    what they are supposed to check), the other IFxxx directives issue 
    warnings for undefined symbols since they are meant to check values not 
    presence (but you may wish to combine the two functions in one and ignore 
    the warning).

    Note that expressions are made of symbols used in the program itself (or 
    simply defined but not used).  There is no way to define a symbol only 
    for the purposes of conditional assembly, as you can do with some other 
    assemblers (eg., some that use directives like $SET or $DEFINE).  You
    may, however, have the same effect by defining your symbols using regular
    assembler syntax (eg., DEBUG EQU 1).  A symbol on a line by itself will
    also define it (since IFDEF and IFNDEF do not care about the value of a
    symbol, no EQU is necessary).  For example:

    DEBUG ;Define the symbol DEBUG (note the needed ; for the comments)
    ...
    $IFDEF DEBUG
    ...
    $ENDIF

    If you want to test for a specific value, you may try something like
    this:

    $IFZ  ROM-$F800
    or
    $IF   ROM = $F800

    These will be true if ROM is equal to $F800, false otherwise.

    NOTE the required spaces in the IF which separates expression1 (ROM) from
    comparator (=) from expression2 ($F800).  In the IFZ there is no space
    around minus (-) because the whole thing is a single expression.

    Another example (both symbols must be defined, or else the ELSE is
    taken):

    $IFDEF DEBUG+MCU711E9
    ...
    $ELSE
    ...
    $ENDIF

    Do not use comments next to those IFxxx directives that expect arguments.

    Symbols are defined by the program itself, so even START LDS #$1FF will
    define START with the value of whatever address it happens to fall on.
    Then you can say:

    $ifdef START
    ...
    $else
    ...
    $endif

    Expressions used in conditional assembly are of exactly the same format
    as those used in normal assembly language.  For example, you could say:

    $IF ROM+$1000 > RAM_TOP-VECTORS
    ...
      $IF * > ROM
      ...
      $ELSE
      ...
      $ENDIF
    ...
    $ENDIF

    Note that conditional directives (but not code or other directives in
    between) are checked even when conditions are false.  This helps the
    assembler to correctly produce errors if there are mismatched nested ELSE
    or ENDIF directives regardless of the higher level condition being true
    or false.  So, even for a conditional branch that will never be taken,
    the IF .. ELSE .. ENDIF constructs should be correct (all IF, optional
    ELSE, ENDIF matching).

    Also, in the listing produced, sections of code between conditional 
    directives that evaluate to False, will not be shown (as if the LISTOFF 
    directive had been used) regardless of the current LISTON/LISTOFF
    setting.  The listing file will show only code and directives recognized
    as a result of conditionals evaluating to true.

    One easy way to mark a whole section of a program as comments is to use 
    the $IFDEF directive with no operand.  This will always evaluate to False 
    (because a null symbol name can never be defined), and the enclosed (to
    the matching $ENDIF) section will be ignored.

    If the end-of-file is reached before you close a conditional directive 
    with $ENDIF you will not get any error or warning messages.  It will 
    work, however, as expected.  The End-Of-File will automatically close any 
    open IFxxx directives (only for main files, not INCLUDEd ones).

    Finally, all comparisons are based on 16-bit unsigned words.

   The newly (ver. 1.33B) added directives $WARNING and $ERROR allow the
    programmer to induce warnings and/or errors wherever s/he pleases.  The
    message to be displayed follows the directive by as many spaces apart as
    desired (leading spaces are trimmed, anyway).  These are often useful
    with conditional assembly to alert to actions taken (normally with a
    WARNING) or serious problems resulting from a condition taking a
    different path than originally planned (normally an ERROR).  Example
    usage:

    ...
    $if ROM < $D000
      $warning This program will not fit a 711E9 internal eprom
    $else
      $if ROM >= $F800
        $error The area from $F800 to $FFBF is reserved for OS11
      $endif
    $endif
    ...

    or something like the following IF at the end of a "talker" program that
    must load in RAM:

               org       $0
    Start      equ       *
    ... more code here ...

    $ifdef MCU811E2
      $if *-Start > 256
        $fatal The code will not fit internal RAM
      $endif
    $else
      $if *-Start > 512
        $fatal The code will not fit internal RAM
      $endif
    $endif

    Yet another directive is FATAL (see above example).  This is similar to
    ERROR but also causes a complete halt of the assembler.  Added in v1.37B,
    this directive is useful for conditionals that have to decide whether
    further compilation is possible or not.  For example:

    $IFDEF MCU711E9
      $IFDEF MCU811E2
        $WARNING MCU711E9 and MCU811E2 are both defined (defaulting to 711E9)
      $ENDIF
      $INCLUDE 711E9.INC
    $ELSE
      $IFDEF MCU811E2
        $INCLUDE 811E2.INC
      $ELSE
        $FATAL You must define either MCU711E9 or MCU811E2
      $ENDIF
    $ENDIF

    In the above example, if the programmer has forgotten to define either
    one of those symbols, the program will not be assembled further.  If you
    use an ERROR directive instead, the assembler will continue assembling
    but since neither INCLUDE has been processed, very likely there will be
    too many errors/warnings produced.  To avoid unnecessary errors/warnings,
    the programmer may choose to use FATAL instead of ERROR.  Note, however,
    that $FATAL will halt the assembler completely, not only for the current
    file.  So, if you were assembling a batch of files, the remaining files
    will not be assembled at all.

    Case sensitivity also affects symbols used with conditional directives.

    A v1.46 added directive is MESSAGE.  It works similar to WARNING but does 
    not increment the warnings counter not does it show in any error files.  
    It's meant for simply informing the user about something.

   MACROs are not supported.  However, some frequently used macros, such as
    PSHD are built-in and are activated when the X option is in the ON state.

CONVERSION PROCESS:

  Although ASM11 is a bit more forgiving with syntax than other assemblers,
  you should note the following when porting your source code to it.

  To convert source code to this assembler's likes, you should normally do
  the following, although this is based heavily on the assembler for which
  the source was originally written.  I have based my suggestions on AS11 (by
  Mot), IASM11 (by P&E), and ASM(11) by Verschueren and Taphoorn (I think
  this is also called VACS, not sure).  This is not necessarily a complete
  listing of what you must do to convert your source, just what I could think
  off the top of my head.  Also, these three assemblers were not chosen for
  any particular reason, they just happened to be the ones I knew of at the
  time I wrote ASM11.  Since then, I have tried a few more, and they all seem
  to follow the same general guidelines.

   For any of them (and others):

     Not a requirement, but you could combine all related consecutive FCB,
      FCC, and DB pseudo-instructions (even when they are mixed), since they
      are treated the same by ASM11.  This will often make your source code
      more readable and compact.

     Not a requirement, but you could recognize instruction sequences that
      match one of the extra instructions provided by ASM11 and replace them
      accordingly.

     Remove (or comment out) all assembler directives, listing formatters,
      etc. not recognized in the same way (or at all) by ASM11 or, where
      possible, replace them with ASM11's equivalents.  Of course, you should
      make sure the code will behave as it should.

     Symbol/Label length is 19 characters in ASM11.  Adjust your code
      accordingly if symbols used were longer than 19 or than what the
      original assembler allowed.  For example, IASM11 allows up to 16
      characters.  If two labels were defined of 19 characters with the first
      16 being the same but the remaining 3 being different, IASM11 would
      treat them the same, so a branch to either one would end up the same
      place.  However in ASM11, the two will be different labels, possibly
      one or both of them will give an error as being undefined.

     Make sure some of the not-so-common operators accepted by ASM11 (such
      as [ or ^) aren't used in a different context in the original source
      since the assembler for which that source was written could have
      different meanings for those very same non-standard operators.

     In ASM11, currently, the colon (:) is a valid symbol character,
      although when found at the end, it is removed for compatibility.
      However, some assemblers (IASM11 comes to mind) will consider the : as
      the end of the symbols, so writing "ABC:CLRA" (with no space between
      the : and C) is the symbol ABC followed by the instruction CLRA.  Well,
      not in ASM11.  ASM11 will read this as symbol ABC:CLRA with no opcode
      following.  This is actually one way of defining a symbol as EQU *.
      You won't get errors or warnings for this but your code will not do the
      same.  Remember that for ASM11, space IS important between label,
      opcode, operand, and comment (but should not exist within each of
      those, except in the case of string data)!

   For IASM11:

     Make sure all assembler directives begin with either # or $ but not a 
      dot (if you intend to leave them in the source).  Dots are valid symbol 
      beginning characters in ASM11 but not in IASM11, so a directive 
      .INCLUDE will attempt to define a symbol by the name .INCLUDE and give 
      you errors (since it most likely will be followed by a filename).

     If there are any $MACROs defined, comment them out by putting ; or *
      infront of each of the lines that define them.  Next, find each
      occurrence of the macro being used in the source file and replace with
      the corresponding instructions.  Note that some frequently used macros
      are PSHD and PULD which are recognized by ASM11 with the -X+ option.
      You would not have to replace those with the corresponding
      instructions, however, you should make sure they do exactly the same,
      since the author could have defined PSHD and PULD in reverse order
      which could produce different results in some cases.  The proper order
      is that used by ASM11 but people do write whichever way they like, so
      be careful in the conversion.

     If the $BASE 10T directive has been used at the top of the source (and
      nowhere else), skip this one.  Otherwise, you should add to all values
      that are plain numbers (ie., without radix indicator), the $ symbol
      infront of them to make them hex (because IASM11's default number base
      is 16).

     Make sure numbers don't end with Q, T, or H for binary, decimal, or hex
      but have the equivalent leading sign (ie., %, !, or $, although ! is
      optional).  If they are formatted with leading %, !, or $ instead,
      you're in luck; no change is needed.

     Expressions within { } may have to be rewritten.  Often, just removing
      the { } and any spaces between operands will fix the problem unless
      precedence rules give different results, in which case a rearrangement
      is needed.  The same goes for parenthesized expressions.

     You may either leave the ; for end of line comments, or remove them.
      However, do not get carried away and remove them from lines that
      contain nothing but the comment because in those cases the ; is
      required.

   For AS11:

     Put commas between all operands of Bit instructions, ie., BSET, BCLR,
      BRSET and BRCLR.

     Check string or character constant definitions so that they are 
      delimited with any of ' (single) " (double) or ` (back) quote but not /
      or any other character.

     Change all FCB #12 type statements to not include the # sign.  This
      assembler does not and will not support this syntax (it will produce a
      Syntax Error).

     Character constants should be treated as strings, ie., have both
      quotes.  So, change instructions like LDAA #'A to LDAA #'A'

     If I'm not mistaken AS11 understands LDA, LDB, CMPD, and some of those
      aliases, so if they have been used, rather than change them, just make
      sure you assemble with -X+ or $EXTRAON defined.

   For ASM(11):

     I haven't played with this one much, but from the little I did, I found
      out there isn't much you should change from a working program.  Only
      thing to be careful is that ASM(11) labels do not have to start on
      column 1 as in ASM11, so you should move them there if they are
      indented.

     This assembler seems to behave very similarly to ASM11 (but accepting a
      much stricter syntax), although as an assembler overall it does differ
      quite a bit.  In case this sounds oxymoronic, I mean that once your
      code assembles with ASM(11) it should be OK for ASM11, also (except for
      the special directives, etc).  ASM(11) seems to be very strict (almost
      punishing), eg., if you forget the END at the end of your code, you get
      an error, not a warning, etc.

MISCELLANEOUS:

   Remember that spaces are used to separate labels from instructions, and
    from operands, and from comments.  Don't leave any spaces inside
    expressions or data lists (such as FDB 1,2,3,4), or else, the ones after
    the first space will not be recognized and you will not receive a warning
    or error because they are viewed as comments.

   I have successfully assembled (and by successfully I don't mean simply
    getting no errors, but rather running the produced object code and making
    sure it runs as expected and, if needed, comparing the object files to
    those produced by the assembler the program was written for, originally)
    all of my own (pre-ASM11) source code, and many programs written by
    others (such as BUF34 and most sources found on Mot's web after minor
    conversions as described above to make them ASM11-compatible) and believe
    the software is highly predictable in its behavior.  As lack of luck
    would have it, none of them utilized the LSRD instruction, which was
    producing a wrong opcode value until version 1.11B.  Anyway, it was a
    good chance to re-check every single opcode by hand.

   The assembler returns a DOS errorlevel of zero when no errors have 
    occurred (regardless of warnings).  The errorlevel returned to the parent 
    program that called ASM11 (if not used from the command line, this would 
    normally be a batch file or an IDE) was actually the linenumber of the 
    first error in the last main file processed until version 1.46.  With 
    version 1.46 this code is changed to a more useful 5-code system where 0 
    means no errors, 1 means system error (such as disk failure), 2 means 
    Assembler Error, 3 means Assembler Warning, and 4 means Usage Screen/No 
    Assembly.  The reason for this change is that there only low-byte is used 
    by calling program in effect making it useless.  Also, line numbers in 
    the format $xx00 (in hex) would show as no error since the low-byte is 0.  
    The new method is more useful and guarantees error-trapping for all lines 
    (however, with no line number information).  Most programmer IDEs will
    catch this return code and report the existance of errors (based solely
    on the fact it is non-zero), but of course they won't know where or what
    kind the errors were.  If your IDE has such capability, assemble with -E+
    always, and make the IDE display the *.ERR file on failure (or leave -E-
    and, instead, use redirection to send errors to whatever file your IDE
    expects to contain them).  Some IDEs will automatically redirect standard
    output to whatever file they like.

   Anything that ASM11 displays on screen it does so through a new file
    handle it creates at startup that it associates to the screen.  This
    means that redirecting the screen display to a file isn't possible.
    Besides, because of the extra CRs used for keeping the line counter from
    scrolling, the resulting file would be a mess!  Only error messages may
    be redirected (in addition to creating *.ERR files, if the -E option is
    active).

   The # and $ symbols as the very first non-blank characters of a line 
    indicate an assembler directive.   Unrecognized directives will produce 
    warnings and will be viewed as comments.

   About the extra mnemonics: Some of them I just couldn't live without.
    Having worked with 6809 for many years, LDAA or STAB didn't "feel" right
    to me (it's a personal thing).

   If, for some reasons, you must make your code more compatible to other 
    assemblers, make sure, as a first step, you use the -X option in the OFF 
    state (-X-) when assembling to flag out all "accidental" uses of extra 
    instructions, then replace them with their standard equivalents.  If you 
    have embedded an $EXTRAON directive anywhere in your source, you should 
    remove that one also before checking with the -X- option because embedded 
    switches always override their command-line counterparts.

   You may find that trying to assemble code that assembles OK with ASM11 
    (with the -X- option) will *appear* to assemble OK with other assemblers.  
    However, if you intend to make your code compatible to as many assemblers 
    as possible (something I do for certain subroutines I wish to share with 
    others), I urge you to check each assembler's listing carefully because 
    it has been my experience that some assemblers out there don't produce 
    errors for what they can't understand, but simply assume what they like 
    (if you find I'm guilty of this also, please let me know, and I'll try to 
    fix it).  I could give numerous specific examples, but I do not wish to 
    be thought of as offending other people's work.  (By the way, don't 
    expect to make all programs compatible to all assemblers at the same 
    time, it's not possible).

VERSION HISTORY:  When reading the history, keep in mind that what's said for
                  any given version was written at the time that version was
                  prepared and, therefore, ASM11 may have been altered in a
                  following version and, thus, operate in a completely
                  different manner.  So, read the whole history (starting
                  perhaps from the end) to figure out what's the current
                  behavior.

  The whole project lasted about 3 months, working at it on and off, mostly 
  during my summer vacation (no, I don't have 3-month long vacations except 
  for periods of unemployment).

  1.00Alpha  Original.

  1.01Beta   Added CMPD extra for CPD equivalence.

             Added CLX to clear the X flag.

  1.02Beta   Allowed strings to be delimited by any of " ' or ` rather than
              just '. Note, however, that what starts a string must also end
              it.  No mixing of delimiters is allowed, or else there would be
              no point in having more than one.

  1.03Beta   Added listing creation capability (*.LST)

  1.04Beta   Made "Division by zero" errors appear only on PASS2.

             Changed RMBs to show both address and number of bytes in the
              listing.

             Changed all pseudo's values to display indented on column after
              address.

             Removed erratic value display from END pseudo-op.

             Added warning for not using DIRECT mode addressing where
              possible.  Please note that this particular warning will only
              appear in the *.ERR file.  This is because the assembler does
              not automatically use direct mode addressing but requires the
              use of the @ or < direct mode designators.  This will result in
              excessive amount of warning for this one reason when assembling
              certain files.  So, if you want to see where you may use direct 
              mode, turn on the *.ERR file with the -E+ option, assemble the 
              file(s), and have a look at the corresponding *.ERR file(s).  
              To make the warning(s) disappear, edit the source file and add 
              @ or < signs infront of the direct mode address symbols or
              values.

             Moved Warning about 16-bit operand with 8-bit instruction to 
              *.ERR file.  If you must see these warnings, turn on *.ERR
              production with the -E+ switch.  This move was done because 
              this warning is highly unlikely to lead to undesirable results 
              and it comes up quite often for certain programs.  (NOTE: This 
              change was reversed in a later version.)

  1.05Beta   Added even length S19 records.  Before this version, S19 
              records held one instruction's worth of code each making the 
              resulting file look jugged edged.

             Added cycle counts in *.LST files.

  1.06Beta   Added XGAB pseudo-instruction for swapping the A and B register 
              contents.  Quite a useful instruction, I'm surprised it wasn't
              part of the 68HC11 instruction set.

  1.07Beta   Added error on numbers greater than 16-bit, such as 65537.

             Added warning for having used JMP or JSR where a BRA or BSR
              would also work.  This helps you optimize your code by
              replacing JMP with BRA and JSR with BSR where appropriate.
              Note that you will not get a warning for direct mode JSRs since
              direct mode JSRs actually have better performance than BSRs,
              having the same instruction length (2 bytes) but being 1 cycle
              faster (5 instead of 6).

              Note that you should worry about this optimization near 
              completion of your program to avoid unnecessary changes back 
              and forth, as even a single command changing from direct to 
              extended mode or the reverse could influence the use of jumps 
              versus branches.

  1.08Beta   Changed phasing error values to display in hex (not decimal).  
              The decimal display was not intentional, I had just forgotten 
              to convert to hex.

             Added CMPX and CMPY extras (there already was a CMPD).

             Added symbol checking for operators inside symbols.

             Fixed deleting upon error or ESC of enabled files only as per
              documentation.

             Added warning for expressions that result in greater than
              16-bit numbers.

             Added warning for missing first operand in expression, except
              when the operator is either a + or - (unary operators).

             Moved warning about 8-bit and 16-bit instruction/operand
              mismatch to always display on the screen (not just the *.ERR
              file as was done in version 1.04Beta), and corrected for
              negative numbers.  Since this warning will not show up quite as
              much anymore, it was moved to display on the screen as well
              (reversing 1.04Beta change).  It used to display even for small
              negative values, such as -1 causing too many warnings when long
              tables with negative values were used, to mention one example.

             Shortened symbol length from 30 to 19 characters to preserve
              memory in favor of larger overall symbol tables and better P&E
              map file compatibility.

             Added recognition of < and > for DIRECT and EXTENDED addressing 
              mode overrides.  This was done for compatibility with other 
              assemblers, and because it's been a Mot standard for a long 
              time.  You no longer have to remove these from existing code.

  1.09Beta   Based on Mark Schultz's suggestion, I changed the command
              filename parser to accept any extension for source file names,
              with one restriction: extensions that are the same as those
              used for output files by ASM11 (ie., S19, LST, MAP, and ERR) as
              well as blank (no extension) will be ignored and the
              corresponding matched files will be skipped.

             Because of the above change, I also extended switch -R's
              functions to accept an extension to be used as default.  This
              option will make sense only if followed by -W to be made the
              new default, otherwise, you could simply give the new extension
              on the command line as part of the file specification.  The
              extension *must* start with a dot and be up to three characters
              long (standard DOS extensions).  Longer ones will be downsized
              to three characters.

             Added listing file header with file name, assembler version,
              date, and footer with end-of-listing marker.

             Removed warning for not using direct mode when extended was 
              explicitly declared (by prefixing with the > sign).

  1.10Beta   Optimized symbol table functions a bit to make overall 
              performance faster (the difference will only show on 
              multi-thousand line code).  Still needs a lot more optimization 
              (or better yet, a complete rewrite but I don't have the time 
              now, maybe after the summer).  This change unfortunately 
              introduced a nasty bug (but highly unlikely to show up), which
              was corrected in version 1.12B.

             Added symbol/label check for embedded string delimiters.

             Added CTRL-BREAK handler to exit more gracefully.  Pressing Esc
              now prints ** Cancelled ** message.

             Added option -EH (Errors Hidden) to send errors only to *.ERR
              file when -E+ is activated.  This option has not effect when
              -E- as errors will be displayed on the screen.

             Added code/data/image size counters at the end of the listing.
              Useful for knowing how much space you program needs, these
              counters display in decimal, hex, and KBs.

             Allowed multiple separate filename specs, eg. ASM11 file1 file2
              file3 ... where each file? is a mask with one or more elements
              as before, eg., ASM11 ,.A11 TEST OS11,OSTEST

             Fixed a little glitch with filename parsing that caused
              needless mismatch messages to show up.

  1.11Beta   Fixed operand label comparison for longer than 19-character
              labels to not produce an error unless there is really a
              collision on the first 19 characters only, as per
              documentation.

             Fixed MAJOR bug with LSRD instruction producing wrong opcode
              (05) instead of 04.  My sincere thanks to Mark Schultz for
              reporting this.

  1.12Beta   Fixed a nasty bug introduced with the optimization of version
              1.10B which, fortunately, would only show in small (mostly
              test-type) programs that had not even one symbol definition
              (highly unlikely for most programs).

             Added closing of files on ESC or error exit before erasing
              files to avoid lost clusters of incomplete files.  Although you
              could get lost clusters when doing a chkdsk afterwards, this
              bug was actually harmless (it's as if power was lost while
              writing to a file that was to be thrown away, anyway).

             When MAP creation is off, symbol table can now hold many more 
              real symbols (rather than source line information), thus, for 
              extremely symbol rich programs you won't run out of heap memory 
              (at the cost of not getting a MAP file which in any case for so 
              many symbols I have found that the programs that are supposed 
              to use them can't handle such large MAP files; actually they 
              can't handle many large MAP files long before ASM11 runs out of 
              heap memory.)  I haven't managed to run out of heap memory 
              while assembling actual programs, only with specifically
              enlarged test programs with several thousands of lines.

             Changed line number incrementing from every 50 to every 100
              lines (to reduce number of screen writes).

             Added & operator for bitwise AND operation.

             Added | operator for bitwise OR operation.

  1.13Beta   Added $INCLUDE file processing.  Upto 49 files may be included 
              (+1 the main file) for a total of 50 files.  Nesting level
              isn't relevant (ie., all 49 include statements could be one 
              inside the other), but if INCLUDEs are nested, the FILES 
              statement in CONFIG.SYS should hold an appropriate value so
              that DOS (not ASM11) can handle that many open files at the
              same time.  If they are not nested, the FILES statement can be
              as little as 10 or so (whatever value works for a single file
              assembly), since each INCLUDEd file will be closed before
              another one is opened.

             Added $MAPON and $MAPOFF directives.  These are used for
              turning source line number information on and off,
              respectively.  Turning map info off for certain sections of
              code you know to work well, allows you to step over them when
              doing the SS command.

             Added $LISTON and $LISTOFF directives.  These turn listing on
              and off, respectively.

  1.14Beta   Corrected use of quotes in INCLUDE files.  Some combinations
              didn't work right.  It worked OK if used without any quotes.

  1.15Beta   Corrected a small error reporting glitch that would show 
              irrelevant error messages on exit (not related to assembly, but 
              to system problems, such as Disk drive not ready) if there were 
              errors during assembly.  You see, I was returning the line 
              number if there were errors, but unfortunately, I did this 
              before checking for actual system errors, not after.  Fixed by 
              setting the line number exit code after DOS-type errors were 
              checked.  Anyway, for those who worried about something being 
              wrong with their system, most likely, there wasn't; the 
              messages were just playing jokes with you!

             Added ^ operator for bitwise XOR

             Changed message 'Operand ... could not be evaluated' to
              'Undefined symbol "..." or bad number' in an attempt to make it
              more meaningful.

             In listings, separated address word from first code/data word
              columns with a colon (:) to aid in quickly identifying the two.

             Changed ERR! to ERR* in the beginning of error messages.  The *
              character is more visible than the ! and makes it easier to
              stand out from a series of surrounding WRN messages.

             Added optional creation of *.SYM file.  This file is not sorted
              in any way, it is simply a dump of the internal symbol table
              with no header or other extra information.  This was done as a
              temporary solution to those who wish to have this information
              for use by tools that don't understand P&E map files, or
              utilities that can create other types of MAP files by using
              this info.  Symbols begin in column 1 and corresponding hex
              values in column 21.  You can sort the table with DOS sort (or
              my BSORT utility, using the command BSORT .SYM to sort by
              symbol name or BSORT .SYM -21 to sort by value).

             Added ~ operator to swap the high and low bytes of the
              immediately following value or symbol.  Note that is a unary
              operator that has precedence over standard operators, such as
              +, -, *, etc.  Example: LDX #~$1234 will do LDX #$3412

             Added [ operator to get the low byte of the immediately
              following value or symbol.  Note that this is a unary operator
              that has precedence over standard operators, such as +, -, *,
              etc.  Example: LDA #[$1234 will do LDA #$34

             Added ] operator to get the high byte of the immediately
              following value or symbol.  Note that this is a unary operator
              that has precedence over standard operators, such as +, -, *,
              etc.  Example: LDA #]$1234 will do LDA #$12

            NOTE: For obvious reasons (to me at least), ~, [, and ] may not
                  be used at the same time.  Only one of the three may be
                  used for any given value.  Using more than one doesn't make
                  sense, anyway, and having used one, the assembler will not
                  recognize the others, it will just look at them as
                  characters in a probable symbol or number, producing
                  appropriate errors.  [ and ] produce 8-bit values so they 
                  definitely don't go along with ~ which swaps the high and 
                  low bytes of a 16-bit value.  Furthermore, you either want 
                  the low or the high, not both, so [ and ] together are not
                  allowed.

  1.16Beta   Fixed the missing name problem from long include filenames or 
              paths.

             Added the -Tn switch for setting listing tab size to n.

             Because of the above switch, also added $TABSIZE directive to
              force a certain tab size from within the source, overriding
              whatever -Tn says.

             Added stdout redirection.  This will be used to send warning
              and error messages, regardless of the -E switch setting (or any
              other settings), to a file of your choosing by using standard
              DOS redirection.  The warnings and errors in this file will be
              for all files processed and each message will show the full
              path of the corresponding file that has the problem.  This was
              added to facilitate some smart IDEs to capture full filename,
              error message, and line number from any file they require.
              Note that redirection does not in any way affect the normal
              behavior of ASM11, in other words, it's completely transparent.

  1.17Beta   Added Tab expansion for source code before parsing to avoid
              problems with tabs inside strings that were put there by the
              editor.  This change means that if you actually want a tab in a
              string, you must break the string and add the value 9 (TAB).
              In other words, the TAB must be treated as you would a CR or LF
              character.  If, because of how tabs were handled until now, you
              had put tabs inside strings with the purpose of using them as
              tabs, you will have to modify your strings to explicitly
              declare tabs.  For comparison, AS11 will read tabs inside
              strings as actual tabs without expanding them first, like ASM11
              did until now.  However, this is not desirable, especially for
              tab sizes other than 8.

  1.18Beta   Removed possible comments on INCLUDE line (following the
              filename).  This used to disrupt the display of the filename a
              bit and would not recognize a filename if there was a dot in
              the comment (otherwise, it was not a problem).

             Added warning for using unlabeled EQUs.  Until now, an EQU
              without a label would be silently ignored.

             Fixed $TABSIZE to reset to its default value at the start of 
              each new main file processed.

             Re-enabled end-of-listing report and closing message even if
              the $LISTOFF directive was used last.

             Fixed problem with End-of-file include not being processed.

  1.19Beta   Added display of filename on first line in addition to every
              100 lines, so that even the smallest files will have their
              names displayed (albeit in a flash).

             Added $CASEON and $CASEOFF directives to control from within
              the source the setting of switch -C.  Normally you could give a
              $CASEOFF (or $CASEON) at the beginning of your source to make
              sure others assemble it correctly.  You may even turn on/off
              this setting within the same source, if you happen to borrow
              code from others, or simply need to use case-sensitive assembly
              only in a portion of your code.

             Added $EXTRAON and $EXTRAOFF directives to control from within
              the source the setting of switch -X.  Normally you could give a
              $EXTRAOFF (or $EXTRAON) at the beginning of your source to make
              sure others assemble it correctly.  You may even turn on/off
              this setting within the same source, if you happen to borrow
              code from others, or simply need to use the extra instructions
              only in a portion of your code.

             Made the Direct Mode warning (the one that only goes to the
              *.ERR) to also go the stdout redirected file.  This change was
              done to make previous documentation look correct :)

  1.20Beta   Corrected lack of error reporting on empty strings.

  1.21Beta   Added error for forward definitions on RMBs.

  1.22Beta   Of course, I had to forget to include the DS in doing v1.21B
              change, just to have to come up with a new version to fix that!

  1.23Beta   Fixed bug with Y indexed Bit instructions giving errors when
              they shouldn't.

  1.24Beta   Changed ERROR of version 1.21B/1.22B to a WARNING.  However,
              this warning should be taken seriously as in some cases it 
              indicates that wrong code has been produced.  The change to a 
              warning was done because in many situations, the code produced
              will be correct.

             Added SB2ASM11 utility for making SBasic output compatible to
              ASM11.

             Added source example MULTBOOT.ASM for re-burning OTPs.

  1.25Beta   Added LBRA and LBSR extra mnemonics (built-in macros).  These 
              will not show on the help screen because they are too big to 
              fit.  Please note that LBRA and LBSR translate to a relatively 
              long series of bytes that does not justify casual use.  They 
              are only meant to provide a means for making your code 
              relocatable (even if you have a widely spread loop that normal 
              branch instructions won't cover, etc.).  They should not be
              used whenever you get the ERROR message that advises you to use
              a jump instead of a branch.  If you still must use relative
              addressing, trying adding "jumper points" to your program.  Not
              officially released.

  1.26Beta   Optimized the code produced by the newly introduced macros,
              LBRA and LBSR.

  1.27Beta   Several internal changes that relate to symbol table handling.

             Automatic determination of Direct Addressing Mode use.

             Allowed message "Direct mode wasn't used" to show on screen
              (because of the change regarding the auto use of direct-mode it
              now will not be as frequent a warning as before).

             Added quotes around labels in Forward/Backward branch messages.

             Changed message displayed by forward definition on RMB to
              something more alarming (because this warning is actually an
              error in many cases and the code produced might be wrong, eg.
              JMP going the wrong place, etc.).  PLEASE (for your own peace
              of mind) take this warning *very* seriously and make sure you
              understand where it originates and how surrounding code may be
              affected.  Better yet, avoid forward references on RMB/DS
              pseudo-instructions, altogether.

  1.28Beta   Added recognition of END label address (if used).

  1.29Beta   Fixed Auto Direct Mode error for some situations.

  1.30Beta   Fixed map line for non-code lines.  It used to work, and
              sometime I inadvertedly messed it up, so it's back to normal.

  1.31Beta   Added directive $S19FLUSH to control when to break S19 files.
              Useful because some other assemblers wrongfully break the S19
              file when encountering an ORG even if the addresses are
              sequential.  The $S19FLUSH lets you control where to break the
              S19 so that you may better check the resulting S19 for equality
              to one produced by another assembler.  (BUF34.S19 from Mot is
              an example of this).

             Updated the help screen to correspond to current version.

  1.32Beta   Minor fixes here and there.

             TERM.EXE program updated with a couple of minor fixes.  It now
              allows uploading even in non-EVBU mode (without the LOAD T).

  1.33Beta   Added support for (nested) conditionals assembly.  New
              directives are: $IFDEF, $IFNDEF, $IFZ, $IFNZ, $ELSE $ENDIF

             Added directives for user induced warnings and errors
              (often useful in conditional assembly).  New directives are:
              $WARNING and $ERROR

             Re-arranged help screen to acommodate information about these
              and other directives.

             Not officially released

  1.34Beta   Fixed nested conditional handling and also fixed so that other
              directives following the conditionals.

  1.35Beta   More fixes for nested conditional handling.

  1.36Beta   Added IF, a two-expression conditional for comparing
              expression1 and expression2 with any of these:
                              =, <>, <, >, <=, >=

  1.37Beta   Added FATAL directive, same as ERROR only halts assembler.

             Moved error about "Symbol does not begin with ..." to PASS1

             Fixed problem with $ERROR recognized even inside false
              directive.

  1.38Beta   Maintenance release.

             For consistency, disabled .labels from being allowed to be
              indented.  This was not a bug (code would assemble correctly),
              just a deviant behavior that allowed one to indent label
              definitions starting with a dot (which one could not do with
              other non-dot-starting labels).

             Added updated versions of the example programs in a ZIP file.
              Also, added some new examples.

  1.39Beta   Added S0 record creation option (-SH).  Some people were having
              problems with their systems not accepting S19 files with
              missing S0 records.  The default is OFF for backward
              compatibility.

  1.40       Final(?) Non-Beta Version.  From this point on, new versions
              will only appear to correct possible remaining bugs or if I
              have something really nice to add.

             Added option -MTx for defining one of two source-level Map
              Types.  x can be either P for P&E compatible map file, or A for
              my own ASCII version of the map file whose format is
              self-evident, and can be used by third parties willing to
              support this freeware assembler.

             Added OSW extra mnemonic.  Similar to the OS extra but with a
              word immediate value (instead of OS's byte value).

             Added $OPTRTS directive for producing warnings on JSR/BSR
              followed by an unlabeled RTS which could be optimized to JMP or
              BRA, respectively.  This will only work after the $OPTRTS is
              encountered.  The command-line equivalent option for this
              directive is -RTS (not shown on the help screen).  Please note
              that the JSR/BSR must be immediately followed by an RTS to
              produce a warning.  Even a blank line in between the two will
              not produce the warning.

             Added "Branch too far forward/back" message offsets to know
              exactly how many bytes away the target address is.  The offset
              is displayed in decimal.

             Optimized memory usage when no $MAPOFF or -M- are in effect.

             Added PDF Quick Reference Guide (thanks to Mark Schultz for
              coming up with the idea and preparing it).

  1.41       Added "RESUMING FILE ..." message when closing an include in 
              the LST file.

             Added pseudo-op FCS (Form Constant String) which is equivalent
              to FCB with an added zero last value (eg. FCB 'Hello World',0
              may be written as FCS 'Hello World').

             Added "Reserved ..." warning message for $MAP directive.  This
              will be used in later versions to provide support for
              high-level language source-level debugging.

             Added warning message for unrecognized directives.

  1.42       Added a few extra lines of statistics at the end of the LST 
              file.

  1.43       Corrected v1.42 addition for certain special cases.

             On request, I removed the $ infront of the hex value in the SYM 
              files.  This was causing some incompatibility with third party 
              software.  The column positions are still the same, for 
              compatibility with previous versions.

  1.44       On request, I added the OPTRTSON/OPTRTSOFF for controlling the
              -RTS option (for enabling/disabling JSR/BSR followed by
              unlabeled RTS optimization warnings) from within the source.
              The OPTRTS has been removed.  Its function is now performed by
              OPTRTSON.

             On request, I added the OPTRELON/OPTRELOFF for controlling the
              -REL option (for enabling/disabling JMP/JSR to BRA/BSR
              optimization warnings) from within the source.

  1.45       Added display of actual branch address in the LST file in
              parentheses.

             Changed : address/code separator to + for RMB lines to
              differentiate between code and RMBs.

             Changed : address/data separator to . for all data producing
              pseudo opcodes, such as FCB, FCS, DB, etc., to differentiate
              between code and data.

  1.46       Changed return code from line number (which could not be
              grabbed correctly by many programs) to 0=No Error, 1=System
              Error, 2=Error, 3=Warning, 4=Usage/No Assembly.

             Added $IFEXISTS and $IFNEXISTS directives for checking if a
              file (normally an include file) exists before using the
              $include directive (or for other creative purposes).

             Changed the fatal type of error that would halt the assembler
              when an INCLUDE could not be opened to a regular error.  The
              previous function can be emulated with a combination of the
              newly introduced $IFEXISTS/$IFNEXISTS directives along with the
              $FATAL directive.  The change was done so that an INCLUDE not
              found does not automatically stop the assembler when there are
              more files to process.

             Added report of Number of Lines in Listing file.

             Added report of Number of Include files in Listing file.

             Added $MESSAGE directive.  Similar to $WARNING but does not
              count warnings, not does it show in error files.

CREDITS:

I must credit Mark Schultz (mschultz@bigfoot.com) for his numerous
suggestions, some of which I followed to the letter while others I followed
with modifications.  Also, for test-driving ASM11 so much he discovered the
LSRD bug in an early version, and for providing his FLASH.A11 example for
programming Flash memories, and, finally, for preparing an excellent (I
think) Quick Reference Guide in PDF format which you can print.

KNOWN PROBLEMS: None

  Please report problems you find to the address below (or via email at
  tonyp@acm.org).

SUGGESTIONS ARE WELCOME:

  I can't promise to follow every suggestion as some of them require too much
  (re)writing of code and this implies having enough free time on my part to
  carry out the needed modifications (I wrote ASM11 for my own use mainly
  because I was disappointed by most free/affordable assemblers, but what I
  use it for is what I'm mostly interested in).  Other suggestions, although
  they may be justifiable, I won't follow simply as a matter of taste.  I
  want this assembler to have some things that I like (that was the reason
  for writing it, in the first place), so if those very same things you
  happen to dislike (or the other way around), sorry.

  Please keep in mind that I consider this software to be complete in what 
  was originally planned (actually much more than that has been done) so I
  will only add new features that I find really useful or incredibly simple
  to implement when time allows.

  If you find yourself using this program regularly you could be nice enough
  to send me a postcard from your city/country (optionally with your name and
  e-mail address on it, if you care to be notified about future enhancements
  or other related development tools as they become available).  At any rate,
  I would still like to receive your comments after you have used the
  assembler for a while.

  I hope you'll enjoy using ASM11 but, most importantly, 68HC11 programming.

ͻ
             Comments to the author may be directed to the address:        
                                                                           
                            Tony G. Papadimitriou                          
                               P.O. Box 14386                              
                                Athens 115 10                              
                                   GREECE                                  
ͼ

LEGAL NOTICE:

This software is FREEWARE which means it is NOT public domain but fully
copyrighted material that is distributed freely without money.  Its
electronic distribution through BBSs, the Internet, or other such means is
encouraged provided no money is requested in return.

Also, it is forbidden to distribute this software should this file, or any of
the remaining files, change in any way or be omitted from the archive.

 Please note that although I have done my best to ensure there is no
  potentially dangerous code (or accidental virus infections), the nature of
  programming is such that forces me to provide absolutely no warranty,
  express or implied, with this version of the software, and I bear no
  responsibility for whatever damages, direct or consequential, you may
  suffer from its use.  I definitely do not warrant this software for
  suitability for any particular purpose, either.  It is also possible that
  the instructions, the extra utilities, or the examples that come with the 
  software contain errors, none of which were intentional.

                                          Tony G. Papadimitriou, M.S.
                                          e-mail: tonyp@acm.org
