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=] [LEVEL=] [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=] 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=] 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