#@L}5 _$% l0$)$$Hȱ$ UhL" `e$$%`$%`  R@P!( L(1   Y I`  d  Ld M * @  $ % CC$$)%1 Udߥ$9%: !0 S$% DD˙`  }J)Lr ɷ=82 =3 =109 =4 =150 =104 =117 =69 =52 =70 =53 =80 =77 =71 =72 =83 =84 =1 =45 =0 =114 =116 =120 =87 =}2 =91 =92 =93 =123 =124 =125 =126 1070800066̛A REFERENCE MANUAL FORΛٱ›MAC/65ϛ}A Macro Assembler and Editor program for use with 6502-based computers built byApple Computer, Inc., and Atari, Inc.}The programms, disks and manuals comprisingMAC/65 are Copyright (c) 1982 byOptimized Systems Software, Inc.andSte}phen D. LawrowThis manual is copyright (c) 1982 byOptimized Systems Software, Inc., of10379 Lansdale Avenue, Cuper }tino, CAawrowThis manual is copyright (c) 1982 byOptimized Systems Software, Inc., of10379 Lansdale Avenue, Cuper SECTION 2.18.edit command : REPpurpose : REPlace occurrence(s) of a given string with another  }given string.usage : REP/old string/new string/[lno1 [,lno2]] [(,A)(,Q)] The REP command will s }earch the specified lines (all or lno1 through lno2) 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 fo}r the change (Y followed by RETURN for change, RETURN for skip this occurrence.) 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. Ex}ample : REP/LDY/LDA/200,250,Q This example will search for the string "LDY" between the lines 200 and 250, inclusive, a}nd 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 terminat}ed and control will return to the Editor. Of course, if TEXTMODE is selected, there can be no syntax errors.SECTION 2.1}9.edit command : SAVEpurpose : SAVEs the internal (tokenized) form of the user's in-memory text/so}urce to a disk file.usage : SAVE #filespec SAVE will save the tokenized user source file to the specified devi}ce. 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: Two byte line number (LSB,MSB), followed byin the file : One byte length of line } (actually offset to next line), followed by The tokenized line.SECTION 2.20.edit comm}and : SIZEpurpose : 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, an}d the highest usable memory address, in that order, using hexadecimal notation for the addresses.SECTION 2.21.edi}t command : TEXTpurpose : allow entry of arbitrary ASCII (ATASCII) text without syntax checking.usage} : TEXT TEXT will CLEAR ALL user source from memory and put the Editor in the text mode. After this command is u}sed, the Editor will prompt the user for new commands and text with the word "TEXTMODE" (instead of "EDIT"), indicating that }the 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 conversionsusage : ? ($hxnum)(dcnum) ? is the "}resident hex/decimal decimal/hex converter. Numbers in the range 0 - 65535 decimal (0000 - FFFF hex) may be converted. #}Example : ? $1200 will print =4608 ? 8190 will print =$1FFEcimal (0000 - FFFF hex) may be converted. M±INTRODUCTION̛ This manual assumes the user is familiar with assembly language. It is not intended to teach ass%}embly language. This manual is a reference for commands, statements, functions, and syntax conventions of MAC65. It is also a&}ssumed that the user is familiar with the screen editor of the Atari or Apple computer, as appropriate. Consult Atari's or Ap'}ple's Reference Manuals if you are not familiar with the screen editor. If you need a tutorial level manual, we would r(}ecommend you to ask your local dealer or bookstore for suggestions. Two books that have worked well for many of our customers)} are "The Atari Assembler" by Don Inman and Kurt Inman and "Programming the 6502" by Rodney Zaks. This manual is divide*}d into two major sections; the first two chapters cover the Editor commands and syntax, source line entry, and executing sour+}ce 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 lin.}e entry syntax feature, less time is spent re-assembling programs due to assembly errors, allowing more time for actual progr/}am development.START UP̛ Power up the disk drive(s) and monitor, leave the computer off. Insert MAC65 disk in 0}drive #1 and boot system by turning the computer on. This will load and execute OS/A+. Now enter MAC65 (return). This loads a1}nd executes MAC65, the Editor/Macro Assembler. Refer to the OS/A+ Manual for other capabilities.WARM START̛ Th2}e user can exit to OS/A+ by entering the MAC65 command CP (return) or by pressing the System Reset key. To return to MAC65, t3}he user can use the OS/A+ command RUN (return). This "warm starts" MAC65 and does not clear out any source lines in memory.4}BACK-UP COPY̛ Please do not work with your master disk! Make a back-up copy with OS/A+. Consult the OS/A+ re5}ference manual for specific instructions. Keep your master copy in a safe place.SYNTAX̛ The following conventi6}ons are used in the syntax descriptions in this manual: 1. Capital letters designate commands, instructions, functions,7} etc., which must be entered exactly as shown (e.g. ENTER, .INCLUDE, .NOT). 2. Lower case letters specify items which m8}ay be used.The various types are as follows: lno - Line number between 0-65535, inclusive. hxnu9}m - A hex number. It can be address or data. Hex numbers are treated as unsigned integers. dcnum - A p:}ositive number. Decimal numbers are rounded to the nearest two byte unsigned integer; 3.5 is rounded to 4 and 100.1 is rounde;}d to 100. exp - An assembler expression. string - A string of ASCII characters enclosed by do<}uble quotes (e.g. "THIS IS A STRING"). strvar - A string representation. Can be a string, as above, or a strin=}g variable within a Macro call (e.g. %$1). filespec - A string of ASCII characters that refers to OR >} a particular device. See device reference file manual for more specific explanation. 3. Item?}s in square brackets denote an optional part of syntax (e.g. [,lno]). When an optional item is followed by ( ..) the items ma@}y be repeated as many times as needed. Example: .WORD exp [,exp ...] 4. Items in parentheses indicate that any onA}e of the items may be used, e.g. (,Q) (,A). Example: .WORD exp [,exp ...] 4. Items in parentheses indicate that any on,±CHAPTER 1: THE EDITOR. The Editor allows the user to enter and edit MAC/65 source code or ordinary ASCII t C}ext files. To the Editor, there is a reel distinction between the two types of files; so much so that there are actuall D}y two modes accessible to the user, EDIT mode and TEXTMODE. However, for either mode, source code/text must begin with a line E} number between 0 and 65535 inclusive, followed by one space. Examples: 10 LABEL LDA #$32 3020 This is v F}alid in TEXT MODE The first example would be valid in either EDIT or TEXTMODE, while the second example would only be v G}alid in TEXTMODE. The user chooses which mode he wishes to use for editing by selecting NEW (which chooses MAC/65 EDIT H}mode) or TEXT (which allows general text entry). There is more discussion of the impact of these two modes below, but, first, I} there are several points in common to the two modes. 1.1 GENERAL EDITOR USAGE. The source file is manipul J}ated by Editor commands. Since the Editor recognizes a command by the absense of a line number, a line beginning with a line K}number is assumed to be a valid source/text line. As such, it is merged with, added to, or inserted into the source/text line L}s already in memory in accordance with its line number. An entered line which has the same line number as one already in memo M}ry will replace the line in memory. Also, as a special case of the above, a source line can be deleted from memory by en N}tering its line number only. (And also see DEL command for deleting a group of lines.) Any line that does not start wit O}h a line number is assumed to be command line. The Editor will examine the line to determine what function is to be performed P}. If the line is a valid command, the Editor will execute the command. The Editor will prompt the user each time a command ha Q}s been executed or terminated by printing: EDIT for syntax (MAC/65 source) mode TEXTMODE for te R}xt mode The cursor will appear on the following line. Since some commands may take a while to execute, the prompt si S}gnals the user that more input is allowed. The user can terminate a command before completion by hitting the break key (escap T}e key on Apple II). And one last point: If the line is neither a source line or a valid command. The Editor will print: U} WHAT?̛ 1.2 TEXT MODE. The Editor supports a text mode. The text mode is entered with the comma V}nd TEXT. This mode will NOT syntax check lines entered, allowing the user to enter and edit non-assembly language files. All W}Editor commands function in text mode. Remember, though, that all text lines must begin with a line number; and, even i X}n TEXTMODE, the space following the line number is necessary. 1.3 EDIT MODE. MAC/65 is nearly unique among Y} assembler/editor systems in that it allows the assembly language user to enter source code and have it IMMEDIATELY checked f Z}or syntax validity. Of course, since assembly language syntax is fairly flexible (especially when macros are allowable, as th [}ey 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 line ^}s must begin with a line number which must, in turn, be followed by one space. Then, the second space after the line number i _}s the label column. The label must start in this column. The third space after the line number is the instruction column. Ins `}tructions may either start in at least the third column after the line number or at least one space after the label. The oper a}and may begin anywhere after the instruction, and comments may begin anywhere after the operand or instruction. Refer to Asse b}mbler Section for specific instruction syntax. As noted, the Editor syntax checks each source line at entry. If the syn c}tax 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 chara d}cter) at the point of error. The source lines are tokenized and stored in memory, starting at an address in low memor e}y and building towards high memory. The resultant tokenized file is 60% to 80% smaller than its ASCII counterpart, thus allow f}ing larger programs to be entered and edited in memory.SPECIAL NOTE:̛ If, upon entry, a source line contains a g}syntax error and is so flagged by the Editor, the line is entered into Editor memory anyway. This feature allows raw ASCII te h}xt files (possibly from other assemblers and possibly containing one or several syntax errors as far as MAC/65 is concerned) i}to be ENTERed into the Editor without losing any lines. The user can note the lines with errors and then edit them later.d) z±CHAPTER 2: EDITOR COMMANDS. This chapter lists all the valid Editor-level commands, in alphabetical order,k} along with a short description of the purpose and function of each. Again, remember that when the "TEXTMODE" or "EDIT"l} prompt is present any input line not preceded by a line number is presumed to be an Editor command. If in the process m}of executing a command any error is encountered, the Editor will abort execution and return to the user, displaying the errorn} number and descriptive massage of the error before re-prompting the user. Refer to Appendix for possible causes of errors.o}SECTION 2.1.edit command : ASMpurpose : ASseMble MAC/65 source filesusage : ASM [#filespec1],[#filesp}pec2],[#filespec3] ASM will assemble the specified source file and will produce a listing and object code output. Filesq}pec1 is the source device, filespec2 is the list device, and filespec3 is the object device. Any or all of the three filespecr}'s may be omitted, in which case MAC/65 assumes the following default filespec(s) are to be used: filespec1 - user sours}ce memory. filespec2 - screen editor. filespec3 - memory (CAUTION: see below) A "filespec" can be omitted byt} substituting a comma in which case the respective default will be used. Example : ASM #D2:SOURCE,#D:LIST,#D2:OBJECT u} In this example, the source will come from D2:SOURCE, the assembler will list to D:LIST, and the object code will be writv}ten to D":OBJECT. Example : ASM #D:SOURCE, ,#D:OBJECT In this example, the source code will be read from D:SOURCEw} and the object will be written to D:OBJECT. The assembly listing will be written to the screen. Example : ASM , #P:x} In this example, the source will be read from memory, the object will be written to memory (but ONLY if the ".OPT OBJ" dy}irective is in the source), and the assembly listing will be written to the printer. Example : ASM #D:SOURCE , #P: z} In this example, the source will be read from D:SOURCE and the assembly listing will be written to the printer. If the ".OP{}T 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 ass}}embler listing and object output.NOTE: The object code file will have the format of compound files created by the OS/~}A+ SAVE command. See the OS/A+ manual for a discussion of LOAD and SAVE file formats.SECTION 2.2.̛edit command : B}LOADpurpose : allows user to LOAD Binary (memory image) files from disk into memoryusage : BLO}AD #filespec The BLOAD command will load a previously BSAVEd binary file, an assembled object file, or a binary file cr}eated with OS/A+ SAVE command. Example : BLOAD #D:OBJECT This example will load the binary file "OBJECT" to memor}y at the address where it was previously saved from or assembled for.CAUTION : It is suggested that the user only BLO}AD files which were assembled into MAC/65's free area (as shown by SIZE command) or which will load into known safe areas of }memory.SECTION 2.3.edit command : BSAVEpurpose : SAVE a Binary image of a portion of memory. } Same as OS/A+ 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 OS/A+ SAVE comma}nd. Example : BSAVE #D:OBJECT<5000,5100 This example will save the memory addresses from $5000 through $5100 to t}he file "OBJECT".SECTION 2.4.edit command : BYEpurpose : exit to system monitor levelusage : BYE} BYE will put the user to the Atari Memo Pad or Apple II monitor, as appropriate.SECTION 2.5.edit command : }Cpurpose : Change memory constantsusage : C hxnum <(,)(hxnum) [(,)(,hxnum) ...] Although MAC/65 does no}t include 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 purpo}se. 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 5000<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 : Dpurpos}e : 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 : DELpurpose : DELetes a line or group of lines from the } source/text in memoryusage : DEL lno1 [,lno2 ] DEL deletes source lines from memory. If only one l}no is entered, only the line will be deleted. If two lnos are entered, all lines between and including lno1 and lno2 will be }deleted.NOTE : lno1 must be present in memory for DEL to execute.SECTION 2.8.edit command : DOS [or, equi}valently, CP ]purpose : exit from MAC/65 to the CP of OS/A+usage : DOS or CP Either DOS or CP returns t}he user to OS/A+.SECTION 2.9.edit command : ENTERpurpose : allow entry of ASCII (or ATASCII) } text files into MAC/65 editor memoryusage : 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. 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 overwr}ite the line in memory. The parameter "A" allows the user to enter un-numbered text from the specified device. The Edito}r will number the incoming text starting at line 10, in increments of 10.CAUTION : The "A" option will always clear the user} memory before entering from the filespec. line 10, in increments of 10.CAUTION : The "A" option will always clear the user+SECTION 2.10.edit command : FINDpurpose : to FIND a string of characters somewhere in MAC/65's} buffer.usage : FIND/string/ [lno1 [,lno2]][,A] The FIND command will search all lines in memory or the specif}ied line(s) (lno1 through lno2) for the "string" given between the matching delimiter. The delimiter may be any character exc}ept 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". Exa}mple : FIND\Label\25,80 This example will search for the first occurance of "Label" in lines 25 through 80. If th}e "A" is specified, all matches within the specified line range will be listed to the screen. Remember, if no line numbers ar}e given, the range is the entire program.SECTION 2.11.edit command : LISTpurpose : 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,][ lno1 [,lno2 ]] LIST lists the source file to the screen, or device when "#filespec" is specif}ied. If no lnos are specified, listing will begin at the first line in memory and end with the last line in memory. } If only lno1 is specified, that line will be listed if it is in memory. If lno1 and lno2 are specified, all lines between }and including lno1 and lno2 will be listed. When lno1 and lno2 are specified, neither one has to be in memory as LIST will se}arch for the first line in memory greater than or equal to lno1, and will stop listing when the line in memory is greater tha}n lno2. Example : LIST #P: This command will list the current contents of the editor memory to the P: (printer) d}evice. Example : LIST #D2:TEMP, 1030, 1800 This command will list 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 : This points out a method of movin}g or duplicating large portions of text or source via the use of temporary disk files. By suitable RENumbering the in-memory }text before and after the LIST, and by then using ENTER with the Merge option, quite complex movements are possible.SEC}TION 2.12.edit command : LOADpurpose : 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. L}OAD will clear the user memory before loading from the specified device unless the ",A" parameter is appended. The para}meter "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.ed}it command : LOMEMpurpose : change the lower bound of editor memory usable by MAC/65.usage : L}OMEM 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 : NEWpurpose : clear}s out all editor memory, sets syntax checking mode.usage : NEW New will clear all user source c}ode from memory and reset the Editor to syntax mode. The "EDIT" prompt appears, reminding the user that syntax checking is no}w active. If the user needs to defeat the syntax checking, he must use the TEXT command.SECTION 2.15.edit command} : NUMpurpose : 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 num}ber. If no dcnums are specified, NUM will start at the last line number plus 10. NUM dcnum1 will start at the last line numbe}r plus "dcnum1" in increments of "dcnum1". NUM dcnum1, dcnum2 will start at "dcnum1" in increments of "dcnum2". Example} : NUM 1000,20 This example will cause the Editor to prompt the user with the number "1000" followed by a space. When t}he user has entered a line, the next prompt will be "1020", etc. The NUM mode will terminate if the line number which wo}uld 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-Z followed by RETURN.}SECTION 2.16.edit command : PRINTpurpose : to PRINT all or part of the Editor text or source t}o a disk file or a device.usage : PRINT [ #filespec,][ lno1 [,lno2]] PRINT is exactly like LIST except that th}e 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 com}mand with the Append line number option.SECTION 2.17.edit command : RENpurpose : RENumber all lines in Edi}tor memory.usage : REN [ dcnum1 [,dcnum2]] REN renumbers the source lines in memory. If no dcnums are specifie}d, REN will renumber the program starting 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.es starting at linej±CHAPTER 3: THE MACRO ASSEMBLER. Usually, the Assembler is entered from MAC/65 with the command ASM. For A}SM command syntax, refer to section 2.1 (in the Editor commands). Assembly may be terminated by hitting the BREAK key (ESCape} on the Apple II). However, MAC/65 also offers the OS/A+ command line level as optional ability to bypass the Editor ph}ase entirely. This is especially useful when doing assemblies during the processing of an EXeCution file. To invoke the assem}bler directly, simply include one or more file names on the same OS/A+ command line as the "mAC65" command. The formal usage }is as follows: MAC65 [file1 [file2 [file3]][-A][-D]] where "file1", "file2", and "file3" are legal OS/A+ file or }device names and "-A" and "-D" are option specifiers. Thus the arguments are an optional set of one to three filenames, const}rued to be the source, listing, and object files (respectively) of a MAC/65 assembly. And the options available 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" m}ode. That is, it will perform a single assembly and then return to OS/A+. Generally, this command line will perform the assem}bly 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 all three filenames are given will the object code be directed to the file specified.NOTE : If an assem}bly needs no listing but does need an object file, the user may specify E: as the listing file, thus sending the listing to t}he screen.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/6}5 to use the sequence of commands "ENTER#D..." and "ASM ,...". The -D option is used to specify that the assembly MUST }proceed from 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 fil}e is too large to be assembled in memory, the user may use this option to allow assembly of even very large programs. (And re}member, 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.SECTION 3.1: ASSEMBLER INPUT. The Assembler will get a line at a time from the spe}cified device or from memory. If assembling from a device, the file must have been previously SAVEd by the Editor. All discus}sions of source lines and syntax will be at the Editor line entry level. The tokenized (SAVEd) form is discussed in general t}erms under the SAVE command, see section 2.19.Source lines are in the form: line number + mandatory space + source st}atementThe 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 comm}ent 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 MOS Technology 6502 Programming Manual. We reco}mmend that the user unfamiliar with 6502 assembly language programming should purchase: "The Atari Assembler" by Don} Inman & Kurt Inman, or "Programming the 6502" by Rodney Zaks.SECTION 3.2: INSTRUCTION FORMAT.A. Inst}ruction mnemonics are as described in the MOS Technology Program Manual.B. Immediate operands begin with "#"C. "}(operand,X)" and "(operand,Y)" designate indirect addressing.D. "operand,X" and "operand,Y" designate indexed a}ddressing.E. Zero page operands cannot be forward referenced. Attempting to do so will usually result in a "PHA}SE ERROR" message.F. Forward equates are evaluated within the limits of a two pass assembler.G. "*" designates t}he current location counter.H. Comment lines may begin with ";" or "*".I. Hex constants begin with "$".J. The "A"} operand is reserved for accumulator addressing.SECTION 3.3: LABELS. Labels must begin with an Alpha char}acter,"@", 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 is 127, and ALL are significant. Labels beginning wit}h a question mark ("?") are assumed to be "LOCAL" labels. Such labels are "visible" only to code encountered within the curre}nt 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 l}ocal regions in any one assembly. Of course, if a .LOCAL is not encountered anywhere in the assembly, then all labels are acc}essible at all times. In any case, labels beginning with a question mark will NOT be listed in the symbol table.The followin}g are axamples of valid labels: TEST1 @.INC LOC22A WHAT? ADDRESS1.1 EXP.. SINE45TAB.SECTION 3.4: OPERANDS}. An operand can be a label, a Macro parameter, a numeric constant, the current program counter (*), "A" for accumul}ator 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 ; expressionSECTION 3.5 OPERATORS. The following are the operators currently suppo}rted by MAC/65: [ ] pseudo parentheses + addition - substraction / division * multipli}cation & binary AND ! binary OR ^ binary EOR = equality, logical > greater than, logi}cal < less than, logical <> inequality, logical >= greater or equal, logical <= less or equal, l}ogical .OR logical OR .AND logical AND - unary minus .NOT unary logical. Returns true (1) if expressi}on is zero. Returns false (0) if expression is non zero. .DEF unary logical label definition. Return}s true if label is defined. .REF unary logical label reference. Returns true if label has been refer}enced. > 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). Some of these operators perhaps need so }me explanation as to their usage and purpose. The operators are thus described in groups in the following subsections.eed sow=82 =3 =109 =4 =150 =104 =117 =69 =52 =70 =53 =80 =77 =71 =72 =83 =84 =1 =45 =0 =114 =116 =120 =87 = }2 =91 =92 =93 =123 =124 =125 =1261070800066±SECTION 3.5.1 OPERATORS : + - * /̛ These are t }he familiar arithmetic operators. Remember, tough, 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.SECTION 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 EXC}LUSIVE ORs. They are 16 bit equivalents of the 6502 opcodes AND, ORA, and EOR. Example : $FF00 & $00FF is $0000 } $03 ! $0A is $000B $003F ^ $011F is $0120SECTION 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. Example : 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 mean}ings when used as unary operators.SECTION 3.5.4 OPERATORS : .OR .AND .NOT̛ These operators also perform lo}gical operations and should not be confused with their bitwise companions. Remember, these operators always return only TRUE }or FALSE. Example : 3 .OR 0 returns 1 3 .AND 2 returns 1 6 .AND 0 returns 0 } .NOT 7 returns 0SECTION 3.5.5 OPERATOR : - (unary)̛ The minus sign may be used as a unary operator. I}ts 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)SECTION 3.5.6 OPERATORS : < > (unary)̛ These UNARY operators are extremely us}eful when it is desired to extract just the high order or low order byte of an expression or label. Probably their most commo}n use will be that of supplying the high and low order bytes from an address to be used in a "LDA #" or similar immediate ins}truction. Example : FLEEP = $3456 LDA #FLEEP (same as L}DA #$34)SECTION 3.5.7 OPERATOR : .DEF̛ These unary operator tests whether the following label has been def}ined 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 .B!}YTE "generate some bytes" .ENDIF ZILK = $3000 In this example, the .BYTE string will NO"}T be generated in the first pass but WILL be generated in the second pass. Thus, any following code will almost undoubtedly g#}enerate a PHASE ERROR.SECTION 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 conjunction with the .IF directive, produce%}s the effect of returning a TRUE or FALSE value. Obviously, the same cautions about .DEF being used before the label de&}finition 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) .E(}NDIF 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 assemb*}le 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 co,}mpiler.CAUTION : Note that in the description above it was implied that .REF only worked properly with a .IF directiv-}e. Not only is this restriction imposed, but attempts to use .REF in any other way can produce bizarr results. ALSO .REF cann.}ot effectively be used in combination with any other operators. Thus, for example: .IF .REF ZAM .OR .REF BLOOP is ILLEG/}AL ! The only operator which can legally combined with .REF is .NOT, as in .IF .NOT .REF LABEL.Note that the illegal0} line above could be simulated thus: Example : DOIT .= 0 .IF .REF ZAM DOIT .= 1 1} .ENDIF .IF .REF BLOOP DOIT .= 1 .ENDIF .IF DOIT 2} ...SECTION 3.5.9 OPERATOR : [ ]̛ MAC/65 supports the use of the square brackets as "pseudo3} parentheses". Ordinarily round parentheses may NOT be used for grouping expressions, etc., as they must retain their special4} meanings with regard to the various addressing modes. In general, the square brackets may be used anywhere in a MC/65 expres5}sion to clarify or change the order of evaluation of the expression. Example : LDA GEORGE+5*3 ; This is legal,but 6}it multiplies 3*5 and adds the 15 to GEORGE... 7} probably not what you wanted. LDA (GEO8}RGE+5)*3 ; Syntax Error!!! LDA [GEORGE+5]*3 ; OK...the addition is 9}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.SECTI<}ON 3.6 ASSEMBLER EXPRESSIONS. An expression is any valid combination of operands and operators which the assemb=}ler will evaluate to a 16-bit unsigned number with any overflow ignored. Expressions can be arithmetic or logical. The follow>}ing are examples of valid expressions:10 .WORD TABLEBASE+LINE*COLUMN55 .IF .DEF INTEGER .AND [ VER=1 .OR VER >=3?} ]200 .BYTE >EXPLOT-1, >EXDRAW-1, >EXFILL-1300 LDA # < [ (high byte), < (low byte), .DEF, .REF, - (unary).NOT*,B} /+, -&, !, ^=, >, <, <=, >=, <> (comparison operators).AND.OR Operators grouped on the same line have equal preceC}dence and will be executed in left-to-right order unless higher precedence operator(s) intervene.SECTION 3.8 STRIND}GS. Strings are of two types. String literals (example: "This is a string literal"), and string variables for MacrosE} (example: %$5). Example : 10 .BYTE "A STRING OF CHARACTERS" 20 .SBYTE %$1CHAPTER 4 : DIF}RECTIVES. As noted in Section 3.1, the instruction field of an assembled line may contain an assembler directive (inG}stead of a valid 6502 instruction). This chapter will list, in roughly alphabetical order, and describe all the directives leH}gal under MAC/65 (excepting directives specific to macros, which will be discussed separetely in Chapter 5). DirectivesI} may be classified into three types:1. Those which produce object code for use by the assembled program. (e.g.,.BYTE, .WOJ}RD, etc.)2. Those which direct the assembler to perform some task, such as changing where in memory the object code shoulK}d go or giving a value to a label (e.g., *=, =, etc)3. Those which are provided for the convenience of the programmer,L} giving him control over listing format, location of source, etc. (e.g., .TITLE, .OPT, .INCLUDE). Obviously, we coulM}d in theory do without the type 3 directives, but, as you read the descriptions that follow, you will soon discover that in pN}ractice these directives are most useful in helping your 6502 assembly language production. Incidentally, all the macro-speciO}fied directives could presumably be classified as type 3. Three of the directives which follow (.PAGE, .TITLE, and .ERRP}OR) allow the user to specify a string (enclosed in Quotes) which will be printed out. For these three directives, the user iQ}s limited to a maximum string length of 70 characters. Strings longer than 70 characters will be truncated.SECTION 4.1R}.directive : *=purpose : change current origin of the assembler's location counter. The *= S}directive will assign the value of the expression to the location counter. The expression cannot be forward referenced. *= muT}st be written with no intervening spaces. Example : 50 *= $1234 ; sets the location counter U} to $1234 Another common usage of *= is to reserve space for data to be filled in or used at run time. Since theV} single character "*" may be treated as a label referencing the current location counter value, the form "*= *+exp" is thus tW}he most common way to reserve "exp" bytes for later use. Example : 70 LOC *= *+1 ; assigns the current value X} of the location counter to LOC and then advances the Y} counter by one. (Thus LOC may be thought of as a one byte reserved memory cell.)CAUTIONZ} : Because any label associated with this directive is assigned the value of the location counter BEFORE the directive is ex[}ecuted, it is NOT advisable to give a label to "*=" unless, indeed, it is being used as in the second example (i.e., as a mem\}ory reserver).NOTE : Some assemblers use "ORG" instead of "*=" and may also have a separate directive (such as "DS" o]}r "RMB") for "defining storage" or "reserving memory bytes". Use caution when converting from and to such assemblers; pay spe^}cial 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 labelusage : label = expression The =`} directive will equate "label" with the value of the expression. A "label" can be equated via "=" only once within a program.a} Example : 10 PLAYER0 = PMBASE + $200NOTE : If a "label" is equated more than once, "label" will contain the b}value of the most recent equate. This process, however, will result in an assembly error.SECTION 4.3.directive : c} .=purpose : assigns a possible transitory value to a labelusage : label .= expression Td}he .= directive will SET "label" with the value of the expression. Using this directive, a "label" may be set to one or more e}values as many times as needed in the same program. Example : 10 LBL .= 5 20 LDA #LBL ; samf}e as LDA #5 30 LBL .= 3+'A 40 LDA #LBL ; same as LDA #68CAUTION : A label whig}ch has been equated (via the "=" directive) or assigned a value through usage as an instruction label may not then be set to q}BMAC0T0 WTRB MAC19T21WTRB$MAC1T3 WTRB(BMAC4T7 WTRB5jMAC8T13 WTRB.MAC14T18WTRB>MAC22T27WTRBx MAC28T39WTRB_MAC40T50WTRBzMAC51T61WTRBXeMAC62T76WTRanother value by ".=".SECTION 4.4.directive : .BYTE [and .SBYTE]purpose : specifies the contents of ir}ndividual bytes in the output objectusage : [label] .BYTE [+exp,] (exp)(strvar) [,(exp)(strvar) ...][labs}el] .SBYTE [+exp,] (exp)(strvar) [,(exp)(strvar) ...] The .BYTE and .SBYTE directives allow the user to generate indivit}dual bytes of memory image in the output object. Expressions must evaluate to an 8-bit arithmetic result. A strvar will generu}ate as many bytes as the length of the string. .BYTE simply assembles the bytes as entered, while .SBYTE will convert the bytv}es to Atari screen codes (on the Atari) or to characters with their most significant bit on (on the Apple II). Example w}: 100 .BYTE "ABC" ,3,-1 This example will produce the following output bytes: 41 42 43 03 FFNote thatx} the negative expression was truncated to a single byte value. Example : 50 .SBYTE "Hello!" On the Atari, this y}example will produce the following screen codes: 28 65 6C 6C 6F 01 On the Apple II, the same example wouz}ld produce the following bytes: C8 E5 EC EC DF A1SPECIAL NOTE : Both .BYTE and .SBYTE allow an additiv{}e Modifier. A Modifier is an expression which will be added to all of bytes assembled. The assembler recognizes the Modifier |}expression by the presece 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 47Note especially the effect of addin}g $80 via the modifier and also adding it to the particular byte. The result is an unchanged byte, since we have added a tota}l 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} IINOTE : .SBYTE performs its conversions according to a numerical algorith and does NOT special case any control cha}racters, including CR, TAB, etc.SECTION 4.5.directive : .DBYTE [ see also .WORD ]purpose : specifies Dua}l BYTE values to be placed inthe output objectusage : [label] .DBYTE exp [,exp... ] Both the .W}ORD 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 ex}pression(s) in the reversed 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 produces : 12 34 00 01 FF FF .WORD $1234,1,-1 )±SECTION 4.6.directive : .ELSEpurpose : See description of .IF for purpose etc.SECTION 4.7.direct!}ive : .ENDpurpose : terminate an in-memory assembly The .END directive will terminate the assembly ONLY if th!}e 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) without having to edit out any .END statements they might contain. In truth, .END is generally !}not needed at all with MAC/65.SECTION 4.8.directive : .ENDIFpurpose : terminate a conditional assembly bl!}ockSee description of .IF for usage and details.SECTION 4.9.directive : .ERRORpurpose : force an assemb!}ler error and message.usage : [label] .ERROR [string] The .ERROR directive allows the user to generate a pseud!}o 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"SE!}CTION 4.10.directive : .IFpurpose : chooses to perform or not perform some portion of an assembl!}y based on the "truth" of an expression.usage : .IF exp (.ELSE) .ENDIF!}NOTE : There may be any number of lines of assembly language code or directives between .IF and .ELSE or .ENDIF and si!}milarly between .ELSE and .ENDIF. The .IF, .ELSE and .ENDIF directives control conditional assembly. When a .IF i!}s encountered, the following expression is evaluated. If it is non-zero (TRUE), the source lines following .IF will be assemb!}led, continuing until an .ELSE or .ENDIF in encountered. If an .ELSE is encountered before an .ENDIF, then all the source lin!}es between the .ELSE and the corresponding .ENDIF will not be assembled. If the expression evaluates to zero (FALSE), the sou!}rce 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. Example : 10 .IF 1 ; no!}n-zero, therefore true 20 LDA # '? ; these two lines will 30 JSR CHAROUT ; be assembled!} 40 .ENDIF Example : 10 .IF 0 ; expression is false 11 LDX #>ADDR ; these two!} lines will 12 LDY #ADDR ; be assembled 22 .ENDIF 23 JSR PRINTSTRING ; go print!}NOTE : The assembler resets the conditional stack at the beginning of each pass. Missing .ENDIF(s) will NOT be flagged.!}SECTION 4.11.directive : .INCLUDEpurpose : allows one assembly language program to request!} that another program be included and assembled in-lineusage : .INCLUDE #filespecNOTE : This !}directive should NOT have a label The .INCLUDE directive causes the assembler to begin reading source lines from the sp!}ecified "filespec". When the end of "filespec is reached, the assembler will resume reading source from the previous file (or!} memory).CAUTION : The .INCLUDE file MUST be a properly SAVEd MAC/65 tokenized program. It can NOT be an ASCII file.!}NOTE : An .INCLUDE file cannot itself contain an .INCLUDE directive. Example : .INCLUDE #D:SYSEQU.M65 Th!}is command line will include the system equates file supplied by OSS.SECTION 4.12.directive : .LOCALpurpose : !} delimits a local label regionusage : .LOCALNOTE : 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 c!}ode, 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 beginni!}ng with "?" and be sure that there will be no duplicate label errors produced. Example : 10 *= $4000 1!}1 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 line 12 17 ; 18 .LOCAL ; another local region 19 ; !} 20 ?LOOP = 6 21 ; 22 LDY #?LOOP ; same as LDY #6 23 (etc,)FE!}ATURE : Local labels MAY be forward referenced, just like any other label.NOTE : Local labels do not appear in the!} symbol table listing.SECTION 4.13.directive : .OPTpurpose : selects various assembly control OPTionsus!}age : .OPT option (or) .OPT NO optionusage notes : the valid options are as follows:!} LIST ERR EJECT OBJ MLIST CLIST NUM WAIT The .OPT directive allows the use!}r 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 !} - controls the entire assembly listing. NO LIST - turns off all listing except error lines. ERR - will d!}etermine if errors are returned to the user in the listing and/or the screen NO ERR - is thus dangerou!}s. EJECT - controls the title and page listing. NO EJECT - only turns off the automatic page generation !} - has no effect on .PAGE requests. OBJ - determines if the object code is written to t!}he device/memory. - is NECESSARY when the object code is to be placed in memory. NO OBJ !} - is useful during trial assemblies. NUM - will auto number the assembly listing instead of using!} the user line numbers. - will begin at 100 and increment by 1 - is generally not useful except f!}or final, "pretty" assemblies. MLIST - controls the listing of Macro expansions - will!} expand the entire Macro. NO MLIST - will list only the lines within a Macro expansion which generate ob!}ject code. - is extraordinary useful in producing readable listings. CLIST - controls !}the listing of conditional assembly. - will list all lines within the conditional !} construct. NO CLIST - will not list source lines which are not assembled. WAIT - will cause!} assembly to halt before printing the page number and title string Assembly will resume when !}the console START key is pressed. (or RETURN key on Apple II) - is generally us!}eful only with printers not capable of handling contiuous paper.NOTE : Unless specified otherwise by !}the user, all of the options will assume their default settings. The default settings for .OPT are: LIST listing i!}s produced ERR errors are reported EJECT pages are numbered and ejected NO NUM use programmer's l!}ine numbers MLIST all macro lines are listed CLIST all failed conditionals list NO WAIT use continuo!}us paper etc. NO OBJ SEE CAUTION!!!!!CAUTION : The OBJ option is handled in a special way:IF assembling to m!}emory the default is NO OBJ.IF assembling to a device the object option is OBJ.NOTE : Macro expansions with the NO N!}UM option will not be listed with line numbers.SECTION 4.14.directive : .PAGEpurpose : provides page head!}ings and/or moves to top of next page of listing.usage : .PAGE [ string ]usage note : no label sh!}ould 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, and prints the most recent title and page hea!}dings Example : 300 .PAGE "EXECUTE LABEL SEARCH"NOTE : The assembler will automatically eject and print the cu!}rrent title and page headings after 61 lines have been listed.SECTION 4.15.directive : .SBYTEpurpose : pr!}oduces "screen" bytes in output objectusage : see .BYTE description,section 4.4SECTION 4.16.directive : !} .SETpurpose : controls various assembler functionsusage : .SET dcnum1 , dcnum2 The .SET directive allo!}ws 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 p!}arentheses, followed by the allowable range of values.dcnum1 dcnum2 function 0 (4) 1-4 sets the .BYTE and !}.SBYTE listing format. 1 to 4 bytes can be printed in the object field 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.SECTION 4.17.d!}irective : .TABpurpose : sets listing "tab stops" for readabilityusage : .TAB dcnum1 ,dcnum2 ,dcnum3 !} The .TAB directive allows the user to specify the starting column for the listing of the instruction field, the operand fiel!}d, and the comment field respectively.The defaults are : 8, 12 , 20 Example 200 .TAB 16,32,50 ... !} 1200 .TAB 8,12,20 ; restores defaultsSECTION 4.18.directive : .TITLEpurpose : specify assemb!}ly listing headingusage : .TITLE string The .TITLE directive allows the user to specify an assembly title head!}ing. The title string will be printed at the top of every page following the page number.SECTION 4.19.directive : !} .WORD [see also .DBYTE]purpose : place 16 bit word values in output objectusage : [label] .WORD exp [,exp.!}..] The .WORD and .DBYTE directives both put the value of each following expression into the object code as two 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. }=82 =3 =109 =4 =150 =104 =117 =69 =52 =70 =53 =80 =77 =71 =72 =83 =84 =1 =45 =0 =114 =116 =120 =87 =%}2 =91 =92 =93 =123 =124 =125 =1261070800066Example : .DBYTE $1234,1,-1 produces: 12 34 00 %}01 FF FF .WORD $1234,1,-1 produces: 34 12 01 00 FF FFCHAPTER 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 upo%}n 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 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 wi%}ll be substituted for the "formal parameters" during the expansion of the Macro. The use (expansion) of a Macro in a pr%}ogram requires 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 dire%}ctives, 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 : .ENDMpurpose : end the definition of a macrousage : .%}ENDMusage note : generally, the .ENDM directive should not be labelled. This directive is used solel%}y 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 des%}cription of .MACRO for further information.SECTION 5.2.directive : .MACROpurpose : initiates a macro defi%}nitionusage : .MACRO macronameusage note : "macroname" may be any valid MAC/65 label. It may be t%}he same name as a program label (without conflict). The .MACRO directive will cause the lines following &}to be read and stored under the Macro name of "macroname". The definition is terminated with the .ENDM directive. All i&}nstructions except another .MACRO directive are valid Macro source lines. A Macro definition can NOT contain another Macro de&}finition.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 following12 ; instructions will be substituted for "PUSHXY"13 ; and then assembled.14 TXA1&}5 PHA16 TYA18 PHA19 .ENDM ;The terminator for "PUSHXY"SPECIAL NOTE : All labels used within a macro a&}re assumed to be local to that macro. MAC/65 accomplishes this by performing a "third pass" of the assembly during macro expa&}nsions. Thus, a label defined within a macro expansion is available 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 for&}ward references to internal macro labels ARE legal.An example follows, on the next page. 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. (Note that if a macro label is only defined once by a singl& }e macro usage, the effect is the same as if the label were defined outside any macro.) Although the .LOCAL-produced local reg& }ions 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.SECTION 5.3 MACRO EXPANSION I. 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 previo&}us section (5.2),one could simply 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 ; 204&}0 MOVE6 2050 ; similarly, MOVE6 is used 2060 JMP LOOP 2070 ; and LOOP refers t&}o the label 2080 ; defined in the MOVE6 macro ...NOTE : 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 conten&}ts of the macro at all. There are many more "tricks" and features usable with macros, but we will continue this discuss&}ion after an examination of macro parameters as used in a macro definition.SECTION 5.4 MACRO PARAMETERS. &}Macro parameters can be of two types : expressions or strings. The parameters are passed via the macro expansion (invocation,&} use, etc.) and are stacked in memory in the order of occurance. Amaximum of 63 parameters can be stacked by a macro expansio&}n, including expansions within expansions. However, before a parameter can be used in an expansion, there must be a w&}ay of accessing it in the MACRO DEFINITION. Parameters are referenced in a macro definition by the character "%" for expressi&}ons and the character "%$" 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 high byte of param 1 15 CMP (%11,X) ;yes, that is really number 11 20 .BYTE %2-1 ;value of param&!} 2 less 1NOTE: The above is NOT equivalent to using param %1. Param substitution has highest precedence! 25 SYM&"}BOL.= 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 reallity, the TOTAL number of parameters in use by al&$}l active (nested) macro expansions cannot exceed 63. This does NOT mean that you can have only 63 parameter references in you&%}r 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 m&'}eaning 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 to 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 param&*}eters as well.Example follows on the next page. 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 ; di&.}d user specify increment? 25 ; this is assembled if user gave two parameters 26 LDA %1 ; add "increment" to "a&/}ddress" 27 CLC 28 ADC # <%2 ; low byte of the increment 29 STA %1 ; low byte of result 30 LDA &0}%1 +1 ; high byte of location 31 ADC # >%2 ; add in high byte of increment 32 STA %1 +1 ; and store rest of res&1}ult 33 ; 34 .ELSE 35 ; this is assembled if only 1 parameter given 36 INC %1 ; just increment by 1&2} 37 BNE SKIPHI ; implicitly local label 38 INC %1 +1 ; must also increment high byte 39 SKIPHI 40 .&3}ENDIF ; matches the .IF %0>1 (line 24) 41 .ENDIF ; matches the .IF of line 18 42 .ENDM ; terminator&4}SECTION 5.5 MACRO EXPANSION II. We have shown how macro definitions may include specifications of particula&5}r parameters (the specifications might also be called "formal parameters"). This section will show how to pass actual paramet&6}ers (equivalently "value parameters", "calling parameters", etc.) to the definition. The concept is simple: on the same&7} line as the macro invocation (by use of its name, of course) and following the macro's name, the user may place expressions &8}(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 &9}expansion, replaces the formal parameters (%1, %2, %(label), etc.) with the corresponding values. Does that sound too c&:}omplicated? Internally, it is. Externally, it is as 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,INCR-2 140 BUMP 150 BUMP A.LOCATION,INC&=}R,7 160 A.LOCATION .WORD 0 note: lines 140 and 150 will each cause the BUMP error to be invo&>}ked and printed. Of course, you can also do silly things, which will no doubt produce some pretty horrible (and hard to&?} debug) code: See next page. 170 BUMP INCR,A.LOCATION will try to increment address 7 by something 180&@} BUMP PORT5 assumig the PORT5 is some hardware port, strange and wonderful things could happenS&A}ECTION 5.6 MACRO STRINGS. String parameters are represented in a macro definition by the character "%$". All nu&B}meric parameters have a string counterpart, not all of which are useful. All string parameters have a numeric counterpart (th&C}eir length).As a special case, %$0 always returns the macro NAME.The following table shows the various string and numeric&D} values returned for a given parameter:As appears in string returned numeric valueMacro call (in quo&E}tes): returned:"A String 1 2 3# "A String 1 2 3" length of stringNUMERICSYMBOL "NUMERICSYMBOL" valu&F}e of labelSYMBOL+1 "SYMBOL" value of expr%$4 the string of value of original&G} parameter 4-LABEL "LABEL" value of exprGEORGE*HARRY+PETE undefined &H} value of expr.DEF CIO "CIO" value of expr2 + 2 * 65 undefined value of exp&I}rA Macro string example: 10 .MACRO PRINT 11 ; 12 ; This macro will print the specified string, &J} 13 ; parameter 1, but if no parameter string is 14 ; passed, only an EOL will be printed. 15 ; 16 ; The call&K}ing format is : PRINT [ string ] 17 ; 18 .IF %0 = 1 ;is there a string to print? 19 JMP PASTSTR ;yes, jump&L} over string storage 20 STRING .BYTE %$1,EOL ; put string here 21 ; 22 PASTSTR 23 LDX #>STRING ; get st&M}ring address into X&Y 24 LDY #1 .OR %2=0 .WORD %1 &Y} .ENDIF The danger here occurs if the caller invokes the macro with only one parameter. Since %2 in non-existent (and h&Z}ence undefined), the sub-expression "%2=0" is indeed true and the effect of "%0>1" is nullified. Of course, the lack of param&[}eter 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 .ENDIFC. Even though labels defined within macros are local to eac&]}h invocation, they are still "visible" outside the macro(s). Thus, it might be a good idea to have a special form of labels d&^}efined in macros and avoid that form outside macros. The macro library supplied with MAC/65 uses labels beginning with "@" as&_} local labels to macros.SECTION 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. St&a}udy it carefully, please. (The line numbers are omitted for the sake of brevity. Any numbers will do, of course.); the fir&b}st 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&c} be a constant; (immediate) channel number. If passed any other; value, it assumes it to be a memory location which; conta&d}ins the channel number.; .MACRO @CH .IF %1>7 LDA %1 ; channel is in memory cellation which; conta$j=82 =3 =109 =4 =150 =104 =117 =69 =52 =70 =53 =80 =77 =71 =72 =83 =84 =1 =45 =0 =114 =116 =120 =87 =*f}2 =91 =92 =93 =123 =124 =125 =1261070800066 ASLA ASLA ASLA ASLA ; times 16 TAX*g} .ELSE LDX #%1*16 .ENDIF .ENDM;; this next macro, "@CV", is designed to load a; Constant or Value into*h} the A register. If; passed a value from 0 to 255, it assumes it; to be a constant (immediate) value. If passed; any other*i} value, it assumes it to be a memory; location (non-zero page).; .MACRO @CV .IF %1<256 LDA #%1 .ELSE *j} LDA %1 .ENDIF .ENDM;; The third macro is "@FL", designed to establish; a filespec. If passed a literal strin*k}g, @FL ; will generate the string in line, jumping around; it, and place its address in the IOCB pointed to; by the X regi*l}ster. If passed a non-zero page; label, @FL assumes it to be the label of a valid; filespec string and uses it instead.; *m} .MACRO @FL .IF %1<256 JMP *+%1+4@F .BYTE %$1,0 LDA #<@F STA ICBADR,X LDA #>@F STA ICBADR*n}+1,X .ELSE LDA #<%1 STA ICBADR,X LDA #>%1 STA ICBADR+1,X .ENDIF .ENDM;; The main macro h*o}ere is "XIO", a macro to; implement a simulation of BASIC's XIO command.; The general syntax of the usage of this maco is:*p}; XIO command, channel [,aux1,aux2][,filespec];; where channel may be a constant from 0 to 7; or a memory location; w*q}here command, aux1, and aux2 may be a constant; from 0 to 255 or a non-zero page location; where filespec may be a literal *r}string or; a non-zero page location; if aux1 and aux2 are omitted, they are assumed; to be zero (you may not omit aux2 onl*s}y); if the filespec is omitted, it is assumed to; be "S:"; .MACRO XIO .IF %0<2 .OR %0>5 .ERROR "XIO: wrong *t}number of parameters" .ELSE @CH %2 @CV %1 STA ICCOM,X ; command .IF %0>=4 @CV %3 *u} STA ICAUX1,X @CV %4 STA ICAUX2,X .ELSE LDA #0 STA ICAUX1,X STA I*v}CAUX2,X .ENDIF .IF %0=2 .OR %0=4 @FL "S:" .ELSE@FPTR .= %0 @FL %$(@FPTR) *w} .ENDIF JSR CIO .ENDIF .ENDM Did you follow all that? The trick is that, the way "XIO" is specifi*x}ed, it is legal to pass it 2, 3, 4, or 5 arguments; but each of those numbers represents a unique combination of parameters, *y}to wit: XIO command,channel XIO command,channel,filespec XIO command,channel,aux1,aux2 XIO command,c*z}hannel,aux1,aux2,filespec This is not a trivial macro example. Perhaps you will not have occasion to write something so*{} complex. But MAC/65 provides the tools to do many things if you need them.CHAPTER 6 : COMPATABILITY. *|} There are many different 6502 assemblers available, and it seems that each has a few foibles, bugs, or whatever that are uni*}}quely its own (and of course, they are called "features" by their promotors). Well, MAC/65 is no different. This chapte*~}r is devoted to telling you of some of the things to watch out for when converting from another 6502 assembler to MAC/65. We *}will restrict ourselves to suc h things as directives and operators. We will NOT go into a discussion of how to convert the a*}ctual 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 va*}rious addressing modes via special opcodes. Thus the conventional "LDA #3" becomes "LDAIMM 3" and "LDA (ZIP),Y" becomes "LDAI*}Y 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 asse*}mbler/editor cartridge (via EASMD). As much as possible, we have tried to keep MAC/65 compatible with the cartridge. Unfortun*}ately, in the interest of providing a more powerful tool, a few things had to be changed. The next section of this chapter, t*}hen, enumerates these changes.SECTION 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 enumer*}ated here, but they will not impact the transferrence of code originally designed for the cartridge (or, for that matter, EAS*}MD).SECTION 6.1.1 .OPT OBJ / NO OBJ. 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 ".)PT OBJ" direc*}tive before the code to be generated or the code will not be produced.SECTION 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 th*}is causes no problems; but watch out for mixed expressions. Example : LDA #LABEL-3/256 seen as LDA #[LABEL-3]/25*}6 by the cartridge. seen as LDA #LABEL-[3/256] by MAC/65SECTION 6.1.3 THE .IF DIRECTIVE. The imple*}mentation 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 wil print: *** ERROR -followed by th*}e error number (unless the error was generated with the .ERROR assembler directive) and, for most errors, a descriptive messa*}ge about the error.NOTE : The assembler will print up to 3 errors per line. The format used in the listing of d*}escriptions 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 macro*}s can be defined.NOTE : If memory full occurs during assembly and the source code is located in memory, SAVE the sourc*}e 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.2. INVALID DELETE Either the first line number is not present in memory, o*}r the second line number is less than the first line number.3. BRANCH RANGE A relative instruction references an addr*}ess displacement greater than 129 or less than 126 from the current address.4. NOT Z-PAGE / IMMEDIATE MODE An express*}ion for indirect addressing or immediate addressing has resolved to a value greater than 255 ($FF).5. UNDEFINED The A*}ssembler has encountered an 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 label*}s (i.e.,using ".=").7. DUPLICATE LABEL The Assembler has encountered a label in the label column which has already be*}en defined.8. BUFFER OVERFLOW The Editor syntax buffer has overflowed. Shorten the input line.9. CONDITIONALS NEST*}ING The .IF-]ELSE-.ENDIF construct is not properly nested. Since MAC/65 cannot detect excess .ENIF's the problem must b*}e an EXTRA .ELSE or .ENDIF instead.10. VALUE > 255 The result of an expression exceeded 255 when only one byte was ne*}eded.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 PHASEThe address generated in pass 2 for a label does not matc*}h the address generated in pass 1. A common cause of this error are forward referenced addresses. If using conditional assemb*}ly (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 # 6*}5535 The Editor cannot accept line numbers greater than 65535.18. MISSING .ENDM In a Macro definition, an EOF w*}as reached before the corresponding .ENDM terminator. Macro definitions cannot cross file boundaries. This error will abort a*}ssembly.19. NO ORRIGIN 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 grea*}ter than 65535. If REN issued the error, entering a valid REN will correct the problem. If NUM issued the error, the auto-num*}bering will be aborted.21. NESTED .INCLUDE An included file cannot itself contain an .INCLUDE directive.22. LI*}ST OVERFLOW The list output buffer has exceeded 255 characters. Use smaller numbers in the .TAB directive.23. NOT SAV*}E FILE An attempt was made to load or assemble a file not created with the SAVE command.24. LOAD TOO BIG The lo*}ad 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 in a .SET specified a non-existent Assembler system parameter.30. UN*}DEFINED MACRO The Assembler encountered a reference to a Macro which is not defined. Macros must first be defined befor*}e they can be expanded.31. MACRO NESTING The maximum level of Macro nesting has exceeded 14 levels.32. BAD PARAMETE*}R 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 the operating system. Refer*} to the OS/A+ manual for detailed descriptions of such errors and their causes. are generated in the operating system. Refer(P/