Short:        Comment/reformat 2650 crossdisasms
Author:       amigansoftware@gmail.com (James Jacobs)
Uploader:     amigansoftware gmail com (James Jacobs)
Type:         dev/cross
Version:      2.33
Requires:     OS2.0+
Architecture: m68k-amigaos >= 2.0.0

Please note that this package has nothing to do with the popular Amiga
text editor which is likewise known as ANNOTATE. Our apologies for any
confusion.

ANNOTATE reformats the output of the DASMX cross-disassembler to make
it more readable (by adding pseudo-C endline comments), and more
compatible with the VACS cross-assembler. (DASMX and VACS are for
Windows.) ANNOTATE is a specialized tool intended for retroprogrammers of
machines which use the Signetics 2650 CPU (especially those emulated by
the AMIARCADIA and WINARCADIA emulators). It has been tested with DASMX
1.40 and VACS 1.24h.

There are eight different 'levels' of operation. Each higher level adds
additional annotation; ie. the highest level gives the friendliest, most
detailed output.

1: (a) Convert tabs to spaces.
   (b) Convert ",+" and ",-" postincrement/postdecrement notation to "+"
       and "-", respectively.
   (c) Convert literals to "$x"-style.
   (d) Convert labels at $2000 or later to literals.
   (e) Convert registers to condition codes for BSNA and BSNR opcodes
       (to deal with a bug in VACS).
   (f) Append ",r3" to operand after BXA and BSXA opcodes.
   (g) Append "end" to end of file.
   (h) Insert 2650 equates.
   (i) Insert banner into header comments.
   (j)*Insert platform family into header comments.
2: (a) Append pseudo-C comments.
3: (a)*Insert hardware equate definitions.
   (b)*Convert hardware registers from literals to constants.
4: (a)*Append memory purpose information to memory access comments.
5: (a)*Insert hardware equate comments.
6: (a) Append cycle timings of each instruction.
   (b) Append byte-lengths of each instruction.
7: (a)*Append runtime start and end addresses of each instruction.
8: (a) Append raw hexadecimal bytes of each instruction. This requires you
       to supply a raw binary dump of the game with the BINFILE or PGMFILE
       argument.

Those marked `*' are platform-specific (ie. different between different
machines).

You *must* feed it unmodified DASMX output, which has been disassembled
with the 'numformat M' or 'numformat I' option. For more information about
disassembly of these files, see the Coding Guides at the site below.

You use it from the command line. All output from the program goes to the
standard output (normally the console), and thus can be piped or
redirected as desired.

Usage is as follows:

    Annotate [FILE|ASMFILE=]<filename> [LEVEL=<number>] [AMIGA]
    [MACHINE=INTERTON_A|INTERTON_B|INTERTON_C|INTERTON_D|ELEKTOR_E|
    ELEKTOR_F|ARCADIA_G|ARCADIA_H|ARCADIA_I|PIPBUG_J|PIPBUG_K|PIPBUG_L|
    PIPBUG_M|PIPBUG_P|INSTRUCTOR_N|INSTRUCTOR_O|CD2650_U|GENERIC]
    [BINFILE|PGMFILE=<filename>]

The template is:

    FILE=ASMFILE/A,LEVEL/N,AMIGA/S,MACHINE/K,BINFILE=PGMFILE/K

FILE or ASMFILE is the input filename.

BINFILE or PGMFILE is the filename of the raw binary dump of the game.
Specifying this argument automatically selects level 8.

LEVEL is the level number as explained above. The default level is 7,
unless a BINFILE or PGMFILE argument is given, in which case it is 8.

The AMIGA keyword will cause carriage returns found in the input to be
omitted on the output; ie. to use Amiga-style end-of-line (EOL) sequences
(LF) rather than IBM-PC ones (CR+LF). This is more convenient for
manipulation of the output on an Amiga but is not acceptable to VACS.
(Amiga version only.)

MACHINE affects the platform-specific annotations listed above. The
default is ARCADIA_G.

Output is to the console by default; use redirection to create an
output file. For example:

    Annotate SUPERBU1.ASM BINFILE=SUPERBUG.BIN >SUPERBU2.ASM

Running it with no arguments will give a list of supported machines.

SAS/C and Microfilth Visual C++ 5.0 source code is included. Also included
is an example disassembly of the Super Bug game. SUPERBU1.ASM is the
unmodified DASMX output, disassembled with the 'numformat M' option of
course. SUPERBU2.ASM is the result of using ANNOTATE on SUPERBU1.asm, and
will assemble under VACS without any changes required.

Also note that use of indirect addressing (the "*" operator) adds a
further 2 cycles (6 clock periods) to the execution time of an
instruction, if the indirect address is actually used (eg. branches
that are taken will incur the penalty, branches that are not taken will
not incur it). Branches which may or may not be taken are annotated with
"+2" in the cycle count (eg. "3+2"). Where the branch is always taken,
or for non-branch instructions (eg. ADDA, ADDR), the penalty is
incorporated fully into the cycle count (eg. "5").

The included TOGGLER program is used to change the header byte of Elektor
.PGM files (Elektor TV Games Computer programs) from $00 to $1F (bcta,un)
for compatibility with DASMX. After disassembly with DASMX, TOGGLER can be
run again to reverse the change to the .PGM file. You will also need to
change the start of the ANNOTATEd source code, eg. from:

    bcta,un $0900

to:

    db      $00
    dw      $0900

See the Elektor TV Games Computer Coding Guide for more information. None
of this applies to other kinds of .PGM files (eg. PIPBUG, Instructor,
CD2650).

Usage is as follows:

    Toggler [FILE=]<filename>

The template is:

    FILE/A

At the Emerson Arcadia 2001 Central site are some resources of interest
to users of ANNOTATE: the Coding Guides have detailed information
about disassembly, annotation and patching of games, and the
Autodisassembly Pack contains ANNOTATEd disassemblies.

Changes since V2.32:
    . PIPBUG-based machines: miscellaneous bug fixes and improvements.

Releases Page:                http://amigan.1emu.net/releases/
Emerson Arcadia 2001 Central: http://amigan.yatho.com/
EMail:                        amigansoftware@gmail.com

James Jacobs of Amigan Software
16/4/10