A68k - a freely distributable assembler for the Amiga by Charlie Gibbs with special thanks to Brian R. Anderson and Jeff Lydiatt (Version 0.9 - January 28, 1987) Note: This program is NOT Public Domain. Permission is given to freely distribute this program provided no fee is charged, and this documentation file is included with the program. This assembler is based on Brian R. Anderson's 68000 cross-assembler published in Dr. Dobb's Journal, April through June 1986. I have converted it to produce AmigaDOS-format object modules, and have made many enhancements, such as macros and include files. My first step was to convert the original Modula-2 code into C. I did this for two reasons. First, I had access to a C compiler, but not a Modula-2 compiler. Second, I like C better anyway. The executable code generator code (GetObjectCode and MergeModes) is essentially the same as in the original article, aside from its translation into C. I have almost completely rewritten the remainder of the code, however, in order to remove restrictions, add enhancements, and adapt it to the AmigaDOS environment. Since the only reference book available to me was the AmigaDOS Developer's Manual (Bantam, February 1986), the assembler and the remainder of this document work in terms of that book. RESTRICTIONS Let's get these out of the way first. There are a few things that I have not yet implemented, and some outright bugs that would take too long to correct for this version. o The verification file (-v) option is not supported. Diagnostic messages always appear on the console. They also appear in the listing file, however (see extensions below). o The header file (-h) option is not supported. o The file names in the include directory list (-i) must be separated by commas. The list may not be enclosed in quotes. o Local labels are not supported - symbols of the form nnn$ will be mistaken for numbers followed by a syntax error. All other symbols are assumed to be global. o Although all operators are accepted in expressions, no precedence is given. Processing is strictly from left to right. Attempting to use parentheses to force precedence will give the assembler indigestion. I intend to lift this restriction in a future release. o A maximum of 256 relocatable references (XDEF or XREF symbols or *) can be made in one hunk. If this limit is exceeded the assembler tries to break the hunk and restart it. o The cross-reference listing is not yet available. I'll put it in as soon as I find the time. o In some cases, if an operand is missing from an executable instruction, invalid code will be generated. No error messages are issued. o The following directives are not supported, and will be flagged as invalid op-codes: RORG OFFSET EQUR REG DCB NOPAGE LLEN PLEN NOOBJ FAIL FORMAT NOFORMAT MASK2 I feel that NOPAGE, LLEN, and PLEN should not be defined within a source module. It doesn't make sense to me to have to change your program just because you want to print your listings on different paper. The command-line option "-p" (see below) can be used as a replacement for PLEN. EXTENSIONS Now for the good stuff: o The number of labels is limited only by available memory, which can be increased by using the "-w" option below. Using the default heap size of 16384 bytes, there is room for over 500 8-character labels, although labels can be any length that will fit into one source line (currently 128 bytes maximum). o Since section data and user macro definitions are stored on the same heap as the symbol table (see above), they too are limited only by available memory. (Actually, there is a hard-coded limit of 32767 sections, but I doubt anyone will run into that one.) o The only values a label cannot take are the register names - the assembler can distinguish between labels, instruction names, macro names, directives, and section names. o Section and macro names appear in the symbol table dump. Their names can be the same as any label (see above); the assembler can sort them out. When I get the cross-reference listing going, section and macro names will also be cross-referenced. o Includes and macro calls can be nested to a combined limit of 19. I intend to lift this restriction in a future release. Recursive macros are supported; recursive includes will, of course, result in a loop that will be broken only when the above limit is exceeded. o The EVEN directive forces alignment on a word (2-byte) boundary. (This one is left over from the original code.) o Branch (Bcc) instructions to a previously-defined label will be automatically converted to short form if possible. This feature is not available for forward branches, since in pass 1 the assembler doesn't yet know how far the branch must go. o If a MOVEM instruction only specifies one register, it is converted to the corresponding MOVE instruction. o ADD, CMP, SUB, and MOVE to an address register are converted to ADDA, CMPA, SUBA, and MOVEA respectively. o ADD, AND, CMP, EOR, OR, and SUB of an immediate value are converted to ADDI, ANDI, CMPI, EORI, ORI, and SUBI respectively (unless the address register conversion above has already been done). o If both operands of a CMP instruction are postincrement mode, the instruction is converted to CMPM. o The SECTION directive allows a third parameter. This can be specified as either CHIP or FAST (upper- or lower-case). If this parameter is present, the hunk will be written with the MEMF_CHIP or MEMF_FAST bit set. This allows you to produce "pre-ATOMized" object modules. o The synonyms DATA and BSS are accepted for SECTION directives starting data or BSS hunks. A section name is mandatory for all non-CODE hunks. o The ability to produce Motorola S-records is retained from the original code. The -s option causes the assembler to produce S-format instead of AmigaDOS format. Relocatable code cannot be produced in this format. HOW TO USE IT The command-line syntax to run the assembler is as follows: a68k [-o] [-l] [-i] [-p] [-s] [-w] [-x] These options can be given in any order, so if you like to specify your switches first, you can. Option values, if any, must immediately follow the keyword with no intervening spaces. If the -o keyword is omitted, the object file will be given a default name. It is created by replacing all characters after the last period in the source file name by "o". For example, if the source file name is "myprog.asm", the object file name defaults to "myprog.o". A source name of "my.new.prog.asm" produces a default object file name of "my.new.prog.o". If the source file name does not contain a period, ".o" is appended to it to produce the default object file name. The default value for the listing file name is arrived at in the same way as the object file name, except that ".lst" is appended instead of ".o". You can suppress the listing file by specifying the -l keyword with no name following it (this also makes the assembler run faster). The include directory list is a list of directory names separated by commas. No embedded blanks are allowed. For example, the specification -imylib,df1:another.lib will cause include files to be searched for first in the current directory, then in "mylib", then in "df1:another.lib". The -p keyword causes the page depth to be set to the specified value. If omitted, a default of 54 lines (-p60) is assumed. The -s keyword, if specified, causes the object file to be written in Motorola S-record format. If omitted, AmigaDOS format will be produced. The default name for an S-record file has ".s" appended to the source name, rather than ".o"; this can still be overridden with the -o keyword, though. The -w keyword specifies the heap size to be used. The default size of 16384 bytes should be enough for all but the largest assemblies. The assembler uses 17 bytes plus the length of the name for each label, section, and macro definition, plus any storage required to hold the macro definitions themselves. The amount of heap space actually used is displayed at the end of the assembly. If you're really tight for memory, you can use this keyword to reduce the space below the default of 16384 bytes. The -x keyword will cause a cross-reference listing to be produced, once I implement it. For now, it just produces a warning message. If you wish to override the default object and (optionally) listing file names, you can omit the -o and -l keywords. The assembler interprets the first three parameters without a leading hyphen as the source, object, and listing file names respectively. Anything over three file names is an error, as is attempting to respecify a file name with the -o or -l keyword. Please send me any bug reports, flames, etc. I can be reached on Dorean BBS (604/432-8579), at any PaNorAmA meeting, or via Jeff Lydiatt or Larry Phillips. There's a lot I still want to do to this thing, including cleaning up the source so it's fit for anyone else to look at. -- Charlie Gibbs