MAC/65 TABLE OF CONTENTS Introduction Start Up Warm Start Back up Copy Syntax Chapter 1 -- The Editor 1.1 General Editor Usage 1.2 TEXT Mode 1.3 EDIT Mode Chapter 2 -- Editor Commands 2.1 ASM 2.2 BLOAD 2.3 BSAVE 2.4 BYE 2.5 C (Change Memory) 2.6 D (Display Memory) 2.7 DEL 2.8 DOS 2.9 ENTER 2.10 FIND 2.11 LIST 2.12 LOAD 2.13 LOMEM 2.14 NEW 2.15 NUM 2.16 PRINT 2.17 REN 2.18 REP 2.19 SAVE 2.20 SIZE 2.21 TEXT 2.22 ? (hex/dec convert) Chapter 3 -- The Macro Assembler 3.1 Assembler Input 3.2 Instruction Format 3.3 Labels 3.4 Operands 3.5 Operators 3.6 Assembler Expressions 3.7 Operator Precedence 3.8 Numeric Constants 3.9 Strings Chapter 4 -- Directives 4.1 *= 4.2 = 4.3 .= 4.4 .BYTE (and .SBYTE) 4.5 .CBYTE 4.6 .DBYTE 4.7 .ELSE 4.8 .END 4.9 .ENDIF 4.10 .ERROR 4.11 .FLOAT 4.12 .IF 4.13 .INCLUDE 4.14 .LOCAL 4.15 .OPT 4.16 .PAGE 4.17 .SBYTE (see also .BYTE) 4.18 .SET 4.19 .TAB 4.20 .TITLE 4.21 .WORD Chapter 5 -- Macro Facility 5.1 .ENDM 5.2 .MACRO 5.3 Macro Expansion, part 1 5.4 Macro Parameters 5.5 Macro Expansion, part 2 5.6 Macro Strings 5.7 Some Macro Hints 5.8 A complex Macro Example Chapter 6 -- Compatibility 6.1 Atari's Cartridge Chapter 7 -- Error Descriptions INTRODUCTION This manual assumes the user is familiar with assembly language. It is not intended to teach assembly language. This manual is a reference for commands, statements, functions, and syntax conventions of MAC65. It is also assumed that the user is familiar with the screen editor of the Atari or Apple II computer, as appropriate. Consult Atari's or Apple's Reference Manuals if you are not familiar with the screen editor. If you need a tutorial level manual, we would recommend that you ask your local dealer or bookstore for suggestions. Two books that have worked well for many of our customers are "Machine Language for Beginners" by Richard Mansfield from COMPUTE! books and "Programming the 6502" by Rodney Zaks. This manual is divided into two major sections; the first two chapters cover the Editor commands and syntax, source line entry, and executing source program assembly. The next three chapters then cover instruction format, assembler directives, functions and expressions, Macros, and conditional assembly. MAC65 is a fast and powerful machine language development tool. Programs larger than memory can be assembled. MAC65 also contains directives specifically designed for screen format development. With MAC65's line entry syntax feature, less time is spent re-assembling programs due to assembly syntax errors, allowing more time for actual program development. START UP Power up the disk drive(s) and monitor, leave the computer off. Insert MAC65 disk in drive #1 and boot system by turning the computer on. This will load and execute DOS XL. Now enter MAC65 (return). This loads and executes MAC65, the Editor/Macro Assembler. Refer to the DOS XL Manual for other capabilities. WARM START The user can exit to DOSXL by entering the MAC65 command CP (return) or by pressing the System Reset key. To return to MAC65, the user can use the DOSXL command RUN (return). This "warm starts" MAC65 and does not clear out any source lines in memory. BACK-UP COPY Please do not work with your master disk! Make a back-up copy with DOSXL. Consult the DOSXL reference manual for specific instructions. Keep your master copy in a safe place. SYNTAX The following conventions are used in the syntax descriptions in this manual: 1. Capital letters designate commands, instruction, functions, etc., which must be entered exactly as shown (e.g. ENTER, .INCLUDE, .NOT). 2. Lower case letters specify items which may be used. The various types are as follows: 1no - Line number between 0-65535, inclusive. hxnum - A hex number. It can be address or data. Hex numbers are treated as unsigned integers. dcnum - A positive number. Decimal numbers are rounded to the nearest two byte unsigned integer; 3.5 to 3.9 is rounded to 4 and 100.1 to 100.4 is rounded to 100. exp - An assembler expression. string - A string of ASCII characters enclosed by double quotes (eg. "THIS IS A STRING"). strvar - A string representation. Can be a string as above, or a string variable within a Macro call (eg. %$1). filespec - A string of ASCII characters that refers to OR refers to a particular device. See device file reference manual for more specific explanation. 3. Items in square brackets denote an optional part of syntax (eg. [,1no]). When an optional item is followed by (...) the item(s) may be repeated as many times as needed. Example: .WORD exp [,exp ...] 4. Items in parentheses indicate that any one of the items may be used, eg. (.Q) (,A). CHAPTER 1: THE EDITOR The Editor allows the user to enter and edit MAC/65 source code or ordinary ASCII text files. To the Editor, there is a real distinction between the two types of files; so much that there are actually two modes accessible to the user, EDIT mode and TEXTMODE. However, for either mode, source code/text must begin with a line number between 0 and 65535 inclusive, followed by one space. Examples: 10 LABEL LDA #$32 3020 This is valid in TEXT MODE The first example would be valid in either EDIT or TEXTMODE, while the second example would only be valid in TEXTMODE. The user chooses which mode he/she wishes to use for editing by selecting NEW (which allows general text entry). There is more discussion of the impact of these two modes below; but, first, there are several points in common to the two modes. 1.1 GENERAL EDITOR USAGE The source file is manipulated by Editor commands. Since the Editor recognizes a command by the absence of a line number, a line beginning with a line number is assumed to be a valid source/text line. As such, it is merged with, added to, or inserted into the source/text lines already in memory in accordance with its line number. An entered line which has the same line number as one already in memory will replace the line in memory. Also, as a special case of the above, a source line can be deleted from memory by entering its line number only. (And also see DEL command for deleting a group of lines.) Any line that does not start with a line number is assumed to be command line. The Editor will examine the line to determine what function is to be performed. If the line is a valid command, the Editor will execute the command. The Editor will prompt the user each time a command has been executed or terminated by printing: EDIT for syntax (MAC/65 source) mode TEXTMODE for text mode The cursor will appear on the following line. Since some commands may take a while to execute, the prompt signals the user that more input is allowed. The user can terminate a command before completion by hitting the break key (escape key on Apple II). And one last point: If the line is neither a source line or a valid command. The Editor will print: What? 1.2 TEXT MODE The Editor supports a text mode. The text mode is entered with the command TEXT. This mode will NOT syntax check lines entered, allowing the user to enter and edit non-assembly language files. All Editor commands function in text mode. Remember, though, that all text lines must begin with a line number; and, even in TEXTMODE, the space following the line number is necessary. 1.3 EDIT MODE MAC/65 is nearly unique among assembler/editor systems in that it allows the assembly language user to enter source code and have it IMMEDIATELY checked for syntax validity. Of course, since assembly language syntax is fairly flexible (especially when macros are allowable, as they are with MAC/65), syntax checking will by no means catch all errors in user source code. For example, the existence of and validity of labels and/or zero page locations is not and can not be checked until assembly time. However, we still feel that this syntax checking will be a boon to the beginner and experienced programmer alike. Again, remember that source lines must begin with a line number which must, in turn, be followed by one space. Then, the second space after the line number is the label column. The label must start in this column. The third space after the line number is the instruction column. Instructions may either start in at least the third column after the line number or at least one space after the label. The operand may begin any where after the instruction, and comments may begin any where after the operand or instruction. Refer to Assembler Section for specific instruction syntax. As noted, the Editor syntax checks each source line at entry. If the syntax of a line is in error, the Editor will list the line with a cursor turned on (i.e., by using an inverse or blinking character) at the point of error. The source lines are tokenized and stored in memory, starting at an address in low memory and building towards high memory. The resultant tokenized file is 60% to 80% smaller than its ASCII counterpart, thus allowing larger programs to be entered and edited in memory. SPECIAL NOTE: If, upon entry, a source line contains a syntax error and is so flagged by the Editor, the line is entered into Editor memory anyway. This feature allows raw ASCII text files (possibly from other assemblers and possibly containing one or several syntax errors as far as MAC/65 is concerned) to be ENTERed into the Editor without losing any lines. The user can note the lines with errors and then edit them later. CHAPTER 2: EDITOR COMMANDS This chapter lists all the valid Editor-level commands, in alphabetical order, along with a short description of the purpose and function of each. Again, remember that when the "TEXTMODE" or "EDIT" prompt is present any input line not preceded by a line number is presumed to be an Editor command. If in the process of executing a command any error is encountered, the Editor will abort execution and return to the user, displaying the error number and descriptive message of the error before re-prompting the user. Refer to Appendix for possible causes of errors. Section 2.1 edit command: ASM purpose: ASseMble MAC/65 source files usage: ASM [#file1],[#file2],[#file3],[#file4] ASM will assemble the specified source file and will produce a listing and object code output; the listing may include a full cross reference of all non-local labels. File1 is the source device, file2 is the list device, file3 is the object device, and file4 is a temporary file used to help generate the cross reference listing. Any or all of the four filespec's may be omitted, in which case MAC/65 assumes the following default filespec(s) are to be used: file1 - user source memory file2 - screen editor. file3 - memory (CAUTION: see below) file4 - none, therefore no cross reference A filespec (#file1, #file3, etc.) can be omitted by substituting a comma in which case the respective default will be used. Example: ASM #D2:SOURCE,#D:LIST,#D2:OBJECT In this example, the source will come from D":SOURCE, the assembler will list to D:LIST, and the object code will be written to D":OBJECT. Example: ASM #D:SOURCE ,,#D:OBJECT In this example, the source will be read from D:SOURCE and the object will be written to D:OBJECT. The assembly listing will be written to the screen. Example: ASM , #P: ,,#D:TEMP In this example, the source will be read from memory, the object will be written to memory (but ONLY if the ".OPT OBJ" directive is in the source), and the assembly listing will be written to the printer along with the complete label cross reference. The file TEMP on disk drive 1 will be created and used as a temporary file for the cross reference. Example: ASM #D:SOURCE .#P: In this example, the source will be read from D:SOURCE and the assembly listing will be written to the printer. If the ".OPT OBJ" directive has been selected in the source, the object code will be placed in memory. Note: If assembling from a "filespec", the source MUST have been a SAVEd file. Note: Refer to the .OPT directive for specific information on assembler listing and object output. Note: The object code file will have the format of compound files created by the DOSXL SAVE command. See the DOSXL manual for a discussion of LOAD and SAVE file formats. Section 2.2 edit command: BLOAD purpose: allows user to LOAD Binary (memory image) files from disk into memory usage: BLOAD #filespec The BLOAD command will load a previously BSAVEd binary file, an assembled object file, or a binary file created with DOSXL SAVe command. Example: BLOAD #D:OBJECT This example will load the binary file "OBJECT" to memory at the address where it was previously saved from or assembler for. CAUTION: it is suggested that the user only BLOAD files which were assembled into MAC/65's free area (as shown by the SIZE command) or which will load into known safe areas of memory. Section 2.3 edit command: BSAVE purpose: SAVE a Binary image of a portion of memory. Same as DOSXL SAVE command usage: BSAVE #filespec < hxnum1 ,hxnum2 The BSAVE command will save the memory addresses from hxnum1 through hxnum2 to the specified device. The binary file created is compatible with the DOSXL SAVe command. Example: BSAVE #D:OBJECT<5000,5100 This example will save the memory addresses from $5000 through $5100 to the file "OBJECT". Section 2.4 edit command: BYE purpose: exit to system monitor level usage: BYE BYE will put the user to the Atari Memo Pad or Apple II monitor, as appropriate. Section 2.5 edit command: C purpose: Change memory contents usage: c hxnum1 < (,)(hxnum) [(,)(,hxnum) ...] Although MAC/65 does not included a debug capability, there are a few machine level commands included for the convenience of the user who would, for example, like to change system registers and the like (screen color, margins, etc.). The C command is provided for this purpose. C allows the user to modify memory. Hxnum1 is the change start address. The remaining hxnum(s) are the change bytes. The comma will skip an address. Example: C 50000<20,00,D8,,5 The example will change the memory addresses as follows: 5000 to 20, 5001 to 00, 5002 to D8, skip 5003, and change 5004 to 5. Section 2.6 edit command: D purpose: Display contents of memory location(s) usage: D hxnum1 [ ,hxnum2 ] D allows the user to examine memory. If hxnum2 is specified, the memory locations between hxnum1 and hxnum2 will be displayed, else only hxnum1 through hxnum1 +8 will be displayed. Section 2.7 edit command: DEL purpose: DELetes a line or group of lines from the source/text in memory. usage: DEL 1nol [ ,1no2 ] DEL deletes source lines from memory. If only one 1no is entered, only the line will be deleted. If two 1nos are entered, all lines between and including 1no1 and 1no2 will be deleted. Note: 1no1 must be present in memory for DEL to execute. Section 2.8 edit command: DOS [ or, equivalently, CP ] purpose: exit from MAC/65 to the CP of DOS XL. usage: DOS or CP Either DOS or CP returns the user to DOSXL. Section 2.9 edit command: ENTER purpose: allow entry of ASCII (or ATASCII) text files into MAC/65 editor memory usage: ENTER #filespec [ (,M) (,A) ] ENTER will cause the Editor to get ASCII text from the specified device. ENTER will clear the text area before entering from the filespec. That is any user program is memory at the time the ENTER command is given will be erased. The parameter "M" (MERGE) will cause MAC/65 to NOT clear the text area before entering from the file, text entered will be merged with the text in memory. If a line is entered which has the same line number of a line in memory, the line from the device will overwrite the line in memory. The parameter "A" allows the user to enter un-numbered text from the specified device. The Editor will number the incoming text starting at line 10, in increments of 10. CAUTION: The "A" option will always clear the text area before entering from the filespec. Section 2.10 edit command: FIND purpose: to FIND a string of characters some where in MAC/65's editor buffer. usage: FIND / string/ [ 1no1 [ ,1no2 ] ] [ ,A ] The FIND command will search all lines in memory or the specified line(s) (1no1 through 1no2) for the "string" given between the matching delimiter. The delimiter may be any character except a space. If a match is found, the line containing the match will be listed to the screen. Note: do NOT enclose a string in double quotes. Example: FIND/LDX/ This example will search for the first occurance of "LDX". Example: FIND\Label\25,80 This example will search for the first occurance of "Label" in lines 25 through 80. If the option "A" is specified, all matches within the specified line range will be listed to the screen. Remember, if no line numbers are given, the range is the entire program. Section 2.11 edit command: LIST purpose: to LIST the contents of all or part of MAC/65's editor buffer in ASCII (ATASCII) form to a disk or device. usage: LIST [ #filespec, ] [ 1no1 [ ,1no2 ] ] LIST lists the source file to the screen, or device when "#filespec" is specified. If no 1nos are specified, listing will begin at the first line in memory and end with the last line in memory. If only 1no1 is specified, that line will be listed if it is in memory. If 1no1 and 1no2 are specified, all lines between and including 1no1 and 1no2 will be listed. When 1no1 and 1no2 are specified, neither one has to be in memory as LIST will search for the first line in memory greater than or equal to 1no1, and will stop listing when the line in memory is greater than 1no2. EXAMPLE: LIST #P: will list the current contents of the editor memory to the P: (printer) device. EXAMPLE: LIST #D2:TEMP, 1030, 1000 lists only those lines lying in the line number range from 1030 to 1800, inclusive, to the disk file named "TEMP" on disk drive 2. NOTE: The second example points out a method of moving or duplicating large portions of text or source via the use of temporary disk files. By suitably RENumbering the in-memory text before and after the LIST, and by then using ENTER with the Merge option, quite complex movements are possible. Section 2.12 edit command: LOAD purpose: to reLOAD a previously SAVEd MAC/65 token file from disk to editor memory. usage: LOAD #filespec [ ,A ] LOAD will reload a previously SAVEd tokenized file into memory. LOAD will clear the user memory before loading from the specified device unless the ",A" parameter is appended. The parameter "A" (for APPEND) causes the Editor to NOt clear the text area before loading from the file. Instead, the load file will be appended with the current file in memory. Note: The Append option will NOT renumber the file after loading. It is possible to have DUPLICATE LINE NUMBERS. Use the REN command if there are duplicate line numbers. Section 2.13 edit command: LOMEM purpose: change the lower bound of editor memory usable by MAC/65. usage: LOMEM hxnum LOMEM allows the user to select the address where the source program begins. Executing LOMEM clears out any source currently in memory; as if the user had typed "NEW". Section 2.14 edit command: NEW purpose: clears out all editor memory, sets syntax checking mode. usage: NEW NEW will clear all user source code from memory and reset the Editor to syntax mode. The "EDIT" prompt appears, reminding the user that syntax checking is new active. If the user needs to defeat the syntax checking, he/she must use the TEXT command. Section 2.15 edit command: NUM purpose: initiates automatic line NUMbering mode usage: NUM [ dcnum1 [ ,dcnum2 ] ] NUM will cause the Editor to auto-number the incoming text from the Screen Editor (E:). A space is automatically printed after the line number. If no dcnums are specified, NUM will start at the last line number plus 10. NUM dcnum1 will start at the last line number plus "dcnum1" in increments of "dcnum1". NUM dcnum1". NUM dcnum1, dcnum2 will start at "dcnum1" in increments of "dcnum2". EXAMPLE: NUM 1000,20 will cause the Editor to prompt the user with the number "1000" followed by a space. When the user has entered a line, the next prompt will be "1020", etc. The NUM mode will terminate if the line number which would be next in sequence is present in memory. The user may terminate NUM mode on the Atari by pressing the BREAK key or by typing a CONTROL-3. On the Apple, the user may terminate the NUM mode by pressing CONTROL-C followed by RETURN. Section 2.16 edit command: PRINT purpose: to PRINT all or part of the Editor text or source to a disk file or a device. usage: PRINT [ #filespec, ] [ 1no1 [ ,1no2 ] ] Print is exactly like LIST except that the line numbers are not listed. If a file is PRINTed to a disk, it may be reENTERed into the MAC/65 memory using the ENTER command with the Append line number option. Section 2.17 edit command: REN purpose: RENumber all lines in Editor memory. usage: REN [ dcnum1 [ ,dcnum2 ]] REN renumbers the source lines in memory. If no dcnums are specified, REN will renumber the program stating at line 10 in increments of 10. REN dcnum1 will renumber the lines starting at line 10 in increments of dcnum1. REN dcnum1, dcnum2 will renumber starting at dcnum1 in increments of dcnum2. Section 2.18 edit command: REP purpose: REPlaces occurrence(s) of a given string with another given string. usage: REP/old string/new string/ [1no1 [,1no2 ]] [(,A)(,Q)] The REP command will search the specified lines (all or 1no1 through 1no2) for the "old string" The "A" option will cause all occurrences of "old string" to be replaced with "new string". The "Q" option will list the line containing the match and prompt the user for the change (Y followed by RETURN for change, RETURN for skip this occurance.) If neither "A" or "Q" is specified, only the first occurrence of "old String" will be replaced with "new string". Each time a change is made, the line is listed. Example: REP/LDY/LDA/100,250,Q This example will search for the string "LDY" between the lines 200 and 250, inclusive, and prompt the user at each occurrence to change or skip. Note: Hitting BREAK (ESCape on Apple Ii) will terminate the REP mode and return to the Editor. Note: If a change causes a syntax error in the line, the REP mode will be terminated and control will return to the Editor. Of course, if TEXTMODE is selected, there can be no syntax errors. Section 2.19 edit command: SAVE purpose: SAVEs the internal (tokenized) form of the user's in-memory text/source to a disk file. usage: SAVE #filespec SAVE will save the tokenized user source file to the specified device. The format of a tokenized file is as follows: File Header Two byte number (LSB,MSB) specifies the size of the file in bytes. For each line in the file: Two byte line number (LSB,MSB) followed by One byte length of line (actually offset to next line) followed by The tokenized line Section 2.20 edit command: SIZE purpose: determines and displays the SIZE of various portions of memory used by the MAC/65 Editor. usage: SIZE SIZE will print the user LOMEM address, the highest used memory address, and the highest usable memory address, in that order, using hexadecimal notation for the addresses. Section 2.21 edit command: TEXT purpose: allow entry of arbitrary ASCII (ATASCII) text without syntax checking. usage: TEXT TEXT will clear all user source code from memory and put the Editor in the textmode. After this command is used, the Editor will prompt the user for new commands and text with the word "TEXTMODE" (instead of "EDIT"), indicating that no syntax checking is taking place. TEXTMODE may be terminated by the NEW command. CAUTION: there is no way to go back and forth between syntax (EDIT) mode and TEXTMODE without clearing the Editor's memory each time. Section 2.22 edit command: ? purpose: makes hexadecimal/decimal conversions usage: ? ($hxnum) (dcnum) ? is the resident hex/decimal decimal/hex converter. Numbers in the range 0 - 65535 decimal (0000 to FFFF hex) may be converted. Example: ? $1200 will print =4600 ? 8190 will print =$1FFE CHAPTER 3: THE MACRO ASSEMBLER Usually, the Assembler is entered from MAC/65 with the command ASM. For ASM command syntax, refer to section 2.1 (in the Editor commands). Assembly may be terminated by hitting the BREAK key (ESCape key on the Apple II). However, MAC/65 also offers the DOSXL command line level an optional ability to bypass the Editor phase entirely. This is especially useful when doing assemblies during the processing of an EXeCution file. To invoke the assembler directly, simply include one or more file names on the same DOSXL command line as the "MAC65" command. The formal usage is as follows: MAC65 [file1 [file2 [file3 [file4 ] ] ] [-A][-D] ] where "file1", "file2", "file3" and "file4" are legal DOSXL file or device names and "-A" and "-D" are option specifiers. Thus the arguments re an optional set of one to four filenames, construed to be the source, listing, object, and cross-reference files (respectively) of a MAC/65 assembly. And the options avaliable are: -A source file is Ascii -D assembly must be Disk-to-Disk Remember, if no filenames are given, MAC/65 will be invoked in its interactive (Editor) mode. But, if one or more files are specified, MAC/65 will be invoked in its "batch" mode. That is, it will perform a single assembly and then return to DOSXL. Generally, this command line will perform the assembly in a manner equivalent to giving the "ASM" command from the MAC/65 Editor. That is, if only one filename is given, it is assumed to be the source file, implying that the listing will go to the screen and the object code will be placed in memory (but only if requested by the .OPT OBJ directive). If a second filename is given, it is assumed to be the name of the listing file. Only if three or four filenames are given will the object code be directed to the file specified. And, finally, if the fourth filename is given it must be a disk filename and will be used as a temporary file for the cross reference listing. Note: if an assembly needs no listing but does need an object file, the user may specify "-" as the listing file. And some notes on the options: The -A option is used to specify that the source file is not a standard MAC/65 SAVEd file but is instead an Ascii (or Atascii) file. This is equivalent to using the interactive Editor mode of MAC/65 to use the sequence of commands "ENTER #D..." and "ASM ,...". The -D option is used to specify that the assembly MUST proceed form disk to disk. If this option is not given, the source file is LOADed (or ENTERed) before the assembly, and then the assembly proceeds with the source in memory (generally producing improved speed of assembly). If, however, the source file is too large to be assembled in memory, the user may use this option to allow assembly of even very large programs. (And remember, even if the source fits, the macro and symbol tables must reside in memory during assembly also.) NOTE: the -D option can NOT be used in conjunction with the -A option. The source file assembled under the -D option MUST be a properly SAVEd (tokenized) file. EXAMPLES: MAC65 JUNK.M65 - JUNK.COM will assemble JUNK.M65, producing no listing but sending the object code to the file JUNK.COM MAC65 TEST.LIS P: TEST.OBJ TEST.XRF will assemble TEST,LIS, which is an ASCII file, sending the listing to the printer (P:) and the object to the file TEST.OBJ. A cross reference of all labels will be appended to the printer listing, and the file TEST.XRF will be used by MAC/65 as a temporary file for this purpose. 3.1 ASSEMBLER INPUT The Assembler will get a line at a time from the specified device or from memory. If assembling from a device, the file must have been previously SAVEd by the Editor. All discussions of source lines and syntax will be at the Editor line entry level. The tokenized (SAVEd) form is discussed in general terms under the SAVE command, section 2.19. Source lines are in the forms: line number + mandatory space + source statement The source statement may be in one of the following forms: [label] [ (6502 instruction) (directive) ] [comment] The following examples are valid source lines: 100 LABEL 120 ;Comment line 140 LDA #5 and then any comment at all 150 DEY 160 ASL A double number in accumulator 170 GETNUM LDA (ADDRESS),Y 180 .PAGE "directives are legal, too" In general, the format is as specified in the MOS Technology 6502 Programming Manual. We recommend that the user unfamiliar with 6502 assembly language programming should purchase: "Machine Language for Beginners" by R. Mansfield or "Programming the 6502" by Rodney Zake or any other book which seems compatible with the users current knowledge of assembly language. Special Note: The assembler of MAC/65 understands only upper case labels, op codes, etc. HOWEVER, the editor (see especially section 1.3) will convert all lower case to upper case (except in comments and quoted strings), so the user may feel free to type and edit in which ever case he/she feels most comfortable with. 3.2 INSTRUCTION FORMAT A) Instruction mnemonics are as described in the MOS Technology Programming Manual. B) Immediate operands begin with "#". C) "(operand,X)" and "(operand),Y" designate indirect addressing. D) "operand,X" and "operand,Y" designate indexed addressing. E) Zero page operands cannot be forward referenced. Attempting to do so will usually result in a "PHASE ERROR" message. F) Forward equates are evaluated within the limits of a two pass assembler. G) "*" designates the current location counter. H) Comment lines may begin with ";" or "*". I) Hex constants begin with "$". J) The "A" operand is reserved for accumulator addressing. 3.3 LABELS Labels must begin with an Alpha character, "@". or "?". The remaining characters may be as the first or may be "0" to "9" or ".". The characters must be uppercase and cannot be broken by a space. The maximum number of characters in a label is 127, and ALL are significant. Labels beginning with a question mark ("?") are assumed to be "LOCAL" labels. Such labels are "visible" only to code encountered within the current local region. Local regions are delimited by successive occurrences of the .LOCAL directive, with the first region assumed to start at the beginning of the assembly source, whether or not a .LOCAL is coded there or not. There are a maximum of 62 local regions in any one assembly. Of course, if a .LOCAL is not encountered any where in the assembly, then all labels are accessible at all times. In any case, labels beginning with a question mark will NOT be listed in the symbol table. The following are examples of valid labels: TEST1 @.INC LOCATION LOC22A WHAT? ADDRESS1.1 EXP.. SINE45TAB. 3.4 OPERANDS An operand can be a label, a Macro parameter, a numeric constant, the current program counter (*), "A" for accumulator addressing, an expression, or an ASCII character. The following are examples of the various types of operands: 10 LDA #VALUE ; label 15 ROR A ; accumulator addressing 20 .BYTE 123,$45 ; numeric constants 25 .IF %0 ; Macro parameter 30 CMP #'A ; ASCII character 35 THISLOC = * ; current PC 40 .WORD PMBASE+[PLNO+4]*256 ; expression 3.5 OPERATORS The following are the operators currently supported by MAC/65: [ ] psuedo parentheses + addition - subtraction / division * multiplication & binary AND ! binary OR ^ binary EOR = equality, logical > greater than, logical < less than, logical < > inequality, logical >= greater or equal, logical <= less or equal, logical .OR logical OR .AND logical AND - unary minus .NOT unary logical. Returns true (1) if expression is zero. Returns false (0) it expression is non-zero. .DEF unary logical label definition. Returns true if label is defined. .REF unary logical label reference. Returns true if label has been referenced. > unary. Returns the high byte of the expression. < unary. Returns the low byte of the expression. Logical operators will always return either TRUE (1) OR FALSE (0). However, any non-zero value is considered true when making a conditional test. Some of these operators perhaps need some explanation as to their usage and purpose. The operators are thus described in groups in the following subsections. 3.5.1 Operators: + - * / These are the familiar arithmetic operators. Remember, though, that they perform 16-bit signed arithmetic and ignore any overflows. Thus, for example, the value of $FF00+4096 is $0F00, and no error is generated. 3.5.2 Operators: & ! ^ These are the binary or "bitwise" operators. They operate on values as 16 bit words, performing bit-by-bit ANDs, ORs, or EXCLUSIVE ORs. They are 16 bit equivalents of the 6502 opcodes AND, ORA, and EOR. EXAMPLES: $FF00 & $0FF is $0000 $03 ! $0A is $000B $003F ^ $011F is $0120 3.5.3 OPERATORS: = > < <> >= <= These are the familiar comparison operators. They perform 16 bit unsigned compares on pairs of operands and return a TRUE (1) or FALSE (0) value. EXAMPLES: 3 < 5 returns 1 5 < 5 returns 0 5 <= 5 returns 1 CAUTION: Remember, these operators always work on PAIRS of operands. The operators ">" and "<" have quite different meanings when used as unary operators. 3.5.4 Operators: .OR .AND .NOT These operators also perform logical operations and should not be confused with their bitwise companions. Remember, these operators always return only TRUE or FALSE. EXAMPLES: 3 .OR 0 returns 1 3 .AND 2 returns 1 6 .AND 0 returns 0 .NOT 7 returns 0 3.5.5 Operator: - (unary) The minus sign may be used as a unary operator. Its effect is the same as if a minus sign had been used in a binary operation where the first operator is zero. EXAMPLE: -2 is $FFFE (same as 0-2) 3.5.6 Operators: < > (unary) These UNARY operators are extremely useful when it is desired to extract just the high order or low order byte of an expression label. Probably their most common use will be that of supplying the high and low order bytes of an address to be used in a "LDA #" or similar immediate instruction. EXAMPLE: FLEEP = $3456 LDA #FLEEP (same as LDA #$34) 3.5.7 Operator: .DEF This unary operator tests whether the following label has been defined yet, returning TRUE or FALSE as appropriate. CAUTION: Defining a label AFTER the use of a .DEF which references it can be dangerous, particularly if the .DEF is used in a .IF directive. EXAMPLE: .IF .DEF ZILK .BYTE "generate some bytes" .ENDIF ZILK = $3000 In this example, the .BYTE string will NOT be generated in the first pass but WILL be generated in the second pass. Thus, any following code will almost undoubtedly generate a PHASE ERROR. 3.5.8 Operator: .REF This unary operator tests whether the following label has been referenced by any instruction or directive in the assembly yet; and, in conjuction with the .IF directive, produces the effect of returning a TRUE or FALSE value. Obviously, the same cautions about .DEF being used before the label definition apply to .REF also, but here we can obtain some advantage from the situation. EXAMPLE: .IF .REF PRINTMSG PRINTMSG ...(code to implement the PRINTMSG routine) .ENDIF In this example, the code implementing PRINTMSG will ONLY be assembled if something preceding this point in the assembly has referred to the label PRINTMSG! This is a very powerful way to build an assembly language library and assemble only the needed routines. Of course, this implies that the library must be .INCLUDEd as the last part of the assembly, but this seems like a not too onerous restriction. In fact, OSS has used this technique in writing the libraries for the C/65 compiler. CAUTION: note that in the description above it was implied that .REF only worked properly with a .IF directive. Not only is this restriction imposed, but attempts to use.REF in any other way can produce bizarre results. ALSO, .REF can not effectively be used in combination with any other operators. Thus, for example, .IF .REF ZAM .OR .REF BLOOP is ILLEGAL! The only operator which can legally combined with .REF is .NOT, as in .IF .NOT .REF LABEL. Note that the illegal line above could be simulated thus: EXAMPLE: DOIT . = 0 .IF .REF ZAM DOIT . = 1 .IF .REF BLOOP DOIT . = 1 .ENDIF .IF DOIT ... 3.5.9 Operator: [ ] MAC/65 supports the use of the square brackets as "psuedo parentheses". Ordinary round parentheses may NOT be used for grouping expressions, etc., as they must retain their special meanings with regards to the various addressing modes. In general, the square brackets may be used any where in a MAC/65 expression to clarify or change the order of evaluation of the expression. EXAMPLES: LDA GEORGE+5*3 ;This is legal, but it multiplies 3*5 and adds the 15 to GEORGE...probably not what you wanted. LDA (GEORGE+5)*3 ;Syntax Error!!! LDA [GEORGE+5]*3 ;OK...the addition is performed before the multiplication LDA ( [GEORGE+5]*3),Y ;See the need for both kinds of "parentheses"? REMEMBER: Operators in MAC/65 expressions follow precedence rules. The square brackets may be used to override these rules. 3.6 ASSEMBLER EXPRESSIONS An expression is any valid combination of operands and operators which the assembler will evaluate to a 16-bit unsigned number with any overflow ignored. Expressions can be arithmetic or logical. The following are examples of valid expressions: 10 .WORD TABLEBASE+LINE+COLUMN 55 .IF .DEF INTEGER .AND [ VER=1 .OR VER >=3 ] 200 .BYTE >EXPLOT-1, >EXDRAW-1, >EXFILL-1 300 LDA # <[ < ADDRESS^-1 ] +1 305 CMP # -1 400 CPX # 'A 440 INC #1+1 3.7 OPERATOR PRECEDENCE The following are the precedence levels (high to low) used in evaluating assembler expressions: [ ] (psuedo parenthesis) > (high byte), < (low byte), .DEF, .REF, - (unary) .NOT *, / +, - &, !, ^ =, >. <, <=, >=, <> (comparison operators) .AND .OR Operators grouped on the same line have equal precedence and will be executed in left-to-right order unless higher precedence operator(s) intervene. 3.8 NUMERIC CONSTANTS MAC/65 accepts three types of numeric constants: decimal, hexadecimal, and characters. A decimal constant is simply a decimal number in the range 0 through 65535; an attempt to use a decimal number beyond these bounds may or may not work and will certainly produce unexpected and undesired results. EXAMPLES: 1 234 65200 32767 (as used:) .BYTE 2,4,8,16,32,64 LDA #1 A hexadecimal constant consists of a dollar sign followed by one to four legal hexadecimal digits (0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F). Again, usage of more than four digits may produce unwanted results. EXAMPLES: $1 $EA $FF00 $7FFF (as used:) .WORD $100,$200,$400,$800,$1000 AND #$7F A character constant is an apostrophe followed by any printable or displayable character. The value of a character constant is the ASCII (or ATASCII) value of the character following the apostrophe. EXAMPLES: 'A '* '" '= (as used:) CMP #'= CMP #'Z+1 ; same as #$5B 3.9 STRINGS Strings are of two types. String literals (example: "This is a string literal"), and string variables for Macros (example: %$5). Example: 10 .BYTE "A STRING OF CHARACTERS" or Example: 20 .SBYTE %$1 CHAPTER 4: DIRECTIVES As noted in Section 3.1, the instruction field of an assembled line may contain an assembler directive (instead of a valid 6502 instruction). This chapter will list and describe, in roughly alphabetical order, all the directives legal under MAC/65 (excepting directives specific to macros, which will be discussed separately in Chapter 5). Directives may be classified into three types: (1) those which produce object code for use by the assembled program (e.g., .BYTE, .WORD, etc.); (2) those which direct the assembler to perform some task, such as changing where in memory the object code should go or giving a value to a label (e.g., *=, =, etc.); and (3) those which are provided for the convenience of the programmer, giving him/her control over listing format, location of source, etc. (e.g., .TITLE, .OPT, .INCLUDE). Obviously, we could in theory do without the type 3 directives; but, as you read the descriptions that follow, you will soon discover that in practice these directives are most useful in helping your 6502 assembly language production. Incidentally, all the macro-specific directives could presumably be classified as type 3. Three of the directives which follow (.PAGE, .TITLE, and .ERROR) allow the user to specify a string (enclosed in quotes) which will be printed out. For these three directives, the user is limited to a maximum string length of 70 characters. Strings longer than 70 characters will be truncated. Section 4.1 directive: *= purpose: change current origin of the assembler's location counter usage: [label] *= expression The *= directive will assign the value of the expression to the location counter. The expression cannot be forward referenced. *= must be written with no intervening spaces. Example: 50 *= $1234 ;sets the location counter to $1234 Another common usage of *= is to reserve space for data to be filled in or used at run time. Since the single character "*" may be treated as a label referencing the current location counter value, the form "*= *+exp" is thus the most common way to reserve "exp" bytes for later use. Example: 70 LOC *= *+1 ;assigns the current value of the location counter to LOC and then advances the counter by one. (Thus LOC may be thought of as a one byte reserved memory cell.) CAUTION: Because any label associated with this directive is assigned the value of the location counter BEFORE the directive is executed, it is NOT advisable to give a label to "*=" unless, indeed, it is being used as in the second example (i.e., as a memory reserver). NOTE: Some assemblers use "ORG" instead of "*=" and may also have a separate directive (such as "DS" or "RMB") for "defining storage" or "reserving memory bytes". Use caution when converting from and to such assemblers; pay special attention to label usage. When in doubt, move the label to the next preceding or next following line, as appropriate. Section 4.2 directive: = purpose: assigns a value to a label usage: label = expression The = directive will equate "label" with the value of the expression. A "label" can be equated via "=" only once within a program. Example: 10 PLAYER0 = PMBASE + $200 Note: If a "label" is equated more than once, "label" will contain the value of the most recent equate. This process, however, will result in an assembly error. Section 4.3 directive: .= purpose: assign a possibly transitory value to a label usage: label .= expression The .= directive will SET "label" with the value of the expression. Using this directive, a "label" may be set to one or more values as many times as needed in the same program. EXAMPLE: 10 LBL .= 5 20 LDA #LBL ;same as LDA #5 30 LBL .= 3+'A 40 LDA #LBL ;same as LDA #68 CAUTION: A label which has been equated (via the "=" directive) or assigned a value through usage as an instruction label may not then be set to another value by ".=". Section 4.4 directive: .BYTE [and .SBYTE] purpose: specifies the contents of individual bytes in the output object usage: [label] .BYTE [+exp,] (exp)(strvar)[,(exp)(strvar) ...] [label] .SBYTE [+exp,](exp)(strvar)[,(exp)(strvar) ...] The .BYTE and .SBYTE directives allow the user to generate individual bytes of memory image in the output object. Expressions must evaluate to an 8-bit arithmetic result. A strvar will generate as many bytes as the length of the string. .BYTE simply assembles the bytes as entered, while .SBYTE will convert the bytes to Atari screen codes (on the Atari) or to characters with their most significant bit on (on the Apple II). Example: 100 .BYTE "ABC" , 3, -1 This example will produce the following output bytes: 41 42 43 03 FF. Note that the negative expression was truncated to a single byte value. Example: 50 .SBYTE "Hello!" On the Atari, this example will produce the following screen codes: 28 65 6C 6C 6F 01. On the Apple II, the same example would produce the following bytes: C8 E5 EC EC DF A1. SPECIAL NOTE: Both .BYTE and .SBYTE allow an additive Modifier. A Modifier is an expression which will be added to all of bytes assembled. The assembler recognizes the Modifier expression by the presence of the "+" character. The Modifier expression will not itself be generated as part of the output. Example: 5 .BYTE +$80 , "ABC" , -1 This example will produce the following bytes: C1 C2 C3 7F Example: 100 .BYTE +$80,"DEF",'G+$80 This example will produce: C4 C5 C6 47. (Note especially the effect of adding $80 via the modifier and also adding it to the particular byte. The result is an unchanged byte, since we have added a total of 256 ($100), which does not change the lower byte of a 16 bit result.) Example: 55 .SBYTE +$40 , "A12" This example will produce: 61 51 52 Atari 01 F1 F2 Apple II. Example: 80 .SBYTE +$C0,"G-$C0,"REEN" This example will produce: 27 F2 E5 E5 EE Atari C7 92 85 85 8E Apple II. Note: .SBYTE performs its conversions according to a numerical algorithm and does NOT special case any control characters, including BELL, TAB, etc.--these characters ARE converted. Section 4.5 directive: .CBYTE purpose: same as .BYTE except that the most significant bit of the last byte of a string argument is inverted usage: [label] .CBYTE [+exp,](exp)(strvar) [,(exp)(strvar)...] The .CBYTE directive may often be used to advantage when building tables of strings, etc., where it is desirable to indicate the end of a string by some method other than, for example, storing a following zero byte. By inverting the sense of the upper bit of that last character of the string, a routine reading the strings from the table could easily do a BMI or BPL as it reads each character. Example: ERRORS .CBYTE 1,"SYSTEM" The line shown would produce these object bytes: 01 53 59 53 54 45 CE And a subroutine might access the characters thus: LDY #1 LOOP LDA ERRORS,Y BMI ENDOFSTRING INY BNE LOOP ... ENDOFSTRING ... Section 4.6 Directive: DBYTE [ see also .WORD ] purpose: specifies Dual BYTE values to be placed in the output object. usage: [label] .DBYTE exp [ ,exp ... ] Both the .WORD and .DBYTE directives will put the value of each expression into the object code as two bytes. However, while .WORD will assemble the expression(s) in 6502 address order (least significant byte, most significant byte), .DBYTE will assemble the expression(s) in the reverse order (i.e., most significant byte, least significant byte). .DBYTE has limited usage in a 6502 environment, and it would most probably be used in building tables where its reversed order might be more desirable. EXAMPLE: .DBYTE $1234,1,-1 produces: 12 34 00 01 FF FF .WORD $1234,1,-1 produces: 34 12 01 00 FF FF Section 4.7 directive: .ELSE purpose: SEE description of .IF for purpose nd usage. Section 4.8 directive: .END purpose: terminate an in-memory assembly usage: [label] .END The .END directive will terminate the assembly ONLY if the source is being read from memory. Otherwise, .END will have no effect on assembly. This "no effect" is handy in that you may thus .INCLUDE file(s) withouthaving to edit out any .END statements they might contain. In truth, .END is generally not needed at all with MAC/65, Section 4.9 directive: .ENDIF purpose: terminate a conditional assembly block SEE description of .IF for usage and details. Section 4.10 directive: .ERROR purpose: force an assembler error and message usage: [label] .ERROR [string] The .ERROR directive allows the user to generate a pseudo error. The string specified by .ERROR will be sent to the screen as if it were an assembler-generated error. The error will be included in the count of errors given at the end of the assembly. Example: 100 .ERROR "MISSING PARAMETER!" Section 4.11 directive: .FLOAT purpose: specifies floating point constant values to be placed in the output object. usage: [label] .FLOAT floating-constant [,flotation-constant...] This directive would normally only be used by the programmer wishing to access the built-in floating point routines of the Atari Operating System ROM's (or similar routines as supplied with the BASIC XL package from OSS for Apple II or equivalent machines). Each floating point constant following the .FLOAT directive will produce 6 bytes of bytes of output object code, in a format consistent with the above-mentioned floating point routines. In particular, the first byte contains the exponent portion of the number, in excess-64 notation representing power of 100. The upper bit of the exponent byte designates the sign of the mantissa portion. The following 5 bytes are the mantissa, inn packed BCD form, normalized on a byte boundary (consistant with the powers-of-100 exponent). EXAMPLES: .FLOAT 3.14156295,-2,718281828 The above example would produce the following bytes in the output object code: 40 03 14 15 62 95 C0 27 18 28 18 28 NOTE: Only floating point constants, NOT expressions, are legal as operands to .FLOAT. Generally, this is not a problem, since the user may perform any constant arithmetic on a calculator (or in BASIC) before placing the result in his/her MAC/65 program. Section 4.12 directive: .IF purpose: choose to perform or not perform some portion of an assembly based on the "truth" of an expression. usage: .IF exp [.ELSE] .ENDIF usage note: there may be any number of lines of assembly language code or directives between ]IF and .ELSE or .ENDIF and similarly between .ELSE and .ENDIF. When a .IF is encountered, the following expression is evaluated. If it is non-zero (TRUE), the source lines following .IF will be assembled, continuing until an .ELSE or .ENDIF is encountered. If an .ELSE is encountered before an .ENDIF, then all the source lines between the .ELSE and the corresponding .ENDIF will not be assembled. If the expression evaluates to zero (false), the source lines following .IF will not be assembled. Assembly will resume when a corresponding .ENDIF or an .ELSE is encountered. The .IF-.ENDIF and .IF-.ELSE-.ENDIF constructs may be nested to a depth of 14 levels. When nested, the "search" for the "corresponding" .ELSE or .ENDIF skips over complete .IF-.ENDIF constructs if necessary. Examples: 10 .IF 1 ; non-zero, therefore true 20 LDA # '? ; these two lines will 30 JSR CHAROUT ; be assembled 40 .ENDIF EXAMPLE: 10 .IF 0 ; expression is false 11 LDA # >ADDRESS ; these two lines will 12 LDX #
ADDRESS ; be assembled 22 .ENDIF 23 JSR PRINTSTRING ; go print the string Note: The assembler resets the conditional stack at the beginning of each pass. Missing .ENDIF(s) will NOT be flagged. Section 4.13 directive: .INCLUDE purpose: allows one assembly language program to request that another program be included and assembled in-line usage: .INCLUDE #filespec usage note: this directive should NOT have a label The .INCLUDE directive causes the assembler to begin reading source lines from the specified "filespec". When the end of "filespec" is reached, the assembler will resume reading source from the previous file (or memory). CAUTION: The .INCLUDEd file MUST be a properly SAVEd MAC/65 tokenized program. It can NOT be an ASCII file. Note: A .INCLUDED file cannot itself contain a .INCLUDE directive. EXAMPLE .INCLUDE #D:SYSEQU.M65 This example line will include the system equates file supplied by OSS. Section 4.14 directive: .LOCAL purpose: delimits a local label region usage: .LOCAL usage note: this directive should not be associated with a label. This directive serves to end the previous local region and begin a new local region. It is assumed that the first local region begins at the beginning of the assembly, and the last local region ends at the end of the assembly. Within each local region, any label beginning with a question mark ("?") is assumed to be a "local label". As such, it is invisible to code, equates, references, etc., outside of its own local region. This feature is especially handy when using automatic code generators or when several people are working on a single project. In both these cases, the coder may use labels beginning with "7" and be sure that there will be no duplicate label errors produced. EXAMPLE: 10 *= $4000 11 LDX #3 ; establish a counter 12 ?LOOP 13 LDA FROM,X ; get a byte 14 STA TO,X ; put a byte 15 DEX ; more to do? 16 BPL ?LOOP ; goes to label on line 12 17 ; 18 .LOCAL ; another local region! 19 ; 20 ?LOOP=6 21 ; 22 LDY #?LOOP ; same as LDY #6 23 (etc.) FEATURE: Local labels MAY be forward referenced, just like any other label. NOTE: Local labels do not appear in the symbol table listing. Section 4.15 directive: .OPT purpose: selects various assembly control OPTions usage: .OPT option (or) .OPT NO option usage notes: the valid options are as follows: LIST ERR EJECT OBJ MLIST CLIST NUM XREF The .OPT directive allows the user to control certain functions of the assembly. Generally, coding ".OPT option" will invoke a feature or option, while ".OPT NO option" will "turn off" that same feature. The following are the descriptions of the individual options: LIST control the entire assembly listing. NO LIST turns off all listing except error lines. ERR will determine if errors are returned to the user in the listing and/or the screen. NO ERR is thus dangerous. EJECT controls the title and page listing. NO EJECT only turns off the automatic page generation; it has no effect on .PAGE requests. OBJ determines if the object code is written to the device/memory. NO OBJ is useful during trial assemblies. OBJ is NECESSARY when the object code is to placed in memory. NUM will auto number the assembly listing instead of using the user line numbers. NUM will begin at 100 and increment by 1. NUM is generally not useful except for final, "pretty" assemblies. MLIST controls the listing of Macro expansions. NO MLIST will list only the lines within a Macro expansion which generate object code. MLIST will expand the entire Macro. NO MLIST is extraordinarly useful in producing readable listings. CLIST controls the listing of conditional assembly. NO CLIST will not list source lines which are not assembled. CLIST will list all lines within the conditional construct. XRef allows the user, when cross reference has been specified in the ASM comland line, to control which portions of the source program will be cross referenced during the assembly. NOTE: unless specified otherwise by the user, all of the options will assume their default settings. The default settings for ..OPT are: ERR errors are reported EJECT pages are numbered and ejected NO NUM use programmer's line numbers MLIST all macro lines are listed CLIST all failed conditionals list XREF continuous cross reference NO OBJ l SEE CAUTION !!!!! CAUTION: The OBJ option is handled in a special way: IF assembling to memory the object default is NO OBJ. IF assembling to a device the object option is OBJ. NOTE: Macro expansions with the NO NUM option will not be listed with line numbers. Section 4.16 directive: .PAGE purpose: provides page headings and/or moves to top of next page of listing usage: .PAGE [ string ] usage note: no label should be used with .PAGE The .PAGE directive allows the user to specify a page heading. The page heading will be printed below the page number and title heading. .PAGE will eject the next page, nd prints the most recent title and page headings. Example: 300 .PAGE "EXECUTE LABEL SEARCH" Note: The assembler will automatically eject and print the current title and page headings after 61 lines have been listed. Section 4.17 directive: .SBYTE purpose: produces "screen" bytes in output object usage: See .BYTE description, section 4.4 Section 4.18 directive: .SET purpose: controls various assembler functions usage: .SET dcnum1 , dcnum2 The .SET directive allows the user to change specific variable parameters of the assembler. The dcnum1 specifies the parameter to change, and dcnum2 is the changed value. The following table summarizes the various .SET parameters. Defaults for each parameter are given in parentheses, followed by the allowable range of values. dcnum1 dcnum1 function 0 (4) 1-4 sets the .BYTE and .SBYTE listing format. 1 to 4 bytes can be printed in the object code filed of the listing. 1 (0) 0-31 sets the assembly listing left margin. The specified number is the number of spaces which will be printed before the assembled source line. 2 (80) 40-132 set width for listing, adjust for your printer. 3 (12) 0,12 form feed select. 0 implies no form feed on printer--use multiple line feeds. Any other used as form feed char. 4 (66) any number of lines per page for listing. SEction 4.19 directive: .TAB purpose: sets listing "tab stops" for readability usage: .TAB dcnum1 .dcnum2 .dcnum3 The .TAB directive allows the user to specify the starting column for the listing of the instruction field, the operand field, and the comment filed respectively. The defaults are 8,12,20. Example: 200 .TAB 16,32,50 ... 1200 .TAB 8,12,20 ;restores defaults Section 4.20 directive: .TITLE purpose: specify assembly listing heading usage: .TITLE string The .TITLE directive allows the user to specify a assembly title heading. The title string will be printed at the top of every page following the page number. Section 4.21 directive: .WORD [See also .DBYTE] purpose: place 16 bit word values in output object usage: [label] .WORD exp [,exp ... ] The .WORD and .DBYTE directives both put the value of each following expression into the object code as tow bytes. But where .WORD will assemble the expression(s) in 6502 address order (least significant byte, most significant byte). .DBYTE will assemble the expression(s) in reverse order (most significant byte, least significant byte). Generally, for 6502 programs, .WORD is the more useful of the two, and is more compatible with the code produced by assembled 6502 instructions. EXAMPLE: .DBYTE $1234,1,-1 produces: 12 34 00 01 FF FF .WORD $1234,1,-1 produces: 34 12 01 00 FF FF CHAPTER 5: MACRO FACILITY A MACRO DEFINITION is a series of source lines grouped together, given a name, and stored in memory. When the assembler encounters the corresponding name in the instruction (opcode, directive) column, the saved lines will be substituted for the Macro name and assembled. Effectively, this allows the user to define and then use new assembler instructions. Depending upon the code stored in its definition, a macro might be thought of as either an "extra" directive or a "new" opcode. The process of finding of a macro in the table when its name is used, and then assembling the code it was defined with, is called a MACRO EXPANSION. The unique facility of Macro Expansions is that they may have PARAMETERS passed to them. These parameters will be substituted for the "formal parameters" during the expansion of the Macro. The use (expansion) of a Macro in a program required that the Macro first be defined. To the set of directives already discussed in chapter 4, then, must be added two new directives used for defining new macros: .MACRO .ENDM This chapter will first discuss these two directives, show how to invoke a macro (cause its expansion) and then examine the use of formal and calling parameters, including string parameters. Section 5.1 directive: .ENDM purpose: end the definition of a macro usage: .ENDM usage note: generally, the .ENDM directive should not be labelled. This directive is used solely to terminate the definition of a macro. When invoking a macro, do NOT use this directive. Basically, the concept of macros requires that all source lines between the .MACRO directive and the .ENDM directive be stored in a special section of memory (the macro table). Thus, encountering an improperly paired .ENDM directive is considered a severe assembly error. See the description of .MACRO for further information. Section 5.2 directive: .MACRO purpose: initiates a macro definition usage: .MACRO macroname usage note: "macroname" may be any valid MAC/65 label. It MAY be the same name as a program label (without conflict). The .MACRO directive all cause the lines following to be read and stored under the Macro name of "macroname". The definition is terminated with the .ENDM directive. All instructions except another .MACRO directive are valid Macro source lines. A Macro definition can NOT contain another Macro definition. A simple example of a MACRO DEFINITION: 10 .MACRO PUSHXY ; The name of this Macro is "PUSHXY" 11 ; When this Macro is used (expanded), the following 12 ; instructions will be substituted for "PUSHXY" 13 ; and then assembled. 14 TXA 15 PHA 16 TYA 18 PHA 19 .ENDM ; The terminator for "PUSHXY" SPECIAL NOTE: ALL labels used within a macro are assumed to be local to that macro. MAC/65 accomplishes this by performing a "third pass" of the assembly during macro expansions. Thus, a label defined within a macro expansion is avaliable to code which follows the macro; but another expansion of the same macro with the same label will reset the labels value. The action is similar to the ".=" directive, except that forward references to internal macro labels ARE legal. EXAMPLE: 20 .MACRO MOVE6 21 LDX #5 22 LOOP 23 LDA FROM,X 24 STA TO,X 25 DEX 26 BPL LOOP 27 .ENDM The label "LOOP" is local to this macro usage, and yet it may (if needed) be referenced outside the macro expansion (although not in another macro expansion). (note that if a macro label is only defined once by a single macro usage, the effect is the same as if the label were defined outside ny macro.) Although the .LOCAL-produced local regions may be used by and with macros, the user is limited to a maximum of 62 local regions. No such restriction applies to the number of possible local usages of a label in a macro expansion. 5.3 MACRO EXPANSION, PART 1 As stated above, a macro is expanded when it is used. And the "use" of a macro is simplicity itself. To invoke (use, expand--all equivalent words) a macro, simply place its name in the opcode/directive field of an assembler line. Remember, though, that macros MUST be defined before they can be used. For example, to invoke the two macros defined in examples in the previous section (5.2), one could simple type them in as shown and then enter and assemble: EXAMPLE: 2000 ALABEL PUSHXY 2010 ; and pushxy generates the code 2020 ; TXA PHA TYA PHA 2030 ; 2040 MOVE6 2050 ; similarly, MOVE6 is used 2060 JMP LOOP 2070 ; and LOOP refers to the label 2080 ; defined in the MOVE6 macro ... Note that the use of a label on the macro invocation is optional. The label is assigned the current value of the location counter and is not dependent upon the contents of the macro at all. There are many more "tricks" and features usable with macros, but we will continue this discussion after an examination of macro parameters as used in a macro definition. 5.4 MACRO PARAMETERS Macro parameters can be of two types: expressions (which are evaluated as 16 bit words) or strings. The parameters are passed via the macro expansion (invocation, use, etc.) and are stacked in memory in the order of occurance. A maximum of 63 parameters can be stacked by a macro expansion, including expansions within expansions. However, before a parameter can be used in an expansion, there must be a way of accessing it in the MACRO DEFINITION. Parameters are referenced in a macro definition by the character "%" for expressions and the characters "%$" for strings. The value following the character refers to the actual parameter number. SPECIAL NOTE: The parameter number can be represented by a decimal number (e.g., %2) or may be a label enclosed by parentheses (e.g., %$(LABEL) ). Of course, strings may be similarly referenced, as in %$(INDEX) or %$1. Examples: 10 LDA # >%1 ; get the high byte of parameter 1. 15 CMP (%11 ,X) ;yes, that really is number 11. 20 .BYTE %2-1 ;value of parameter 2 less 1. NOTE: the above is NOT equivalent to using parameter %1. Parameter substitution has highest precedence! 25 SYMBOL .= SYMBOL + 1 30 LDX # -%(SYMBOL) ; see the power available? 40 .BYTE %$1,%$2,0 ; string parameters, ending 0. Remember, in theory the parameters are numbered from 1 to 63. In reality, the TOTAL number of parameters in use by all active (nested) macro expansions cannot exceed 63. This does NOT mean that you can have only 63 parameter references in your macro DEFINITIONS. The limit only applies at invocation time, and even then only to nested (not sequential) macro usages. SPECIAL NOTE: In addition to the "conventional" parameters, referred to by number, parameter zero (%0) has a special meaning to MAC/65. Parameter zero allows the user to access the actual NUMBER of real parameters passed to a macro EXPANSION. This feature allows the user to set default parameters within the Macro expansion, or test for the proper number of parameters in an expansion, or more. The following example illustrates a possible use of %0 and shows usage of ordinary parameters as well. EXAMPLE: 10 .MACRO BUMP 11 ; 12 ; This macro will increment the specified word 13 ; 14 ; The calling format is: 15 ; BUMP address [ ,increment ]. 16 ; If increment is not given, 1 is assumed 17 ; 18 .IF%0=0 .OR %0>2 19 .ERROR "BUMP": Wrong number of parameters" 20 .ELSE 21 ; 22 ; this is only done if 1 or 2 parameters 23 ; 24 .IF $0>1 ; did user specify "increment" ? 25 ; this is assembled if user gave two parameters 26 LDA %1 ; add "increment" to "address". 27 CLC 28 ADC # <%2 ; low byte of the increment 29 STA %1 ; low byte of result 30 LDA %1 +1 ; high byte of location 31 ADC # >%2 ; add in high byte of increment 32 STA %1 +1 ; and store rest of result 33 ; 34 .ELSE 35 ; this is assembled if only one parameter given 36 INC %1 ; just increment by 1. 37 BNE SKIPHI ; implicitly local label 38 INC %1 +1 ; must also increment high byte 39 SKIPHI 40 .ENDIF ; matches the .IF %0>1 (line 24) 41 .ENDIF ; matches the .IF of line 18 42 .ENDM ; terminator. 5.5 MACRO EXPANSION, PART 2 We have shown how macro definitions may include specifications of particular parameters (the specifications might also be called "formal parameters"). This section will show how to pass actual parameters (equivalently "value parameters", "calling parameters", etc.) to the definition. The concept is simple: on the same line as the macro invocation (by use of its name, of course) and following the macro's name, the user may place expressions (or strings, see section 5.6). MAC/65 simply assigns each of these values a number, from 1 to 63, and then, during the macro expansion, replaces the formal parameters (%1, %2, %(label), etc.) with the corresponding values. Does that sound too complicated? Internally, it is. Externally, it is an easy as this: EXAMPLE: Assume that the BUMP macro has been defined (as above, section 5.4), then the user may invoke it as needed, thus: 100 ALABEL BUMP A.LOCATION 110 INCR .= 7 120 BUMP A.LOCATION,3 130 BUMP A.LOCATION-2 140 BUMP 150 BUMP A.LOCATION,INCR,7 160 A.LOCATION .WORD 0 note: lines 140 and 150 will each cause the BUMP error to be invoked and printed 170 BUMP INCR,A.LOCATION will try to increment address 7 by something 180 BUMP PORT5 assuming the PORT5 is some hardware port, strange and wonderful things could happen 5.6 MACRO STRINGS String parameters are represented in a macro definition by the character "%$". All numeric parameters have a string counterpart, not all of which are useful. All string parameters have a numeric counterpart (their length). As a special case, %$0 always returns the macro NAME] The following table shows the various string and numeric values returned for a given parameter: As appears in string returned numeric value Macro call: (in quotes): returned: "A String 1 2 3" "A String 1 2 3" length of string NUMERICSYMBOL "NUMERICSYMBOL" value of label SYMBOL+1 "SYMBOL" value of expr %$4 the string of parameter 4 value of original (above would be used by a macro calling another macro) -LABEL "LABEL" value of expr GEORGE*HARRY+PETE undefined value of expr .DEF CIO "CIO" value of expr 2 + 2 * 65 undefined value of expr A Macro string example: 10 .MACRO PRINT 11 ; 12 ; This Macro will print the specified string. 13 ; parameter 1, but if no parameter string is 14 ; passed, only an EOL will be printed. 15 ; 16 ; The calling format is: PRINT [ string ] 17 ; 18 .IF %0 = 1 ; is there a string to print? 19 JMP PASTSTR ; yes, jump over string storage 20 STRING .BYTE %$1,EOL ; put string here. 21 ; 22 PASTSTR 23 LDX #>STRING ; get string address into X&Y 24 LDY #1 .OR %2=0 .WORD %1 .ENDIF The danger here occurs if the caller invokes the macro with only one parameter. Since %2 is non-existent (and hence undefined), the sub-expression "%2=0" is indeed true and the effect of "%0>1" is nullified. Of course, the lack of parameter 2 will produce a "PARAMETER ERROR", but it will already be too late. A better coding of the above would be: .IF %0>1 .IF %2<>0 .WORD %1 .ENDIF .ENDIF C. Even though labels defined within macros are local to each invocation, they are still "visible" outside the macro(s). Thus, it might be a good idea to have a special form for labels defined in macros and avoid that form outside macros. The macro library supplied with MAC/65 uses labels beginning with "@" as local labels to macros. 5.8 A COMPLEX MACRO EXAMPLE The following set of macros is designed to demonstrate several of the points made in the preceding sections. Aside from that, though, it is a good, usable macro set. Study it carefully, please. (The line numbers are omitted for the sake of brevity. Any numbers will do, of course.) ; ; the first macro, "@CH", is designed to load an ; IOCB pointer into the X register. If passed a ; value from 0 to 7, it assumes it to be a constant ; (immediate) channel number. If passed any other ; value, it assumes it to be a memory location which ; contains the channel number. ; ; NOTE that these comments are outside the body of ; the macro, thus saving valuable table space. ; .MACRO @CH .IF %1>7 LDA %1 ; channel # is in memory cell ASLA ASLA ASLA ASLA ; times 16 TAX .ELSE LDX #%*16 .ENDIF .ENDM ; ; this next macro, "@CV", is designed to load a ; Constant or Value into the A register. If ; passed a value from 0 to 255, it assumes it ; to be a constant (immediate) value. If passed ; any other value, it assumes it to be a memory ; location (non-zero page). ; .MACRO @CV .IF %1<256 LDA #%1 .ELSE LDA %1 .ENDIF .ENDM ; ; The third macro is "@FL", designed to establish ; a filespec. If passed a literal string, @FL ; will generate the string in line, jumping around ; it, and place its address in the IOCB pointed to ; by the X register. If passed a non-zero page ; label, @FL assumes it to be the label of a valid ; filespec string and uses it instead. ; .MACRO @FL .IF %1<256 JMP *+%1+4 @F .BYTE %$1,0 LDA #<@F STA ICBADR+1,X LDA #>@F STA ICBADR+1,X .ELSE LDA #<%1 STA ICBADR,X LDA #>%1 STA ICBADR+1,X .ENDIF .ENDM ; ; The main macro here is "XIO", a macro to ; implement a simulation of BASIC's XIO command. ; The general syntax of the usage of this macro is: ; XIO command, channel [,aux1,aux2] [,filespec] ; ; where channel may be a constant from 0 to 7 ; or a memory location. ; where command, aux1, and aux2 may be a constant ; from 0 to 255 or a non-zero page location ; where filespec may be a literal string or ; a non-zero page location ; if aux1 and aux2 are omitted, they are assumed ; to be zero (you may not omit aux2 only) ; if the filespec is omitted, it is assumed to ; be "S:" ; .MACRO XIO .IF %0<2 .OR %0>5 .ERROR "XIO: wrong number of parameters" .ELSE @CH %2 @CV %1 STA ICCOM,X ; command .IF %0>=4 @CV %3 STA ICAUX1,X @CV %4 STA ICAUX2,X .ELSE LDA #0 STA ICAUX1,X STA ICAUX2,X .ENDIF .IF %0=2 .OR %0=4 @FL "S:" .ELSE @FPTR .= %0 @FL %$(@FPTR) .ENDIF JSR CIO .ENDIF .ENDM Did you follow all that? The trick is that, the way "XIO" is specified, it is legal to pass it 2, 3, 4, or 5 arguments; but each of those numbers represents a unique combination of parameters, to wit: XIO command,channel XIO command,channel,filespec XIO command,channel,aux1,aux2 XIO command,channel,aux1,aux2,filespec This is not a trivial macro example. Perhaps you will not have occasion to write something to complex. But MAC/65 provides the tools to do many things if you need them. CHAPTER 6: COMPATIBILITY There are many different 6502 assemblers available, and it seems that each has a few foibles, bug, or whatever that are uniquely its own (and, or course, they are called "features" by their promoters). Well, MAC/65 is no different. This chapter is devoted to telling you of some of the things to watch out for when converting from another 6502 assembler to MAC/65. We restrict ourselves to such things as directives and operators. We will NOT go into a discussion of how to convert the actual 6502 opcodes (equivalently: instructions, mnemonics, etc.). We consider it mandatory that any good 6502 assembler will follow the MOS Technology standard in this regard. Example: We know of some antique 6502 assemblers that specify the various addressing modes via special opcodes. Thus the conventional "LDA #3" becomes "LDAIMN 3" and "LDA (ZIP),Y" becomes "LDAIY ZIP". Unfortunately, there was never any standard established for such distortions, so we shall ignore them as antique and outmoded. In any case, unless you are entering a program out of an older magazine, you are unlikely to run into one of these strange beasts. The rest of this chapter pays homage to our birthright. MAC/65 is a direct descendant of the Atari assembler/editor cartridge (via EASMD). As much as possible, we have tried to keep MAC/65 compatible with the cartridge. Unfortunately, in the interest of providing a more powerful tool, a few things had to be enumerates these changes. 6.1 ATARI'S ASSEMBLER/EDITOR CARTRIDGE This section presents all known functional differences between the Atari cartridge and MAC/65. Obviously, MAC/65 also has many more features not enumerated here, but they will not impact the transferrance of code originally designed for the cartridge (or, for that matter, EASMD). 61.1 .OPT OBJ / NOOBJ By default, the Atari cartridge produces object code, even when the destination of the object is RAM memory. This is a dangerous practice, at best: it is too easy to make a mistake in a program and write over DOS, the user's source, the screen memory, or even (horror of horrors) some of the hardware registers. MAC/65 makes a special case of object in memory: you don't get it unless you ask for it. You MUST have a ".OPT OBJ" directive before the code to be generated or the code will not be produced. 6.1.2 OPERATOR PRECEDENCE The cartridge assigns no precedence to arithmetic operators. MAC/65 uses a precedence similar to BASIC's. Most of the time, this causes no problems; but watch out for mixed expressions. Example: LDA #LABEL-3/256 seen as LDA #[LABEL-3] / 256 by the cartridge seen as LDA #LABEL - [3/256] by MAC/65 6.1.3 THE .IF DIRECTIVE The implementation of .IF in the cartridge is clumsy and unusable. MAC/65's implementation is more conventional and much more powerful. Rather than try to offer a long example here, we will simply refer you to the appropriate sections of the two manuals. CHAPTER 7: ERROR DESCRIPTIONS When an error occurs, the system will print *** ERROR - followed by the error number (unless the error was generated with the .ERROR assembler directive) and, for most errors, a descriptive message about the error. Note: The assembler will print up to 3 errors per line. The format used in the listing of descriptions which follows is simply ERROR NUMBER, ERROR MESSAGE, description and possible causes. 1 - MEMORY FULL All user memory has been used. If issued by the Editor, no more source lines can be entered. If issued by the Assembler, no more labels or macros can be defined. NOTE: If memory full occurs during assembly and the source code is located in memory, SAVE the source to disk, type NEW, and assemble from the disk instead. Now the assembler can use all of the space formerly occupied by your source for macro and symbol tables, etc. 1 - INVALID DELETE Either the first line number is not present in memory, or the second line number is less than the first line number. 3 - BRANCH RANGE A relative instruction references an address displacement greater than 129 or less than 126 from the current address. 4 - NOT Z-PAGE / IMMEDIATE MODE An expression for indirect addressing or immediate addressing has resolved to a value greater than 255 ($FF). 5 - UNDEFINED The Assembler has encountered a undefined label. 6 - EXPRESSION TOO COMPLEX The Assembler's operator stack has overflowed. If you must use an expression as complex as the one which generated the error, try breaking it down using temporary SET labels (i.e., using ".="). 7 - DUPLICATE LABEL The Assembler has encountered a label in the label column which has already been defined. 8 - BUFFER OVERFLOW The Editor syntax buffer has overflowed. Shorten the input line. 9 - CONDITIONAL NESTING The .IF-.ELSE-.ENDIF construct is not properly nested. Since MAC/65 cannot detect excess .ENDIFs, the problem must be an EXTRA .ELSE or .ENDIF instead. 10 - VALUE > 255 The result of an expression exceeded 255 when only one byte was needed and allowed. 11 - CONDITIONAL STACK The .IF-.ELSE-.ENDIF nesting has gone past the number allowed. Conditionals may be nested a maximum of 14 levels. 12 - NESTED MACRO DEFINITION The Assembler encountered a second .MACRO directive before the .ENDM directive. This error will abort assembly. 13 - OUT OF PHASE The address generated in pass 2 for a label does not match the address generated in pass 1. A common cause of this error are forward referenced addresses. If using conditional assembly (with or without macros), this error can result from a .IF evaluating true during one pass and false during the other. 14 - *= EXPRESSION UNDEFINED The program counter was forward referenced. 15 - SYNTAX OVERFLOW The Editor is unable to syntax the source line. Simplify complex expressions or break the line into multiple lines. 16 - DUPLICATE MACRO NAME An attempt was made to define more than one Macro with the same name. Only the first definition will be valid. 17 - LINE # >65535 The Editor cannot accept line numbers greater than 65535. 18 - MISSING .ENDM In a Macro definition, an EOF was reached before the corresponding .ENDM terminator. Macro definitions cannot cross file boundaries. This error will abort assembly. 19 - NO ORIGIN The *= directive is missing from the program. Note: This error will only occur if the assembler is writing object code. 20 - NUM/REN OVERFLOW On the REN or NUM command, the line number generated was greater than 65535. If REN issued the error, entering a valid REN will correct the problem. If NUM issued the error, the auto-numbering will be aborted. 21 - NESTED .INCLUDE An included file cannot itself contain an .INCLUDE directive. 22 - LIST OVERFLOW The list output buffer has exceeded 255 characters. Use smaller numbers in the .TAB directive. 23 - NOT SAVE FILE An attempt was made to load or assemble a file not created with the SAVE command. 24 - LOAD TOO BIG The load file cannot fit into memory. 25 - NOT BINARY SAVE The file is not in a valid binary (memory image, assembler object, etc.) format. 27 - INVALID .SET The first dcnum is a .SET specified a non-existant Assembler system parameter. 30 - UNDEFINED MACRO The Assembler encountered a reference to a Macro which is not defined. Macros must first be defined before they can be expanded. 31 - MACRO NESTING The maximum level of Macro nesting has exceeded 14 levels. 32 - BAD PARAMETER In a Macro expansion, a reference was made to a nonexistent parameter, or the parameter number specified was greater than 63. 128 -255 [operating system errors] Error numbers over 127 are generated in operating system. Refer to the DOSXL manual for detailed descriptions of such errors and their causes. APPENDIX A Actually, the bulk of this appendix is contained on your master MAC/65 diskette in the form of a system macro file. This appendix is here simply to alert you to the existence of the file and to give a brief description of macros available. We would suggest that you use MAC/65 to LOAD and LIST (to a printer or the screen) the file IOMAC.LIB. May we suggest that you adopt a naming convention for you MAC/65 files, both SAVEd and LISTed, that does not conflict with anything? We use the following extensions (though you are obviously free to rename our files to your own preferences): .M65 MAC/65 SAVEd files .ASM MAC/65 LISTed files .LIB MAC/65 SAVEd libraries (note that C/65 insists on its runtime library being named RUNTIME.LIB, hence this convention) In any case, the macros available in IOMAC.LIB are: OPEN chan,aux1,aux2,filename Opens the given filename on the given channel using aux1 and aux2 as per DOSXL specifications. PRINT chan [,buffer[,length]] If no buffer given, prints just a CR on chan. If no length given, length assumed to be 255 or position of CR, which ever is smaller. Buffer may be literal string, in which case length is ignored if given. INPUT chan,buffer [,length] If no length given, defaults to 255 bytes. BGET chan,buffer,length Binary read, a la BASIC XL, of length number of bytes into the given buffer address. BPUT chan,buffer,length Binary write of length number of bytes from the given buffer address. CLOSE chan Closes the given file. XIO command,chan [,aux1,aux2][,filename] As described in chapter 5. NOTES: "chan" may be a literal channel number (0 through 7) or a memory location containing a channel number (0 through 7). "aux1", "aux2", "length" and "command" may all be either literal numbers (0 to 255) or memory locations. "filename" may be either a literal string (e.g., "D:FILE1.DAT") or a memory location, the latter assumed to be the address of the start of the filename string. Where memory locations are given instead of literals, they must be non-zero page locations which are defined BEFORE their usage in the macro(s). The following example will NOT work properly!! : PRINT 3,MESSAGE1 ; WRONG! ... MESSAGE1 .BYTE "This WON'T WORK !!! " These macros are useful instruments, but they really are meant only as examples, to show you what you can do with MAC/65. Please feel free to study them and change them as you need.