Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 013.lha / Asm68k.doc < prev next >

Wrap

Text File | 1986-11-10 | 48.7 KB | 1,310 lines

Asm68k 68000 Macro Assembler Version 1.0.1 Docs Date: 20-Jan-87 =============================================================================== IMPORTANT: This is the second beta release of this program. Correct object has been verified for correct source, and appears to operate well. Please send any bug reports to me promptly, either through MMS [(919) 779-6674] or Deep Thought, [(919) 471-6436], Compuserve [73277,260], the Mail or at my home address. Your help is greatly appreciated. =============================================================================== NOTICE: THIS FILE AND THE PROGRAM IT DESCRIBES ARE COPYRIGHT © 1987, W. WESLEY HOWE. ALL RIGHTS RESERVED. A LICENSE FOR USE AND DISTRIBUTION WITHOUT PROFIT IS GRANTED TO POSSESSOR OF THIS FILE, PROVIDED DISTRIBUTION INCLUDES THE PROGRAM AND THIS FILE. NO RIGHT OF ALTERATION OF THE PROGRAM OR DOCUMENTATION IS CONVEYED WITH THIS LICENSE. NO WARRANTY IS EXPRESSED OR IMPLIED HEREIN ON THE SUITABILITY OF THIS PROGRAM FOR ANY PURPOSE AT ALL. YOU MUST RELY ON YOUR OWN JUDGEMENT AS TO WHETHER THIS PROGRAM WILL OPERATE PROPERLY WITH YOUR COMPUTER FOR WHATEVER PURPOSE YOU MAY DESIRE TO USE IT FOR. ADDRESS ALL QUESTIONS, COMMENTS OR CRITICISM TO: W. WESLEY HOWE 4800 LAKEMONT DR. RALEIGH, NC 27609 ============================================================================= LIMITS: Source-line length: 255 bytes (including newline) Sub-expression length: 40 bytes Parenthesis nesting: 16 levels Symbol length: 31 bytes Macro Size: 8,190 bytes Number of Macros: Available RAM Number of Symbols: Available RAM Available RAM: 270,336 bytes maximum heap utilized Macro Nesting: 8 levels Include Nesting: 8 levels Conditional Nesting: 16 levels Macro Parameters: 10 per invocation Sections: 255 maximum Program size: 91,364 bytes (loaded) Minimum free heap: 26,796 bytes Total RAM necessary: 118,160 bytes Constant size: 255 bytes Storage size: 65,535 bytes Strings: 255 bytes (or line length limit) Minimum stack: 8,192 (recommended) Operating System: V. 1.2 Workbench (CLI Only ) (Release) ============================================================================== If you are an experienced 68000 Assembly language programmer, you will find much of this material useful in understanding assembly language programming on the AMIGA. If you are an experienced AMIGA assembly language programmer, you may find much of the material boring, and will only want to use this as a reference document. If you don't know assembly language, then this document will not teach it, so you may need to buy (What? spend MONEY?) one of a number of reference books on MC68000 assembly language programming that are available. In the following sections, Directives, Commands, Expressions and Mnemonics are referred to. A Directive or Command is an instruction to the assembler which causes a specific action to be performed. Some of these add data to the object file, and some only affect the way assembly operations are performed. A Mnemonic is the Pseudo-English abbreviation for an in- struction the assembler is to translate into the appropriate numeric sequence and include in the object file for the MC68000 processor to perform later, when your program is run. An expression refers to any sequence of items consisting of numbers, symbols with a numerical value, and the allowable math operators which can be reduced to a single number value. ============================================================================== Math & Logic Operators: + Addition - Subtraction or Negation ~ Bit-wise NOT << Bit-wise left shift >> Bit-wise right shift & Bit-wise AND | Bit-wise OR ! Bit-wise OR (for compatability) ^ Bit-wise XOR (Exclusive OR) / Integer Division %% Integer Modulo (Remainder) * Integer Multiplication or Current Program Counter Location Like the Rotomola assembler, all expressions evaluate in strict Left-to- Right order, as divided by parentheses. The Unary operators '-' and '~' need to be offset from any adjacent operators with parentheses. Symbols and constants may be mixed, and space or tab characters may be included. No individual portion of the expression may exceed 40 characters (NOTE: a 'portion' would be any symbol or number alone.) Some examples: 4+(7*2) Yields 56 4 + ( 7 * 2 ) Yields 56 4+7*2 Yields 22 -4*6 Yields -24 6*-4 Error 4(6*7) Error ('A'+1) Yields 66 "A" + 1 Yields 194 'ASDF'+0 Error =============================================================================== Numbers and Constants: Binary: A binary number is either [1] prefixed with the '%' (percent) character, or [2] followed immediately with the letter 'B' (UPPER or lower case). It may contain only the digits '1' or '0'. Octal: An octal number is either [1] prefixed with the '@' (at) character, or [2] followed immediately with either the letter 'O' or the letter 'Q', in either case. Only the digits '0' through '7' are valid. Decimal: A decimal number contains only the digits '0' through '9', and may be optionally followed immediately with the letter 'D' (either case.) Hexa-Decimal: HexaDecimal numbers contain the digits '0' through '9', and the letters 'A' through 'F' (in either UPPER or lower case.) They may be [1] prefixed with the '$' (Dollar) character, or [2] they must start with a digit and be followed immediately with either the letter 'Q' or the letter 'X', in either UPPER or lower case. A leading '0' may be prefixed for the post-fix form. Leading zeros do not affect the value of any of the number forms, although the 40 character limit applies to them also. Characters: An INDIVIDUAL ascii character may be included by enclosing it in QUOTES. The single quote will yield the ascii value, and the double quote will yield the ascii value with bit 7 SET (or'd with 128). Multiple byte constants are not evaluated in this version. Some Examples: The number 1,000 (one thousand) may be represented any one of the following ways: 1111101000B 01111101000b %1111101000 1750Q 01750o @1750 1000D 0001000d 1000 3e8H 03E8h $3e8 ============================================================================== Assembly Line Format: An input assembly line follows the following models: Label Mnemonic Operand , MoreOperands ;comment Label: Mnemonic Operand Comment Mnemonic Operand Label: Mnemonic * a comment only Note that the LABEL either starts in the first column, or is followed by a colon. The Mnemonic field is separated by at least one space or tab, and never starts in the first column. Operands, where needed, follow, separated from the Mnemonic by at least one space or tab. Multiple operands are separated from each other by a comma (the comma flags the assembler that there is another operand available.) An asterisk in the first position on the line indicates a comment only line, or comments may follow complete operands with a space or semicolon separator. Assembler directives occupy the Mnemonic position, and comments are optional. Labels are allowed on all lines, and are required for some assembler directives. ============================================================================== Constants: The following Assembler directives cause the inclusion of data in the Object file: DB Yields 8-bit values. Either STRINGS, Symbols, Labels, numbers or expressions may be evaluated. Multiple operands need to be separated by commas, and generate successive bytes up to a limit of 255 bytes (the line-length limit should prevent this from ever being reached.) DW Yields 16-bit values, in Hi-Lo order. The format is the same as the DB directive, except STRINGS will not be evaluated. If the address is not a word address, a pad byte will be appended to the previous line, and a non-fatal error message will be issued. DL Yields 32-Bit values. Otherwise equivalent to DW. DC This directive is the same as DW. Appending .L or .B (in either case) will change the function to be the same as DL or DB, respectively. ASCII This command yields a sequence of bytes equivalent to the ascii value of the operands (delimited by quotes) provided. Single quotes will yield the normal value, and double quotes will yield values with bit 7 SET. Within the delimited STRING, a '\' (backslash) character, followed by up to three decimal digits will cause inclusion of a byte with the same numerical value, or if followed by any other character will allow the inclusion of that character immediately following. (This is useful for including quotes and backslashes in the string.) A limit of 255 values applies. CSTRING This command is the same as ASCII, except an additional byte with the value 0 is appended (as in the C language.) PSTRING This is the same as ASCII also, except a leading byte with a value equal to the number of bytes following is prepended (as used in the PASCAL language). ISTRING This variant of ASCII will cause the final character to have it's most significant bit of the opposite (INVERTED) value from the rest of the characters in the string (as defined by the delimiting quotes). This form is popular among 8-bit machines, and some BASIC interpreters. It's usefulness with the new international 8-bit standard ASCII is questionable, but it may be helpful, so it hasbeen included anyway. DCB This command accepts the .B .W and .L size specifiers (or defaults to WORD.) It generates as many values as the operand expression evaluates to (up to 255 bytes total), of the size specified. WORD and LONG sizes are forced to an even address alignment. ============================================================================== Symbol and Labels: A Label is an address designator. It is placed before a mnemonic or a data location, and acquires a value equal to the relative program counter value at that location. A standard Label may only be defined this way once in a program, but may be referenced as many times as needed. It must start with a letter, a period or the '_' (underscore) character, and may contain only these characters, or the digits '0' through '9', without spaces up to a total of 31 characters. When you define a label, it must appear as the very first item on a line, or you must append a ':' (colon) character to it. (You may have the colon in the first case also.) You must not use the colon on the label other than when you define it, or you may get an erroneous interpretation of your expression. A Symbol starts off looking like a label, and follows the same rules, except the following commands modify it to acquire a new type and value: EQUATE Sets a permanent, absolute value equal to the value of the expression following this directive. STRING values are not allowed. SETVAL Sets an absolute value which is retained until a new value is set. You may not later use EQUATE on this label, but you can EQUATE a different label to the set value. EQUR Gives a value to the symbol which may later be used in place of a standard data or address register. This is valid only for D0-D7 or A0-A7 (SP is a synonym for A7). You cannot use this value other than to reference a register in a MC68000 mnemonic. REG Accepts a register-list operand for use with the MOVEM mnemonic. A register-list looks like this: A2-A7/D1/D3-D7 Which defines the registers A2 through A7, D1 and D3 through D7. In fact, all the registers except A0, A1, D0 and D2. Only the standard address and data registers may be defined in this fashion. MACRO Assigns a sequence of input lines, with replacable parameters, which will later be substituted for any line which uses this symbol as a mnemonic or command. More on Macros later. These Directives must have a Label in the Label Field for assignment. You must avoid referencing a symbol before giving it a value, or the assembler will complain (sometimes), because the forward reference will make it type the symbol as a label, which is an address, not a number. Labels, of course, may be referenced before use, and it's value will be substituted on the second pass. In fact, this is the only reason you need a two-pass assembler. ============================================================================= Local (Numeric) Labels: A line may be labeled with a special Local Label which attaches itself to a specific offset from the last proper line label, as previously described. A Local Label is a sequence of up to three decimal digits followed by the '$' (Dollar) character. Like a regular Label, if it does not start at the beginning of the line, it must be followed by a colon. A Local Label may be referenced in an operand anywhere a line Label would, but it's scope is only between one regular Label and the next. Each time a new regular Label is used, the Local Label may then be redefined and reused with a different value. An example: Start Jsr Initialize_Data 001$ Jsr Initialize_Serial Move.b D1,ChangeFlag Cmp.b #0ffh,D1 Bne 1$ Note that 001$ and 1$ will evaluate to the same location. You need not start with one and may use any numbers you desire, as long as their value does not exceed 999. Also, note that $1 and 1$ are interpreted differently; the first is an absolute expression, and the second is a relative address. Local Labels may not be used for Macro names, although they may be used within Macros, and cannot be used to represent Numbers, EXTERNal or ENTRY types. ============================================================================== Conditional Assembly Directives: The following Commands allow assembly to proceed until a matching ENDIF Directive is found, or disable assembly until the ENDIF is reached if the condition is not met: IFEQ Expression EQuals zero. (e.g. 4-4) IFGE Expression Greater than or Equal to zero. (e.g. 4-4 or 4-3) IFGT Expression Greater Than zero. (e.g. 4-3) IFLE Expression Less than or Equal to zero. (e.g. 4-4 or 4-5) IFLT Expression Less Than zero. (e.g. 4-5) IFNE Expression is Not Equal to zero. (e.g. 4-5 or 4-3) The above conditionals are evaluated to 32 bits, but the condition decision is based on their WORD (16-bit) value. IFD Label following was already Defined (not just referenced.) IFND Label following has Not yet been Defined. IFC Both STRINGS following Compare (same length and characters.) IFNC Both STRINGS do Not Compare (different length or characters.) The last two conditional commands need two operands, separated by a comma. They may be delimited with Quotes (single or double), or by a left bracket '<' and right bracket '>' pair, or the first string will start at the first character which is not a space or a tab, and end at the first occurrence of a comma or space or tab, and the second will start at the next character which is not a comma or a space or a tab and will end at the first space, tab, semi- colon or newline character. To enclose spaces in the string, you must use either the quote or bracket delimiters. To enclose quotes, use the brackets, and to enclose brackets, use the quotes. Both quotes and brackets cannot be passed together unless you use the spaces, but then you can't have spaces in the string. Just shows to go you, everything is a compromise. Any backslash characters are not expanded before comparison. Each Conditional command DO level ends with an ENDIF command. DO levels nest only to 16 levels, or a fatal error will be generated (whether the assembly is on or off, each IFxx increases the level count, and each ENDIF decreases the count; exceeding 16 or going below zero are fatal errors.) DO levels are not active during a macro definition, but will be evaluated during a macro expansion. ============================================================================== Other Assembler Directives: RESERVE Creates an uninitialized data storage area, with a size equal to the expression following it. The size designators .B .W and .L (any case) may be used, or WORD is assumed. The expression following the Directive is expanded to the size specifier. This is the only Directive which is not limited in size to 255 bytes for the result, but may yield up to 65,535 bytes. ENDSRC Shuts off assembly for the current DO level. (See the section on conditional assembly for DO level explanation.) If you are not in a DO level, the source is read to the end of file, but no assembly action will occur. OPTION This command accepts the following operands only: M - Allows macro call lines to print in the assembly listing. (If List is on.) This is the default condition. NM - Hides macro call lines, showing expansion lines only. L - Turns on listing. (The default condition). NL - Shuts off Listing. (Neither of these commands override the command-line switches directly, they only control the flow of data. An assembly will still create a list file if not prohibited, Option NL will just make it an empty file. If the list file was disabled on the command line, Option L will not send the listing anywhere. None of the operands are case-sensitive.) TITLE Accepts a STRING (delimited by quotes) which will label all pages, if paging is not disabled. The Maximum title length is 40 characters. Also cause pages to be numbered. ORIGIN Sets the program counter to the value of the expression following the command. Origin remains relative on AMIGA output format. PAGEUP Causes a page to end if paging is not disabled. A form-feed character is sent, and a page heading with the optional title (see TITLE) is printed. SECTION this command causes a new section, or Hunk, to be created in the AMIGA output format. The first operand must be a name containing no spaces and having less than 40 total characters. The second operand, if given, should be separated by a comma and should be either CODE, DATA or BSS. If none is given, CODE is assumed. (only the first character is checked, however, so DUMMY will yield a DATA section definition.) Case is not significant on the section type, but case is important for the name. If the section name has been used before, assembly will proceed at the next location as was previously defined, and the resultant code, data or storage space will be coalesced into one Hunk. See the AmigaDOS manual for more information on Hunks. IDENTIFY This command should be followed with a name, which will be given to the program unit (a program unit is a hunk or a collection of hunks to be fed to the linker.) Only the first name given will be used, subsequent uses are ignored. If the IDENTIFY command is not used during an assembly, the object file will be given a name that has 0 characters in it. (Null string.) EXTERN Followed by one or more Labels or symbols (separated by commas.) These labels must not be defined within the entire assembly source, and cause the assembler to generate the appropriate external reference instructions in the object file (AMIGA format only) for resolution by the linker. ENTRY Followed by one or more Labels or Symbols. These labels, which need to be defined somewhere, allow locations within the program unit to be visible to the linker to resolve other program unit EXTERNal references. A program that consists of more than one object file will need to have an ENTRY in one unit for every EXTERN in the other units, or the program will 'BOMB' and probably either lock-up the machine or cause the dreaded GURU to appear. References between different sections must be to ENTRY labels, since the AMIGA loader will place each section wherever it will fit, and resolve all these different addresses. If you never use the section command, the entire program will have to fit in the same place, and might not be able to be loaded if there is not a spot big enough for the whole thing (depending on how many tasks might also be running, etc.) EXECUTE This command will pass the quote delimited string following it to AmigaDOS during the second pass. The current window is the input and output. A more detailed description of the Execute routine is located in the AmigaDOS manual, but basically the same things you can do from the CLI may be contained within the string and executed from within the assembler. The Source, Object and any open Include files will be locked, and cannot be accessed at this time. No use is made of the return value from the program called. This is your hook, let me have some ideas for any uses for it (hint: the Macro functions allow some very powerful uses, and any valid AmigaDOS device may be used for Source, Include and Object file-handles.) CNOP This Directive causes null filler bytes to be inserted into the object file until the desired alignment is reached. There should be two values after the Directive, separated a comma. The second value given is the desired alignment value you want, and the first value is how many more to add beyond this point. There may not be more than 255 bytes generated in total to acheive the desired alignment, and no restrictions are imposed on what alignment values can be used. If you want to set the Program Counter 5 bytes beyond the next PC location evenly divisible by 7 use the command like this: CNOP 5,7 The predominant reason for using this command would be to align data at specific offsets, and to create data structures in specific formats. =============================================================================== Include Files: Up to 8 levels of include files may be inserted into the assembly with the INCLUDE Directive. The syntax demands a Filename or Path, delimited by quotes. Include file directory searches are supported by command-line parameters (De- tailed in another section.) Include files may be called by Macros, and Macros may be used by Include files, up to their respective nesting levels (8 each.) The INCLUDE directive will cause the next source line to be read from the named file as if the entire contents appeared in the original source file, except line numbering will start at one again, and the line number will be followed by a '+' (plus) sign. When the end of the Include file is reached, the line number will revert to the one following the line which invoked the INCLUDE Command. Special provisions have been made to allow automatic and command-line inclusion of header and/or macro definition files before assembly starts, and these files do not count in the nesting level limits for Include files. A later section will describe command-line parameters and the configuration file. A SPECIAL NOTE: Several of the existing include files from Commodore do not Assemble correctly (particularly those in the exec directory.) Many of the source lines in these files contain comments which are delimited only by spaces and an asterisk. Asm68k is not restrictive about spaces within an expression, and tries to assemble the asterisk as a multiplication operator with the words in the comment being looked at as labels, and gives appropriate error messages. Make sure the comments are stripped or delimited by a semi-colon (as per the MOTOROLA spec.) A few of the files contain Macro error checks using an IFC \1,'' which will not assemble correctly with Asm68k. Use IFEQ NARG instead. the FUNCDEF file contains an expression 4*-6, which will not be interpreted correctly as written. Change this one to 4*(-6). These changes will make both assemblers happy, and the include files more portable between applications. =============================================================================== Macros: The best feature of the assembler, and the hardest one to master, is the use of the MACRO command. A Macro is simply a sequence of source lines which may be saved and inserted as often as wanted just by using the name you gave it as a command. A Macro may contain any of the other Directives and Mnemonics the assembler recognizes except another MACRO definition command, although you may use the name of a defined Macro in your Macro (up to 8 levels deep.) A Macro is defined (and it must be before being used) by placing the MACRO in the Mnemonic Field, either before or after it's name. The name for the Macro must follow the rules for Labels if it is on the left side, or if it is on the right side it needs to be separated by at least one space or tab from the MACRO Directive, and follow all the Label rules except it does not need to be followed by a colon. All the subsequent lines up to the one which contains the ENDMAC command will be saved for subsequent use. The real power of Macros comes from their use with replacable parameters. When you issue a Macro name as a Command, up to ten parameters (numbered from one to nine, with zero for ten) may be included in a comma, space or bracket separated list after the name for use within the Macro text. To make these parameters appear in the Macro expansion, place a '\' (backslash) character followed immediately (no spaces) with the digit of the parameter you want in the definition. When the macro is expanded, the text will include the parameter placed on the calling line, and will be evaluated just as if the source had included it as it appears. The parameters are gathered under the same rules as the IFC and IFNC commands (bracket, quote or space delimiters.) The backslash character may be passed to the Macro by including two backslashes in the calling line, and any non-numeric character following a backslash other than a backslash will pass both the backslash and the character following it to the Macro. Conditional Directives are effective within the Macro, under the same rules as they follow elsewhere. If assembly is enabled, and the Directive MEXIT is encountered, expansion of the Macro is suspended, and the next source line will be the one following the Macro invocation line, after the assembler has examined the remaining Macro text and resolved all the IFxx and ENDIF levels. To make Macros respond differently with different numbers of passed para- meters, the special symbol NARG (not case-sensitive) has been reserved. It will yield a value equal to the number of parameters found on the invocation line within a Macro expansion, and zero elsewhere. One additional feature within Macros is the \@ (backslash followed by the at character). While the Macro is being expanded, this combination is changed to a period followed by three decimal digits. These digits increment starting from zero every other time the \@ combination is expanded. This allows pairs of unique symbol names to be generated within the Macro text, allowing branch instructions to occur. Local (numeric) Labels are effective within the Macro, but they do not attach to the Macro name, nor are they canceled by the Macro invocation (unless the invocation line was labeled.) ============================================================================== Do Nothing Directives: The following directives are accepted by the assembler, but cause no action and generate no code, just as if they were comments. They have been included to allow use of source code written for other assemblers. MASK2 FORMAT SPC NOL OFFSET Synonym Directives: The directives in the left column are substitute names for the directives in the right column, and were included for source compatability: DS RESERVE END ENDSRC EQU EQUATE SET SETVAL TTL TITLE ENDC ENDIF ENDM ENDMAC RORG ORIGIN XDEF EXTERN XREF ENTRY RORIGIN ORIGIN =============================================================================== Unimplemented Directives: The following Directives, found in some other assemblers, have not been implemented in this version: IDNT FAIL LIST LLEN PAGE PLEN NOOBJ NOLIST NOPAGE A startup Macro file has been included with this package to allow some compatability if these are needed. =============================================================================== Startup Configuration: If a file named Asm68k.cnf is found in the current directory, it is read and acted on. The current version only looks for two items in this file, the pagelength (which must be greater than 11) and the name of the startup file. The format is: Page Length: 1 byte (11-255), binary File Path: up to 31 bytes, ascii Terminator: 1 byte, binary, value 0 Any remaining characters after the null byte are ignored. The assembler next looks for the filename or path given, and if this file is found, it is read and assembled as if it was the beginning of the Source file. All lines from this file are numbered 0, and no warning or error occurs if the file is not found (unless, of course, you were depending on these definitions in your program, then you could have lots of error messages.) Beware when building this file that the null character must be at the end of the pathname or you may crash the system. You can create a file from the keyboard using the command: COPY con: to Asm68k.cnf then typing a character for the pagelength (B is 66, the standard), following it with the pathname for the startup file, followed with a control@ (CTRL key and 2 key together), then ending it with a control\ (CTRL and \ keys together.) If you make a mistake, you cannot edit the file, so do the control\ and start over. =============================================================================== Invoking the Assembler: The assembler is only designed to be run from the CLI interface. If you don't know how to find the CLI interface, read the manuals that came with the machine before trying to use this program. The minimum invocation must be the program name Asm68k followed with a source filename (separated by at least one space from the program name.) This will yield an assembly, with an object file output in the AMIGA format, and a listing file. The filenames for these files will be created by stripping any extension (period followed by characters) from the source filename and appending .o for the object filename and .lst for the listing filename. Any error messages will list to the screen. Example: Asm68k MyProgram.a Outputs: MyProgram.o (The relocatable binary object file) MyProgram.lst (A combined source and hex object file) If this isn't what you want, a wide variety of "switches" are supported to control the usage of the assembler, and the descriptions follow: (A switch is a parameter you type after the program name and source filename, with an intervening space. These switches all start with the minus sign '-' and may be followed immediately by a letter or letters as shown below.) -O Causes the OBJECT file to be generated (this is a default value.) It may be followed immediately with a filename containing no spaces, or type a space and then enclose the filename in double quotes if it contains spaces. You may also use the intervening space without quotes on a filename without spaces if you like. A given object filename will be used instead of the default filename normally used. -L Causes the LISTING file to be generated (also a default.) The usage is just like the -O switch. -E Causes ERROR messages to list to the named file. Use like above. On this switch, if no filename is given, a default filename will be formed like the object and listing names, using the extension .err -V VERIFICATION file. Another name for the -E switch. -H HEADER file. Causes a search for the filename given after the switch (as above) which will be read as a source file before the source file is read (but after the initialization file, if enabled.) Just like the initialization file, if the file is not found, no warning or error is issued directly. All the source from this file will also be numbered as line 0. -I An INCLUDE directory search path list should follow this switch and should contain directory names (no spaces allowed) separated from each other with plus signs '+', commas or spaces. If spaces are used, then you must space the list off from the switch and enclose the entire list in double quotes. Use of this switch will cause the assembler to search for an INCLUDE file in each of the named directories if it is not found in the current one. -X This switch should be followed immediately with up to 6 characters, and will cause the default object filename to be formed by stripping the extension and appending a period and the characters following the X. -C This switch has been included for compatability. It should be followed with only the following characters, as many as wanted, with no spaces: S Generates a symbol table at the end of the list file (this is a default value.) D Does nothing. C Causes Case of all Labels and symbols to be ignored. With this switch activated, LABEL, Label and label will all be interpreted as the same name. This is not the default. X Does nothing. -N This switch turns things off (NO.) Like -C, you should follow it with a series of letters from the following list, without any spaces: S Turns off the SYMBOL table normally produced at the end of the listing file. L Stops the LISTING file from being generated. E Inhibits the ERROR file, if you turned it on. V A synonym for the E switch above. P Inhibits the PAGINATION of the listing file. O Inhibits the OBJECT file generation. Q Inhibits the conversion of mnemonics to QUICK form. The default is to convert allowable values of ADD and SUB to the quick form if it is safe (values already defined.) X Keeps the assembler from stripping the eXten- sion from the source filename when forming default filenames. R Causes the assembler to generate the object code in a non-RELATIVE format. The format used is the Intel format, and the program counter is only output to 16-bits of significance. No symbol or relocation infor- mation is output, and no linker or loader is available to operate on this format. > The right bracket, followed immediately with a filename, will cause the signon, progress and all error messages to be diverted by AmigaDOS to the named file when it is the first parameter after the program name. If it is not the first, the assembler will send the error messages to the named file. All the above switches may be used in either UPPER or lower case, and will generate the same results. The source filename should be the first parameter after the program name, but only to avoid confusion. It must be the only parameter not associated with a switch, and may not be given twice. The source filename is the only mandantory command-line parameter. ============================================================================== Other notes on use: Case is normally significant on Symbols, Labels and Macro names unless the -CC switch is used. The Directives, Mnemonics and special symbols will be recognized in any mixture of UPPER and lower case. The only truly reserved symbols are the following: NARG MACRO ENDMAC ENDM A0 A1 A2 A3 A4 A5 A6 A7 D0 D1 D2 D3 D4 D5 D6 D7 SP CCR USP SR PC All the other special Symbols, Mnemonics and Directive names may be defined and used as Labels, or may be implemented as Macros, but be careful when doing this to avoid circular references, which will not be detected until the Macro nesting level is exceeded, or a write error results from the disk being full. For example, if you redefine JSR as a Macro, and want to use it in the Macro definition, don't call the assembler with the -CC switch, and be sure to use a different case within the Macro text to get the assembler to recog- nize the Mnemonic, which is case-insensitive, from the Macro name. This allows the maximum flexibility for the assembler, with only a minimum of care from the programmer. ============================================================================== Error Messages: The assembler uses as much logic as possible to generate a line of code in spite of erroneous input. If a reliable evaluation can be made, a source line will be interpreted regardless of errors, however some of these lines may not be what you meant. Even the little bit of DWIM in this assembler occupies a lot of code space. Because assembly of erroneous lines is attempted where possible, you may find multiple error messages referring to the same line. The listing file will only contain the first error detected, however the screen list or error file will also list the errors in the order they were detected. Some errors may generate errors later, especially if typing errors cause the assembler to find an item it thinks is an undefined symbol in an expression, and you later used this symbol for another purpose. The following is a list of error messages, and explanations: 1: Error in Expression Value The expression being evaluated contained some garbage. 2: Duplicate Line Label An attempt at defining a Label twice was detected. 3: Undefined Label in Expression The symbol or label used in the expression was not defined anywhere in the source file. 4: Syntax Error The assembler could make no sense of what you were trying to tell it to do. 5: Operand Too Large The operand was greater than the value allowed for the operation being performed. 6: Invalid Register Specified The register called for in the current operation and what was found are not compatable. 7: Undefined Mnemonic or Command An item in the Mnemonic field is not a defined Macro or valid mnemonic or directive. May also be caused by using a label outside of column one without a colon following it. 8: Improper use of Unary Operator A Unary operator ('-' or '~') was found right after another math operator. The expression evaluator cannot handle this, so it is ignored and this message is output. 9: Operation Involves Division by Zero A Division or Modulo operation was attempted where the right hand value was zero or undefined. The result of this operation is set to zero. 10: Too Many Right Parentheses More right parentheses were found than left parentheses. 11: Missing Right Parenthesis More left parentheses were used than right parentheses. 12: Too Many Parenthesis Levels More than 16 levels of parentheses were attempted to be opened. 13: Invalid Character in Expression A character was found in the expression that is not any of the defined mathops, numbers, symbol characters or newline characters. 14: Closing Quote for Character Constant Absent No closing quote on a single character constant was found. Also caused by attempts to define multiple-character constants in an expression. 15: Operand Field Missing An operand was needed, and was not there. 16: Bit Operand Required The expression needs a bit operand, and what was found was not of the required type. 17: Invalid Bit Specified The data found cannot be used legally to specify a bit. 18: Immediate (#) Operand Needed The data given was not preceded by the '#' (pound) sign, and needed to be. 19: Branch or Jump Out-of-Range The address evaluated is outside of the range allowable for the branch of jump mnemonic specified. ** Run from CLI Interface ** The message output when no command-line was used (as from the workbench. A Fatal error. ** Command Line Required ** The message output when no arguments are present on the command-line (you need at least the source filename.) Also a Fatal error. ** Unrecognized Switch ** A switch or a character within a switch was not one of the valid switches. Not a Fatal error. ** File Write Error ** An error occurred during a file write, as reported from AmigaDOS. A Fatal error. May be caused by a full disk. ** Source Filename Missing ** The source filename was not present or was corrupt or was given twice. A Fatal error. ** Parameter Too Long ** An Item on the command-line was too long to be evaluated. Also Fatal. ** Insufficient Free Memory ** This error occurs when the memory pool does not contain enough memory in a size large enough for the request from the assembler to be filled. Execution stops immediately. ** Include Files nested too deep ** This error occurs when you try to open the ninth Include file before closing one. ** Couldn't open Source file ** AmigaDOS did not return information indicating that the source file was ready to be read from (or it isn't there.) No assembly will take place without a source file. ** Error Closing Source file ** Another error was reported when the source file was being closed. ** Couldn't open Object file ** A Dos error occurred trying to open the object file. ** Couldn't open Listing file ** Same error from listing file open attempt. ** Couldn't open Error listing file ** Like above, but on error file attempt. ** ENDMAC Command missing ** The end of the source file was reached, and the assembler was still saving a macro definition. 34: Too Many Parameters present More parameters than the assembler has space to store were found. 35: Parameter Too Long An item in an expression or an operand was longer than the defined limit. 36: Closing Single-Quote Missing A string definition should be bounded on both ends with matching quotes. 37: No Label on Line No label was present for the Directive to act upon. 38: Macro called using Symbol label A symbol name found in the mnemonic field was attempted to be used as a Macro, and was found to be a Label. ** Too many nested Macros ** This Fatal error occurs when the ninth Macro call is issued before any of the previous Macro calls have ended. 40: Macro redefinition Error The name used with the MACRO command is already the name of a previously defined Macro. 41: ENDMAC command without MACRO definition You didn't use the MACRO command to define your Macro, or you issued the ENDMAC command twice. If you are attempting to get two or more exit points from a macro, use the MEXIT Directive. ** INCLUDE file unable to be opened ** This Error occurs when the filename associated with the INCLUDE command was not found after the include directory list was exhausted. ** Source or Include file line too long ** An input line read from disk contained more than 255 characters in a row without a carriage return or linefeed. 44: Insufficient Macro parameters supplied An expansion was attempted and there were not enough parameters on the Macro call line. 45: Label Value changed between passes This unusual error occurs when the value of a Line Label is different on the second pass than it was on the first pass. The whole assembly file is probably corrupt, and it is likely that the message will repeat with every subsequent Line Label found. Forward references and absolute references to SETVAL Labels, or conditional compilation based on SETVAL Labels are the likely culprits behind this error. 46: Invalid Label - Item was Forward Referenced A Label which was referenced before it was used was later found in a context other than usage as a relative location. 47: Local Definition of External Symbol not allowed If you declared a Symbol to be EXTERNal, you cannot define it within the current assembly. Use the ENTRY Directive instead if this is what you want. 48: Unavailable Addressing Mode Used The addressing mode used for the Mnemonic on this line is not one which is allowable for that Mnemonic. 49: Invalid Item in External Reference Expression An external reference included an item which did not belong there. This also occurs on an attempt to generate PC relative references to external addresses. ** Too Many Section Definitions (Limit = 255) ** The message is self-explanatory. 51: Invalid Section Type - Section CODE used An item found after the section name was not one of the three valid section types - CODE, DATA or BSS. The type was set to CODE. 52: Instruction Alignment Error - Pad Byte Added All the 68000 Mnemonics and WORD and LONG oriented Directives need to be aligned on an even address. The Assembler attempts to correct this by adding a null byte to the previous instruction, and adjust the Program Counter and Label values accordingly. ** Too Many Conditional Levels Attempted The seventeenth conditional Directive was found before an ENDIF Directive was. ** Conditional End without Conditional Statement There are more ENDIF commands than matching conditional Directives. 55: Relative Reference Outside of Current Section An attempt to use a PC relative mode to a Line Label that was not declared as an ENTRY label was attempted. Also occurs on Data references to other sections without using the ENTRY type-definition. 56: Executable Code not allowed in Data & Bss Sections DATA sections may contain only initialized and uninitialized data locations, and BSS sections may contain only un- initialized (RESERVE) data. 57: Redefinition of Equate Label not Allowed You cannot change the value of a Label that has been EQUATEd. 58: Equate to previously SET Label Disallowed A Label that was set cannot later be upgraded to an equate in the same assembly. The assembler handles decisions on equated labels, whose value cannot change, differently than set labels, whose value may be redefined. Since the length of 68000 instructions vary with the address mode, a set label is always treated as a LONG value (unless otherwise specified) and an equated label is treated for the value it contains. Since the assembler always attempts to use the shortest instruction length possible, a change in the type of a label can cause bad code to be generated. =============================================================================== Addressing Modes: The following models show the valid address modes for the 68000 processor as they are recognized by the assembler: ( 'n' represents a digit from 0 to 7, X represents either 'D' or 'A' for an address mode 'ALabel' represents a symbol with an absolute or an external value, 'RLabel' represents a Line Label or an ENTRY typed label, 'number' refers to an actual numerical value, and the other items are what they are. Case is not significant except on Label and Symbol Names. Defined REG Labels of the proper type may be used in place of the register names.) IMMEDIATE: #number #ALabel DATA REGISTER DIRECT: Dn ADDRESS REGISTER DIRECT: An SP ADDRESS REGISTER INDIRECT: (An) (SP) ADDRESS REGISTER INDIRECT WITH POST INCREMENT: (An)+ (SP)+ ADDRESS REGISTER INDIRECT WITH PREDECREMENT: -(An) -(SP) ADDRESS REGISTER INDIRECT WITH DISPLACEMENT: number(An) number(SP) ALabel(An) ALabel(SP) ADDRESS REGISTER INDIRECT WITH DISPLACEMENT AND INDEX: (say that 50 times) number(An,Xn) Alabel(An, Xn) number(SP, Xn) ALabel(SP,Xn) PROGRAM COUNTER RELATIVE WITH DISPLACEMENT: RLabel RLabel(PC) number(PC) PROGRAM COUNTER RELATIVE WITH DISPLACEMENT AND INDEX: RLabel(Xn) RLabel(PC, Xn) number(PC, Xn) SHORT ABSOLUTE: ALabel number (where the value is less than $007FFF or greater than $FF8000) LONG ABSOLUTE: RLabel (to another section) ALabel number (where the value doesn't qualify for short mode) SPECIAL: USP CCR SR =============================================================================== Release History: Version 1.0.1 Alpha1 released 02-Jan-87. Version 1.0.1 Beta1 released 11-Jan-87. Changes: 1. EQUATEd & SETVAL Labels now use their full 32-bit value in expressions. 2. External 16-bit references are now handled correctly (for those open-library calls.) 3. Macro Parameters now parse correctly when separated by commas. 4. The REG and EQUR functions were swapped. Version 1.0.1 Beta2 released 20-Jan-87. Changes: 1. Conditional levels were increased to 16. 2. The include directory spec switch was changed to handle logical assignments correctly (e.g. INCLUDE: now works.) 3. DBcc and Bcc branches to an ENTRY Label no longer generate an error. 4. IFD and IFND did not function properly with SET or EQUATED Labels. 5. The assembler now passes external reference information for the linker on EXTERN items used as immediate operands. 6. Several heavily used routines were rewritten in assembly language and assembled with this program. =============================================================================== NOTE: Amiga and AmigaDOS are trademarks of Commodore Business Machines. Intel is a trademark of the Intel Co. MC68000 is a trademark of Motorola Co. =============================================================================== <*|=|*> THE END <*|=|*> ==============================================================================