- Release notes for v.8beta -¢¢This is almost, but not quite complete. I'm still working on some changes¢to the debugger, and for now, an older version is included with the¢assembler. This version resides entirely in main system RAM, which¢partially undermines the fact that the rest of the package is designed to¢fit mostly in bank select memory. Thus, this version takes up almost 5K¢of system RAM, whereas the final version will only require 1-2K.¢¢Note for non-SpartaDOS users. The MAE.COM file does not have a DOS II run¢address appended to it, and so it will not automatically run as is.¢However, I have included a file called RUNAD.OBJ that you should append¢onto the end of the MAE.COM file in order to make the assembler auto-run.¢The RUNAD wasn't included in the file, because it can mess up the automatic¢return to the program from SpartaDOS using the RUN command. I feel it is¢very important to be able to easily switch to DOS and back without losing¢anything. To return to the assembler from any non-Sparta DOS, you can run¢at the address $A900.¢¢Another note for non-Sparta users. The assembler picks up the current¢drive number from the SpartaDOS variable structure. An attempt has been¢made to bypass this step for non-Sparta DOSes, but I don't know for sure¢if it will work in all cases. Worst case, you will find the default drive¢set to something other than what is stored in the configure section. This¢can easily be reset from the assembler menu.¢¢Please report any and all bugs and suggestions. I can be reached on GEnie¢at J.HARRIS32, or on internet at jharris@cup.portal.com. More¢conventional access is available at:¢¢John Harris¢45346 Graceway Dr.¢Ahwahnee, CA 93601¢(209)683-3412¢¢On to the assembler...¢¢- STRENGTHS -¢¢Excellent full screen editor with many features such as key macros,¢automatic 'JSR' and return to subroutine labels, block moves and copies,¢multiple undo.¢¢XEP80 compatable.¢¢High level of integration between editor-assembler-debugger. The editor¢can take you directly to lines that had assembly errors. The debugger can¢reference labels in the symbol table and assemble single program lines.¢¢Very user friendly -- it will save you a lot of typing. (Now, if I could¢have just gotten it to type this DOC file for me. Sigh...)¢¢Local labels referenced between global labels.¢¢Can assemble directly to bank select memory or bank select cartridges.¢¢Uses very little system RAM. Most of the code resides in bank select¢memory.¢¢Full 65816 and 24 bit support.¢¢- WEAKNESSES -¢¢Simple implementation of macro ability, compared with Mac/65 or other more¢advanced macro assemblers. Only expression values can be passed as¢parameters.¢¢Slower assembly speed than Mac/65 -- especially with large source files.¢There are a few things that can partly offset this though. You can start¢the assembly at Pass 2 if no changes have been made that effect the symbol¢table values. This can more than double the assembly speed in these¢cases. You can also include binary files within the assembly, for¢pre-assembled code or data segments. If you program in a modular fashion,¢avoiding the constant reassembly of large unchanged portions of code, you¢will of course completely avoid any speed problems.¢¢I don't know how many people I may have scared at this point. This¢assembler is not depressingly slow. It takes 45 seconds to assemble¢itself, and while Mac/65 could do it in 10 seconds, I would spend a whole¢lot more than 35 seconds fighting with its inept editor. I prefer to rate¢the speed of a development system in terms of how long it would take to¢write a program with it. In this regard, I don't think this assembler can¢be beat. Enough of defending this product. I'm proud of it the way it¢is, and I hope you'll enjoy using it.¢¢- MEMORY USAGE -¢¢This assembler is designed to run in one bank of the extended memory¢available on the 130XE or other memory expanded Atari. This bank number¢is configurable. A portion of the assembler must reside outside of bank¢select RAM, and in this version, it will occupy $A900-$BBFC. Memory usage¢for the source file and symbol table is also configurable. In addition,¢memory for the symbol table will use bank select RAM when the addresses¢are within the $4000-$7FFF range, while memory for the source file will¢always be in normal system RAM. This allows memory for the source file¢and symbol table to overlap, and gives you the largest possible free¢memory buffer. Having the symbol table in bank select RAM has one other¢benefit. It will usually stay intact so that the labels can be used from¢the debugger. The default values for memory usage are to place the symbol¢table from $6400-$7FFF and the source buffer from LOMEM to $A8FF. The¢file ED.DOC has specific instructions about changing the memory¢configurations.¢¢Zero page memory is saved and restored from the editor and assembler, so¢that they will effectively leave all of ZP available to the user. The¢debugger is using locations $F4-$FF right now, but this will change in a¢future release. For now, you should avoid using these locations.¢¢All three modules use a $100 byte buffer in low memory that is currently¢at $400-$4FF. Please contact me if these locations conflict with your¢setup, and I can assemble a version that uses a different area.¢¢When assembling to disk files, a $100 byte buffer is used for disk I/O.¢The location of this buffer is configurable, as described in ED.DOC, and¢is currently set to use $500-$5FF.¢¢- EXPRESSIONS -¢¢Expressions can be made from decimal numbers, hex numbers by using "$",¢binary numbers by using "%", single ASCII characters with a "'" (single¢quote), and label names.¢¢Any of these values can be mixed with math operators +-*/, ! (bitwise¢OR), & (bitwise AND), and unary -. The | vertical bar can be used in¢place of !.¢¢There are also special operators that refer to the low byte, high byte,¢and bank byte (24 bit highest byte) of the calculated expression. These¢operators are <, >, and ^.¢¢There is no operator precedence. All math is evaluated left to right,¢with the exception of <, >, and ^, which are done after the rest of the¢expression has been evaluated.¢¢Examples of valid expressions:¢¢ LDA #-1 ;= $FF¢ LDA #'A-$20 ;= $21¢ LDA #%101&3 ;= 1¢ LDA #>$1234+1 ;= $12¢ LDA #^$123456 ;= $12¢ LDA #>$123456 ;= $34 (mid byte)¢¢All of these expression types can be used in .BY statements as well.¢Like:¢¢LOWS .BY <LABEL1 <LABEL2 <LABEL3¢HIGHS .BY >LABEL1 >LABEL2 >LABEL3¢ .BY 15+3!%1000¢ etc...¢¢- LABELS -¢¢The first character of a label may be any letter, or the symbols @, \, ^,¢_, or ?. All remaining characters may also include numbers plus the¢symbols ., \, :, ;, <, =, and >. Labels may be up to 15 characters long.¢¢Label names, and for that matter all text entered with the assembler, can¢be entered in upper or lower case. Labels are not case-sensitive.¢¢When the first character of a label is '?', the label is a 'local label'.¢Locals are defined only in the source code segment between two global¢(i.e. non-local) labels. References to local labels cannot cross a¢global label definition.¢¢Internally, the assembler creates local labels by appending the local onto¢the end of the previous global label. Thus in the following code segment:¢¢DELAY LDX #100¢?L DEX¢ BNE ?L¢¢'?L' is a local label, and will be entered in the symbol table as DELAY?L.¢Knowing how the label is stored, allows you to access it from the debugger¢or the Esc-V expression evaluator. You can also code a direct reference¢to the label DELAY?L if you need to access the local from the other side¢of the global label DELAY.¢¢Locals are not printed in X-reference or symbol table listings, which¢makes them most useful for simple loop and branch structures where you¢don't want to think up unique label names for all occurances.¢¢- ADDRESSING MODES -¢¢All 6502 and 65816 addressing modes are supported. Any addresses that¢evaluate less than $100 will use zero page modes when possible. Thus,¢zero page labels must be defined before being used, or assembly errors¢will result.¢¢There is also a way to force 8 bit, 16 bit, or 24 bit addresses using the¢operators <, !, and >. (Yes, I know this is inconsistant with the¢immediate operators for low, high and bank bytes -- I didn't write the¢65816 assembler specifications). This can be really useful for forcing¢absolute 16 bit addressing on zero page labels, to add 1 cycle in time¢critical applications. For the 65816, it can force direct page addressing¢for non-ZP labels, (which of course requires you to move the direct page¢register to the proper page address). All 24 bit addresses must be¢preceded by the > character.¢¢The operands for the 65816 MVP and MVN instructions should be simple bank¢bytes -- not full addresses. Ex:¢¢ MVP $40 $80¢moves memory from bank $40 to bank $80, using the addresses in X and Y.¢¢- PSUEDO OPS -¢¢Note that only 2 letters are required, but if additonal letters are¢present they will be truncated without assembly errors. For example, you¢may use psuedo ops like '.byte' and '.org'. Personaly, I really like¢having the psuedo ops the same width as all 6502 instructions, and only¢use 2 letters.¢¢ .24¢Sets the symbol table and program counter to use 24 bit addresses.¢This is only useful for 65816 programs.¢¢ .AB¢The assembler will generate byte-sized values for accumulator-related¢immediate constants. (Default)¢¢ .AW¢The assembler will generate word-sized values for accumulator-related¢immediate constants. This is only useful for 65816 programs.¢¢ .BA byte¢For bank addressing, you can specify an operand to force assembler¢generated object code into bank select RAM. If the operand is >= $80,¢this value will be stored into location $D301 when storing bytes of object¢code into RAM. Operands less than $80 are placed in the X register, and a¢STA $D580,X is performed. This can control certain bank select cartridge¢devices. NOTE: For using the second method of bank addressing, the¢assembler should be able to return the bank select cartridge to normal.¢There is currently a 'STA $D5DC' for this purpose, but this may not be the¢right address for your cartridge setup. You should search the disk file¢for this instruction, ($8D $DC $D5), and replace it with the appropriate¢address.¢¢ .BI filename¢Includes the contents of a binary disk file into the assembly. If this¢file does not contain a DOS binary header, it will be assembled as in-line¢data at the current PC. Otherwise, a file that contains a header will be¢loaded at its load address.¢¢ .BY [+byte] bytes and/or ASCII¢Store byte values in memory. ASCII strings can be specified by enclosing¢the string in either single or double quotes.¢¢If the first character of the operand field is a '+', then the following¢byte will be used as a constant and added to all remaining bytes of the¢instruction.¢¢Ex:¢ .BY +$80 1 10 $10 'Hello' $9B¢¢will generate:¢81 8A 90 C8 E5 EC EC EF 1B¢¢Values in .BY statements may also be separated with commas for¢compatability with other assemblers.¢¢See also .SB which creates ATASCII screen codes.¢¢ .CL¢Close output object code file. When using the .OU psuedo op to create¢object code files on disk, the file will normally be closed at the end of¢assembly. However, if you wish to close the file before that, it can be¢forced closed with the .CL psuedo op. You may use this to create multiple¢output files in one assembly, or to place something in RAM in addition to¢the disk file.¢¢ .DC word byte¢Define constant-filled block. This will fill an area of size 'word' with¢the constant 'byte'.¢¢ .DS word¢Define storage. This will reserve an area of storage equal to size¢'word'.¢¢ .EC¢Do not display macro generated code in the assembly listing. Only the¢macro call itself will appear.¢¢ .EJ¢Eject -- Send a form feed code to eject the page in an assembly listing.¢¢ .EN¢Mark End of assembly. This psuedo op *must* be present to end the¢assembly, or an error will result.¢¢ .ES¢Display the code resulting from Macro expansions.¢¢ .HE hex bytes¢Store hex bytes in memory. This is a convenient method to enter strings¢of hex bytes, since it does not require the use of the '$' character. The¢bytes are still separated by spaces however, which I feel makes a much¢more readable layout than the 'all run together' form of hex statement¢that some other assemblers use. Example:¢ .HE 0 55 AA FF¢¢ .IB¢The assembler will generate byte-sized values for index register-related¢immediate constants. (Default)¢¢ .IW¢The assembler will generate word-sized values for index register-related¢immediate constants. This is only useful for 65816 programs.¢¢ .IN filename¢Include additional files in the assembly. Only the main source file can¢contain .IN psuedo ops. You cannot nest them. Default drive processing¢works the same here as it does when loading files from the editor, and so¢you will usually not need any 'Dn:' types of filespecs. The file name¢only should be sufficient.¢¢ .LC¢Turn off (clear) the display of the assembly listing. (Default)¢¢ .LL¢Display the assembly listing on this line only, even if the full listing¢is turned off. This can be extremely handy to display the program counter¢value at important positions in the source file.¢¢ .LO long¢Stores a longword, 3 byte value in memory. Only one operand is supported.¢¢ .LS¢Turn on (set) the display of the assembly listing.¢¢ .MC adr¢Move Code to a different address when storing object code in memory. This¢is in case the .OR assembly address conficts with something already at¢that location in memory.¢¢!!!name .MD ([label1] [label2]...)¢Begin macro definition. Described in a separate section.¢¢ .ME¢End macro definiton.¢¢ .MG¢Mark the current .IN include file as Macro Global. This keeps this file¢in memory thruought the assembly, which is required if the file contains¢macros that are referenced in other .IN files.¢¢ .OC¢Turn off (clear) the storing of object code in memory.¢¢ .OR adr¢Sets the origin address for the assembly.¢¢Note: If there is a label on this line, it will be given the value of the¢new origin. This is not the same as in Mac/65 which could use its origin¢directive to reserve space (*= *+1). You should use the .DS psuedo op for¢reserving space.¢¢ .OS¢Turn on (set) the storing of object code in memory. (Default)¢¢ .OU filename¢Create an output disk file for the object code. Regretfully, this file is¢made up of individual 256 byte segments much like Mac/65 does. I¢apologize for the laziness here on my part, but it realy was a lot easier¢to do this way. You will need to run some type of strip program to¢de-segment the file.¢¢ .PR "text"¢Print a text message to the screen on pass 1 of the assembly. This is¢generally used with the .VA psuedo op when prompting for values to be¢entered from the keyboard.¢¢ .SB [+byte] bytes and/or ASCII¢This is in the same format as the .BY psuedo op, except that it will¢convert all bytes into ATASCII screen codes before storing them. The¢ATASCII conversion is done before any constant is added with the '+'¢modifier.¢¢label .VA¢Will print a '?', and then accept input from the keyboard. You may enter¢any value, which will be given to the label in front of the .VA.¢¢ .WO word¢Stores a word in memory. Only one operand is supported.¢¢ SET label = expression¢Set the specified label to a new value. This instruction allows a label¢to be redefined with different values during the assembly. Any label can¢be SET.¢¢- CONDITIONAL ASSEMBLY -¢¢There are four conditional instructions IFE, IFN, IFP, and IFM, that¢represent conditional assembly if Equal, Not equal, Positive, and Minus.¢The operand of the IF instruction will be evaluated, and if the processor¢status codes match the type of IF statement, then the source code¢following the IF will be assembled. Mark the end of the conditional block¢of code with the psuedo op '***'. (*** is like an ENDIF statement).¢¢There is no 'ELSE' instruction, and so you must use complimenting IF¢statements.¢¢Examples:¢¢ IFN FLAG¢ . ;This block of¢ . ;code gets asm'ed¢ . ;when FLAG <> 0¢ ***¢¢ IFE FLAG¢ . ;This block does¢ . ;when FLAG=0¢ ***¢¢ IFN FLAG1!FLAG2¢ . ;asm'ed if FLAG1¢ . ;or FLAG2 <> 0¢¢ IFE WIDTH-40¢ . ;This gets asm'ed¢ . ;when width=40¢ ***¢¢ IFM WIDTH-40¢ . ;asm'ed if WIDTH¢ . ;less than 40¢ ***¢¢ IFP WIDTH-40¢ . ;if WIDTH greater¢ . ;or equal to 40¢¢- MACROS -¢¢Macros must be defined before they are used in your source. The¢definition looks like this:¢¢!!!name .MD ([label1] [label2]...)¢¢Where 'name' is the name of the macro, and 'label1' etc. are its¢parameters. The three exclamation marks are a special macro identifier,¢and must precede the macro name. The body of the macro definition will¢follow, and should be ended with a .ME psuedo op.¢¢The number of parameters used when calling the macro must always match the¢number of labels in the definition. When called, these parameters will be¢placed into the label names, in order, where they can be used in the body¢of the macro. Parameters can only be expressions -- there is no method¢for passing arbitrary text strings.¢¢Macros can pass up to 8 parameters.¢¢Any labels defined within a macro must use a special form. Because macros¢can be expanded multiple times, a special label type exists to avoid¢errors from multiple label definitions. These label types start with¢three periods, followed by any normal label name. These special macro¢labels will be given unique numbers with each macro expansion to keep them¢separate. You can consider them local labels to each macro expansion.¢¢Here's an example of a macro to increment a two byte value:¢¢!!!IND .MD (LOC)¢ INC LOC¢ BNE ...SKP¢ INC LOC+1¢...SKP .ME¢¢To call this macro, you would use:¢¢ IND $80¢¢- ERROR MESSAGES -¢¢These are the error messages that can be produced by the assembler. Error¢messages are marked with an '!', and also include the source line number¢that they occured on. If you are assembling a single file, or if the¢errors occurs in your main file, you will be able to use the editor ^H¢command to jump directly to the errors. For errors that occur in included¢files, you will need to load in that portion, and jump to those line¢numbers manually using the ^G goto line number command.¢¢ BRANCH¢Branch instruction out of range.¢¢ OPCODE¢Error in opcode field. This can be either a bad 6502 instruction, bad¢psuedo op, or an undefined macro.¢¢ DUP¢Duplicate label definiton.¢¢ EOF¢End Of File error. All assemblies must end with a .EN psuedo op. This¢should be in the main source file, not in any included files. This error¢can also occur if a conditional or macro definition is pending at the .EN.¢¢ UNDEF¢Undefined label reference.¢¢ NEST¢Nested definition. IF conditionals may not be nested. .MD macro¢definitions cannot contain additional definitions.¢¢ OPERAND¢Error in operand field.¢¢ ADR MODE¢Addressing mode not spported.¢¢ BAD LABEL¢Bad characters in label name.¢¢ MACRO OV¢Macro overflow in either the number of expansions, or level of nested¢expansions.¢¢ SYM OV¢Symbol table overfow.¢¢ PARMS¢Number of macro parameters in the call does not match the definition.¢¢ LABEL MISSING¢Missing label on either a SET psuedo op or in an = equate definition.¢
