8bitfiles.net/archives

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

/ 8bitfiles.net/archives / archives.tar / archives / genie-commodore-file-library / C64-128Toolkit / ACE14E.SFX / ace14-as.doc next >

Wrap

Text File | 1990-02-12 | 43.5 KB | 897 lines

┴├┼ ┴SSEMBLER ─OCUMENTATION FOR VERSION 1.00 [╧CTOBER 23, 1994] ------------------------------------------------------------------------------ 1. ╔╬╘╥╧─╒├╘╔╧╬ ╘HE ┴├┼ ASSEMBLER IS A ONE-PASS ASSEMBLER. ╘HE ONLY REAL LIMITATION ON THE SIZE OF ASSEMBLY JOBS IS THE AMOUNT OF NEAR+FAR MEMORY YOU HAVE AVAILABLE. ╠ABELS ARE "LIMITED" TO 240 CHARACTERS (ALL SIGNIFICANT), AND THE OBJECT SIZE IS LIMITED TO 64╦ (OF COURSE). ╬UMERICAL VALUES ARE "LIMITED" TO 32-BITS OR LESS. ╥ELATIVE LABELS ("+" AND "-" LABELS) ARE IMPLEMENTED IN THE SAME WAY AS IN THE ┬UDDY ASSEMBLER. ╧NLY ADD AND SUBTRACT DYADIC OPERATORS ARE CURRENTLY IMPLEMENTED FOR EXPRESSIONS WITH POSITIVE, NEGATE, HIGH-BYTE, AND LOW-BYTE MONADIC OPARATORS, AND THE PLANNED MACRO AND CONDITIONAL ASSEMBLY FEATURES ARE NOT YET IMPLEMENTED. ┼XPRESSIONS ARE LIMITED TO 17 OPERANDS (WITH 255 MONADIC OPERATORS EACH), BUT REFERENCES TO UNRESOLVED IDENTIFIERS ARE ALLOWED ANYWHERE, INCLUDING EQUATE DEFINITIONS. ╚IERARCHICAL INCLUSION OF SOURCE FILES IS NOT YET IMPLEMENTED. ╘HE ┴├┼ SOURCE CODE WILL EVENTUALLY BE CONVERTED TO USE THIS ASSEMBLER. ╘HE ASSEMBLER CODE ITSELF HAS BEEN CONVERTED. ╘HE ASSEMBLER IS DESIGNED TO BE A "HEAVY HITTER", OPERATES AT MODERATE SPEED, AND USES A FAIR AMOUNT OF DYNAMICALLY ALLOCATED MEMORY. ╔N FACT, ON AN UNEXPANDED 64, YOU WON'T BE ABLE TO ASSEMBLE PROGRAMS THAT ARE TOO LARGE, INCLUDING THE ASSEMBLER ITSELF (85╦ OF SOURCE). ┘OU'LL BE ABLE TO DO LARGER JOBS ON AN UNEXPANDED 64 IF YOU DEACTIVATE THE SOFT-80 SCREEN IN THE CONFIGURATION. ╔'LL BE WORKING ON MAKING MORE ╥┴═0 MEMORY AVAILABLE TO ┴├┼ APPLICATIONS. (╧F COURSE, ONE COULD ARGUE THAT ANY SERIOUS 64 HACKER WOULD HAVE EXPANDED MEMORY ANYWAYS...). ╔N ADDITION TO THE REGULAR 6502 INSTRUCTIONS, THIS RELEASE OF THE ASSEMBLER HAS THE FOLLOWING DIRECTIVES: LABEL = VALUE ;ASSIGN GIVEN VALUE TO THE LABEL LABEL: ;ASSIGN THE CURRENT ASSEMBLY ADDRESS TO LABEL + ;GENERATE A TEMPORARY LABEL, ASSIGN CUR ADDRESS - ;GENERATE A TEMPORARY LABEL, ASSIGN CUR ADDRESS ORG ADDRESS ;SET THE ORIGIN OF THE ASSEMBLY BUF SIZE ;RESERVE "SIZE" BYTES OF SPACE,FILLED WITH ZEROES DB VAL1, VAL2, ..., VAL╬ ;PUT BYTE VALUES INTO MEMORY DW VAL1, VAL2, ..., VAL╬ ;PUT WORD VALUES INTO MEMORY DT VAL1, VAL2, ..., VAL╬ ;PUT "TRIPLE" (3-BYTE) VALUES INTO MEMORY, LO->HI DL VAL1, VAL2, ..., VAL╬ ;PUT "LONG" (4-BYTE) VALUES INTO MEMORY, LO->HI ╘HESE FEATURES IS DESCRIBED IN MORE DETAIL BELOW. ╬OTE THAT THROUGHOUT THE DOCUMENTATION, ╔ USE THE TERMS "IDENTIFIER", "SYMBOL", AND "LABEL" INTERCHANGEABLY. ------------------------------------------------------------------------------ 2. ╒╙┴╟┼ ╘HE USAGE FOR THE AS COMMAND IS, STATED IN ╒NIX NOTATION: USAGE: AS [-HELP] [-S] [-D] [FILE ...] ╘HE "-HELP" FLAG WILL CAUSE THE ASSEMBLER DISPLAY THE USAGE INFORMATION AND THEN EXIT, WITHOUT ASSEMBLING ANY CODE. ┴CTUALLY, ANY FLAG THAT IT DOESN'T UNDERSTAND WILL BE TAKEN AS IF YOU HAD SAID "-HELP", BUT NOTE THAT IF YOU TYPE THE "AS" COMMAND ALONE ON A COMMAND LINE THAT USAGE INFORMATION WILL NOT BE GIVEN. ╘HE "-S" FLAG TELLS THE ASSEMBLER TO GENERATE A SYMBOL-TABLE LISTING WHEN THE ASSEMBLY JOB IS FINISHED. ╘HE TABLE IS FORMATTED FOR AN 80-COLUMN DISPLAY. INDICATES THAT A SYMBOL TABLE SHOULD BE GENERATED WHEN THE ASSEMBLY JOB IS DONE. ╘HE TABLE WILL LOOK LIKE: ╘HE "-D" FLAG TELLS THE ASSEMBLER TO PRODUCE DEBUGGING INFORMATION WHILE IT IS WORKING. ╔T WILL GENERATE A LOT OF OUTPUT, SO YOU CAN SEE EXACTLY WHAT IS GOING ON. ╘HE OBJECT-CODE MODULE NAME WILL BE "A.OUT" UNLESS THE NAME OF THE FIRST SOURCE FILE ENDS WITH A ".S" EXTENSION, IN WHICH CASE THE OBJECT MODULE WILL BE THE BASE NAME OF FIRST SOURCE FILE (WITHOUT THE EXTENSION). ╘HE OBJECT MODULE WILL BE WRITTEN AS A ╨╥╟ FILE AND WILL BE IN ├OMMODORE-─╧╙ PROGRAM FORMAT: THE FIRST TWO BYTES WILL BE THE LOW AND HIGH BYTES OF THE CODE ADDRESS, AND THE REST WILL BE THE BINARY IMAGE OF THE ASSEMBLED CODE. ╔F NO SOURCE FILENAME IS GIVEN ON THE COMMAND LINE, THEN INPUT IS TAKEN FROM THE STDIN FILE STREAM (AND WRITTEN TO "A.OUT"). ╔F MORE THAN ONE FILENAME IS GIVEN, THE EACH IS READ, IN TURN, INTO THE SAME ASSEMBLY JOB (AS IF THE FILES WERE "CAT"TED TOGETHER INTO ONE SOURCE FILE). (╘HIS WILL CHANGE SUBTLY WHEN THE ASSEMBLER IS COMPLETED). ╘HIS ASSEMBLER DOES NOT PRODUCE A LISTING OF THE CODE ASSEMBLED AND WILL STOP THE WHOLE ASSEMBLY JOB ON THE FIRST ERROR IT ENCOUNTERS. ------------------------------------------------------------------------------ 3. ╘╧╦┼╬╙ ╫HILE READING YOUR SOURCE CODE, THE ASSEMBLER GROUPS CHARACTERS INTO TOKENS AND INTERPRETS THEM AS A COMPLETE UNIT. ╘HE ASSEMBLER WORKS WITH FIVE DIFFERENT TYPES OF TOKENS: IDENTIFIERS, NUMERIC LITERALS, STRING LITERALS, SPECIAL CHARACTERS, AND END-OF-FILE (EOF). ┼OF IS SPECIAL SINCE IT DOESN'T ACTUALLY INCLUDE ANY CHARACTERS, AND ITS ONLY MEANING IS TO STOP READING FROM THE CURRENT SOURCE. ┘OUR INPUT SOURCE FILE SHOULD CONSIST ONLY OF CHARACTERS THAT ARE PRINTABLE IN STANDARD ┴╙├╔╔ (DON'T BE CONFUSED BY THIS; THE ASSEMBLER EXPECTS ITS INPUT TO BE IN ╨┼╘╙├╔╔) PLUS ╘┴┬ AND ├ARRIAGE-╥ETURN. ╧THER CHARACTERS MAY CONFUSE THE ASSEMBLER. ╔DENTIFIERS CONSIST OF A LOWECASE OR UPPERCASE LETTER OR AN UNDERSCORE FOLLOWED BY A SEQUENCE OF SUCH LETTERS OR DECIMAL DIGITS. ╘HIS IS A PRETTY STANDARD DEFINITION OF AN IDENTIFIER. ╔DENTIFIERS ARE LIMITED TO 240 CHARACTERS IN LENGTH AND AN ERROR WILL BE REPORTED IF YOU TRY TO USE ONE LONGER THAN THAT. ┴LL OF THE CHARACTERS OF ALL IDENTIFIERS ARE SIGNIFICANT, AND LETTERS ARE CASE-SENSITIVE. ╚ERE ARE SOME EXAMPLES OF ALL-UNIQUE IDENTIFIERS: HELLO ╚ELLO _TIME4 A1_X140╩ ╚ELLO╘HERE╘HIS╔S┴_╠ONG╧NE ╬UMERIC LITERALS COME IN THREE TYPES: DECIMAL, HEXADECIMAL, AND BINARY. ─ECIMAL LITERALS CONSIST OF AN INITIAL DIGIT FROM 0 TO 9 FOLLOWED BY ANY NUMBER OF DIGITS, PROVIDED THAT THE VALUE DOES NOT EXCEED 2^32-1 (APPROX. 4 BILLION). ┴LL TYPES OF LITERALS CAN ALSO HAVE EMBEDDED UNDERSCORE CHARACTERS, WHICH ARE IGNORED BY THE ASSEMBLER. ╒SE THEM GROUPING DIGITS (LIKE THE COMMA FOR BIG ┴MERICAN NUMBERS). ╚EXADECIMAL LITERALS CONSIST OF A DOLLAR SIGN ($) FOLLOWED BY ANY NUMBER OF HEXADECIMAL DIGITS, PROVIDED THE VALUE DOESN'T OVERFLOW 32 BITS. ╚EXADECIMAL DIGITS INCLUDE THE DECIMAL DIGITS (0-9), AND THE FIRST SIX UPPERCASE OR LOWERCASE LETTERS OF THE ALPHABET (EITHER A-F OR ┴-╞). ╚EXADECIMAL LITERALS CAN ALSO HAVE EMBEDDED UNDERSCORE CHARACTERS FOR SEPARATORS. ┬INARY LITERALS CONSIST OF A PERCENT SIGN (%) FOLLOWED BY ANY NUMBER OF BINARY DIGITS THAT DON'T OVERFLOW 32-BITS VALUES. ╘HE BINARY DIGITS ARE, OF COURSE, 0 AND 1, AND LITERALS MAY INCLUDE EMBEDDED UNDERSCORE CHARACTERS. ╬OTE THAT NEGATIVE VALUES ARE NOT LITERALS. ╚ERE ARE SOME EXAMPLES OF VALID LITERALS: 0 123 0001 4_294_967_295 $AE╞╞ $0123_4567 %010100 %110_1010_0111_1010 ╙TRING LITERALS ARE SEQUENCES OF CHARACTERS ENCLOSED IN EITHER SINGLE (') OR DOUBLE (") QUOTATION MARKS. ╘HE ENCLOSED CHARACTERS ARE NOT INTERPRETED TO BE INDEPENDENT TOKENS, NOMATTER WHAT THEY ARE. ╧NE EXCEPTION IS THAT THE CARRIAGE-RETURN CHARACTER CANNOT BE ENCLOSED IN A STRING (THIS NORMALLY INDICATES AN ERROR ANYWAY). ╘O GET SPECIAL NON-PRINTABLE CHARACTERS INTO YOUR STRINGS, AN "ESCAPE" CHARACTER IS PROVIDED: THE BACKSLASH (\). ╔F THE BACKSLASH CHARACTER IS ENCOUNTERED, THEN THE CHARACTER FOLLOWING IT IS INTERPRETED AND A SPECIAL CHARACTER CODE IS PUT INTO THE STRING IN PLACE OF THE BACKSLASH AND THE FOLLOWING CHARACTER. ╚ERE ARE THE CHARACTERS ALLOWED TO FOLLOW A BACKSLASH: ├╚┴╥ ├╧─┼ ═┼┴╬╔╬╟ ---- ---- -------- \ 92 BACKSLASH CHARACTER (\) N 13 CARRIAGE RETURN (NEWLINE) B 20 BACKSPACE (THIS IS A NON-DESTRUCTIVE BACKSPACE FOR ┴├┼) T 9 TAB R 10 GOTO BEGINNING OF LINE (FOR ┴├┼, LINEFEED FOR ├┬═) A 7 BELL SOUND Z 0 NULL CHARACTER (OFTEN USED AS A STRING TERMINATOR IN ┴├┼) ' 39 SINGLE QUOTE (') E 27 ESCAPE 0 0 NULL CHARACTER Q 34 QUOTATION MARK " 34 QUOTATION MARK ╙O, IF YOU REALLY WANT A BACKSLASH THEN YOU HAVE TO USE TWO OF THEM. ╔F YOU WISH TO INCLUDE AN ARBITRARY CHARACTER IN A LITER STRING, NO FACILITY IS PROVIDED FOR DOING THAT. ╚OWEVER, THE ASSEMBLER WILL ALLOW YOU TO INTERMIX STRINGS AND NUMERIC EXPRESSIONS AT A HIGHER LEVEL, SO YOU CAN DO IT THIS WAY. ╙TRINGS ARE LIMITED TO INCLUDE 240 (ENCODED) CHARACTERS OR LESS. ╘HIS IS REALLY NO LIMITATION TO ASSEMBLING, SINCE YOU CAN PUT AS MANY STRING LITERALS CONTIGUOUSLY INTO MEMORY AS YOU WISH. ╚ERE ARE SOME EXAMPLES: "╚ELLO THERE" "ERROR!\A\A" 'FILE "OUTPUT" COULD NOT BE OPENED\N\0' "YOU 'DUMMY'!" 'YOU \'DUMMY\'!' "╚ERE ARE TWO BACKSLASHES: \\\\" ╙PECIAL CHARACTERS ARE SINGLE CHARACTERS THAT CANNOT BE INTERPRETED AS ANY OF THE OTHER TYPES OF TOKENS. ╘HESE ARE USUALLY "PUNCTUATION" CHARACTERS, BUT CARRIAGE RETURN IS ALSO A SPECIAL-CHARACTER TOKEN (IT IS A STATEMENT SEPARATOR). ╙OME EXAMPLES FOLLOW: , ( # & ) = / ? \ ▐ █ ╘OKENS ARE SEPARATED BY EITHER THE NEXT CHARACTER OF INPUT NOT BEING ALLOWED TO BELONG TO THE CURRENT TOKEN TYPE, OR ARE SEPARATED BY WHITESPACE. ╫HITESPACE CHARACTERS INCLUDE ╙╨┴├┼ (" ") AND ╘┴┬. ╬OTE THAT CARRIAGE RETURN IS NOT COUNTED AS WHITESPACE. ├OMMENTS ARE ALLOWED BY USING A ";" CHARACTER. ┼VERYTHING FOLLOWING THE SEMICOLON UP TO BUT NOT INCLUDING THE CARRIAGE RETURN AT THE END OF THE LINE WILL BE IGNORED BY THE ASSEMBLER. (╔ MAY IMPLEMENT AN ARTIFICAL-INTELLIGENCE COMMENT PARSER TO MAKE SURE THE ASSEMBLER DOES WHAT YOU WANT IT TO, BUT THIS WILL BE STRICTLY AN OPTIONAL, TIME-PERMITTING FEATURE). ------------------------------------------------------------------------------ 4. ┼╪╨╥┼╙╙╔╧╬╙ ╬UMERIC EXPRESSIONS CONSIST OF OPERANDS AND OPERATORS. ╔F YOU DON'T KNOW WHAT OPERANDS AND OPERATORS ARE, THEN GO BUY AN ELEMENTARY-SCHOOL MATH BOOK. ╘HERE ARE SIX TYPES OF OPERANDS: NUMERIC LITERALS, SINGLE-CHARACTER STRING LITERALS, IDENTIFIERS, THE ASTERISK CHARACTER, ONE OR MORE PLUS SIGNS, AND ONE OR MORE MINUS SIGNS. ╘HESE LAST THREE TYPES CAN MAKE PARSING AN EXPRESSION A BIT CONFUSING, BUT THEY ARE NECESSARY AND USEFUL. ╬UMERIC LITERALS ARE PRETTY EASY TO THINK ABOUT. ╘HEY'RE JUST 32-BIT NUMBERS AND WORK IN THE USUAL WAY. ╙INGLE-CHARACTER STRING LITERALS ARE ALSO INTERPRETED (IN THE CONTEXT OF A NUMERIC EXPRESSION) AS BEING A NUMERIC LITERAL. ╘HE VALUE OF A SINGLE-CHARACTER STRING IS SIMPLY THE ╨┼╘╙├╔╔ CODE FOR THE CHARACTER. ╔DENTIFIERS OR "SYMBOLS" OR "LABELS" USED IN EXPRESSIONS REFER TO NUMERIC VALUES THAT HAVE BEEN OR WILL BE ASSIGNED TO THE IDENTIFIERS. ┬INDING VALUES TO IDENTIFIERS IS DONE BY ASSEMBLER DIRECTIVES DISCUSSED IN A LATER SECTION. ╔F AN IDENTIFIER ALREADY HAS A VALUE ASSIGNED TO IT BY THE TIME THAT THE CURRENT EXPRESSION IS REACHED IN ASSEMBLY, THEN IT IS TREATED AS IF IT WERE A NUMERIC LITERAL OF THE VALUE ASSIGNED TO THE IDENTIFIER. ╔F THE IDENTIFIER CURRENTLY HAS NO VALUE ASSIGNED TO IT (I.E., IT IS "UNRESOLVED"), THEN THE ENTIRE EXPRESSION WILL BE UNRESOLVED. ╔N THIS CASE, THE EXPRESSION WILL BE RECORDED AND WILL BE EVALUATED AT A LATER TIME WHEN ALL OF ITS IDENTIFIERS BECOME RESOLVED. ┴ "HOLE" WILL BE CREATED WHERE THE EXPRESSION SHOULD GO, AND THE HOLE WILL BE "FILLED IN" LATER. ╬OTE THAT THERE ARE A COUPLE OF DIRECTIVES FOR WHICH AN EXPRESSION MUST BE RESOLVED AT THE TIME IT IS REFERENCED. ╘HE ASTERISK CHARACTER OPERATES MUCH LIKE A NUMERIC LITERAL, EXCEPT THAT ITS VALUE IS THE CURRENT CODE ADDRESS RATHER THAN A CONSTANT. ╘HE CURRENT CODE ADDRESS WILL ALWAYS BE FOR THE START OF AN ASSEMBLER INSTRUCTION. ╔.E., THE CURRENT CODE ADDRESS IS INCREMENTED ONLY AFTER AN INSTRUCTION IS ASSEMBLED. ╘HIS HAS SOME SUBTLE IMPLICATIONS, AND OTHER ASSEMBLERS MAY IMPLEMENT SLIGHTLY DIFFERENT SEMANTICS. ─IRECTIVES ARE A LITTLE DIFFERENT IN THAT THE ADDRESS IS INCREMENTED AFTER EVERY VALUE IN A "COMMALIST" IS PUT INTO MEMORY. ╥ELATIVE REFERENCES, OPERANDS CONSISTING OF A NUMBER OF PLUSES OR MINUSES, OPERATE MUCH LIKE IDENTIFIERS. ╘HEY ARE PROVIDED FOR CONVENIENCE AND WORK EXACTLY HOW THEY DO IN THE ┬UDDY ASSEMBLER. ╧PERANDS OF ALL MINUSES ARE BACKWARD REFERENCES AND OPERANDS OF ALL PLUSES ARE FORWARD REFERENCES. ┬ECAUSE OF PARSING DIFFICULTIES, RELATIVE-REFERENCE OPERANDS MUST EITHER BE THE LAST OPERAND IN AN EXPRESSION OR MUST BE FOLLOWED BY A ":" CHARACTER. ╘HE NUMBER OF PLUSES OR MINUSES TELL WHICH RELATIVE REFERENCE "POINT" IS BEING REFERRED TO. ┴ REFERENCE POINT IS SET BY THE "+" AND "-" ASSEMBLER DIRECTIVES DISCUSSED LATER. ╘HIS GETS DIFFICULT TO EXPLAIN WITH WORDS, SO HERE IS A CODE EXAMPLE: LDY #5 - LDX #0 - LDA NAME1,X STA NAME2,X BEQ + CMP #"X" BEQ ++ INX BNE - + DEY BNE -- + RTS ╘HIS RELATIVELY BOGUS SUBROUTINE WILL COPY A NULL-TERMINATED CHARACTER STRING FROM NAME1 TO NAME2 FIVE TIMES, UNLESS THE STRING CONTAINS AN "X" CHARACTER, IN WHICH CASE THE COPY OPERATION TERMINATES IMMEDIATELY UPON ENCOUNTERING THE "X". ╘HE "BEQ +" BRANCHES TO THE NEXT "+" LABEL TO OCCUR IN THE CODE, TO THE "DEY" INSTRUCTION. ╘HE "BEQ ++" BRANCHES TO THE "RTS", TO THE "+" LABEL FOLLOWING THE NEXT "+" LABEL ENCOUNTERED. ╘HE "-" AND "--" REFERENCES WORK SIMILARLY, EXCEPT THAT THEY REFER TO THE PREVIOUS "-" LABEL AND THE PREVIOUS TO THE PREVIOUS "-" LABEL. ┘OU CAN USE UP TO 255 PLUSES OR MINUS SIGNS IN A RELATIVE-REFERENCE OPERAND TO REFER TO THAT MANY REFERENCE POINTS AWAY. ╘HAT ╔ SAID RELATIVE-REFERENCE OPERANDS WORK MUCH LIKE IDENTIFIERS ABOVE IS NO COOINCIDENCE. ╞OR EACH DEFINITION OF A REFERENCE POINT AND REFERENCE TO A POINT, AN INTERNAL IDENTIFIER IS GENERATED THAT LOOKS LIKE "╠+123C" OR "╠-123C". ╬OTE THAT YOU CAN'T DEFINE OR REFER TO THESE IDENTIFIERS YOURSELF. ╘HERE ARE TWO TYPES OF OPERATORS THAT CAN BE USED IN EXPRESSIONS: MONADIC AND DIADIC OPERATORS. ═ONADIC OPERATORS AFFECT ONE OPERAND, AND DYADIC OPERATORS AFFECT TWO OPERANDS. ┴T ABOUT THIS POINT, ╔ SHOULD SPELL OUT THE ACTUAL FORM OF AN EXPRESSION. ╔T IS: [MONADIC_OPERATORS] OPERAND [ OPERATOR [MONADIC_OPERATORS] OPERAND [...] ] OR: 1 + 2 -1 + -+-2 + 3 ┴N EXPRESSION MAY HAVE UP TO 17 OPERANDS. ╘HE MONADIC (ONE-OPERAND) OPERATORS ARE: POSITIVE (+), NEGATIVE (-), LOW-BYTE (<), AND HIGH-BYTES (>). ┘OU CAN HAVE UP TO 255 OF EACH OF THESE MONADIC OPERATORS FOR EACH OPERAND OF AN EXPRESSION. ╨OSITIVE DOESN'T ACTUALLY DO ANYTHING. ╬EGATIVE WILL RETURN THE 32-BIT 2'S COMPLEMENT OF THE OPERAND THAT IT IS ATTACHED TO. ╠OW-BYTE WILL RETURN THE LOWEST EIGHT BITS OF THE OPERAND IT IS ATTACHED TO. ╚IGH-BYTE WILL RETURN THE HIGH-ORDER 24-BITS OF THE 32-BIT OPERAND IT IS ATTACHED TO. ┴LL EXPRESSIONS ARE EVALUATED IN FULL 32-BIT PRECISION. ╬OTE THAT YOU CAN USE THE HIGH-BYTES OPERATOR MORE THAN ONCE TO EXTRACT EVEN HIGHER. ╞OR EXAMPLE, "<>>VALUE" WILL EXTRACT THE SECOND-HIGHEST BYTE OF THE 32-BIT VALUE. ╘HE DYADIC (TWO-OPERAND) OPERATORS ARE CURRENTLY ONLY ADD (+) AND SUBTRACT (-). ┘ES, THE PLUS AND MINUS SYMBOLS ARE HORRIBLY OVERLOADED. ╔ HOPE THAT WE ALL KNOW WHAT ADD AND SUBTRACT DO. ╔ AM PLANNING TO IMPLEMENT MORE DYADIC OPERATORS IN THE FUTURE (MULTIPLY, DIVIDE, AND, OR, NOT, EXCLUSIVE-OR). ┼VALUATION OF DYADIC OPERATORS IS STRICTLY LEFT-TO-RIGHT, AND VALUE OVERFLOWS AND UNDERFLOWS ARE IGNORED. ╓ALUES ARE ALWAYS CONSIDERED TO BE POSITIVE, BUT THIS DOESN'T IMPACT 2'S COMPLEMENT NEGATIVE ARITHMETIC FOR ADD AND SUBTRACT DYADIC OPERATORS. ═ONADIC OPERATORS TAKE PRECEDENCE OVER DYADIC OPERATORS. ┼VALUATION OF MONADIC OPERATORS IS DONE A LITTLE DIFFERENTLY. ┴LL POSITIVE OPERATORS ARE THROWN OUT SINCE THEY DON'T ACTUALLY DO ANYTHING. ╘HEN, IF THERE IS AN EVEN NUMBER OF NEGATIVE OPERATORS, THEY ARE THROWN OUT. ╔F THERE IS AN ODD NUMBER OF NEGATIVE OPERATORS, THEN THE 2'S COMPLEMENT NEGATIVE OF THE OPERAND IS RETURNED. ╘HEN, IF THERE ARE ANY HIGH-BYTES OPERATORS, THE VALUE IS SHIFTED THAT NUMBER OF BYTES TO THE RIGHT AND THE HIGHEST-ORDER BYTE OF THE VALUE IS SET TO ZERO. ╬OTE THAT IT REALLY DOESN'T MAKE ANY SENSE TO PERFORM ANY MORE THAN THREE HIGH-BYTES OPERATORS. ╘HEN, THE LOW-BYTE OPERATOR IS PREFORMED, IF ASKED FOR. ╔T IS EQUIVALENT TO TAKING ANDING THE VALUE WITH $000000FF. ╔T REALLY DOESN'T MAKE MUCH SENSE TO PERFORM THIS OPERATOR MORE THAN ONCE. ┴LSO, IT DOESN'T MAKE ANY DIFFERENCE IN WHICH ORDER YOU PLACE THE MONADIC OPERATORS IN AN EXPRESSION; THEY ARE ALWAYS EVALUATED IN THE STATIC ORDER GIVEN ABOVE. ╘HERE IS ONE EXCEPTION HERE. ╔F THE FIRST OPERAND OF AN EXPRESSION HAS HIGH-BYTES AND/OR LOW-BYTE MONADIC OPERATORS, THEN THE REST OF THE EXPRESSION IS EVALUATED FIRST AND THEN THE HIGH/LOW-BYTE MONADIC OPERATORS ARE PERFORMED ON THE RESULT. ╘HIS IS DONE TO BE CONSISTENT WITH OTHER ASSEMBLERS AND WITH USER EXPECTATIONS. ╨ARENTHESES ARE NOT SUPPORTED. ╚ERE ARE SOME EXAMPLES OF VALID EXPRESSIONS: 2 +2+1 2+-1 2+-------------------------------------1 ++++:-+++:+--- 1+"X"-"A"+"┴" <>>>4_000_000_000 <LABEL+1 >LABEL+1 -1 ╘HIS LAST ONE ENDS UP WITH A VALUE OF NEGATIVE ONE, WHICH IS INTERPRETED AS REALLY BEING 4_294_967_295. ╔F YOU WERE TO TRY AND DO SOMETHING LIKE "LDA #-1", YOU WOULD GET AN ERROR BECAUSE THE VALUE WOULD BE INTERPRETED AS BEING WAY TOO BIG. ┼XPRESSIONS RESULTS ARE CURRENTLY CONSIDERED TO BE ONE OF TWO TYPES: VALUE AND ADDRESS. (╘HE COMPLETE SET MUST BE VALUE, ADDRESS, ADDRESS-LOW-BYTE, AND ADDRESS-HIGH-BYTE IN ORDER TO BE ACTUALLY USEFUL). ╓ALUES ARE WHAT YOU WOULD EXPECT AND COME FROM NUMERIC AND SINGLE-CHARACTER-STRING-LITERAL OPERANDS. ╘HE ADDRESS TYPE COMES FROM THE ASTERISK AND RELATIVE REFERENCE OPERANDS AND FROM IDENTIFIER OPERANDS WHICH ARE DEFINED TO BE ADDRESSES. ┴N ADDRESS IS DEFINED TO BE ONLY AN ADDRESS IN THE RANGE OF THE ASSEMBLED CODE. ┴DDRESSES OUTSIDE OF THIS RANGE ARE CONSIDERED TO BE VALUES. ╘HE DISTINCTION OF VALUES AND ADDRESSES IS CURRENTLY NOT USED, BUT WILL BE IN THE FUTURE WHEN CODE RELOCATION FEATURES ARE IMPLEMENTED. ╦EEPING TRACK OF EXPRESSION TYPES MAKES IT POSSIBLE TO GENERATE A LIST OF ALL VALUES IN MEMORY THAT MUST BE MODIFIED IN ORDER TO RELOCATE A PROGRAM TO A NEW ADDRESS WITHOUT REASSEMBLING IT. ╙TRING "EXPRESSIONS" CONSIST OF ONLY A SINGLE STRING LITERAL. ╬O OPERATORS ARE ALLOWED. ╙OME ASSEMBLER DIRECTIVES ACCEPT EITHER NUMERIC OR STRING EXPRESSIONS AND INTERPRET THEM APPROPRIATELY (LIKE "DB"). ------------------------------------------------------------------------------ 5. ╨╥╧├┼╙╙╧╥ ╔╬╙╘╥╒├╘╔╧╬╙ ╘HIS ASSEMBLER ACCEPTS THE 56 STANDARD 6502 PROCESSOR INSTRUCTIONS. ╔T DOES NOT PROVIDE UN-DOCUMENTED 6502 INSTRUCTIONS NOR 65C02 NOR 65816 INSTRUCTIONS NOR CUSTOM PSEUDO-OPS. ╘HE LATTER WILL BE PROVIDED BY FUTURE MACRO FEATURES. ┴LL OF THE ASSEMBLER INSTRUCTIONS MUST BE IN LOWERCASE OR THEY WILL NOT BE RECOGNIZED. ╚ERE ARE THE INSTRUCTIONS: ╬╒═ ╔╬╙ ╬╒═ ╔╬╙ ╬╒═ ╔╬╙ ╬╒═ ╔╬╙ ╬╒═ ╔╬╙ --- --- 12. BVC 24. EOR 36. PHA 48. STA 01. ADC 13. BVS 25. INC 37. PHP 49. STX 02. AND 14. CLC 26. INX 38. PLA 50. STY 03. ASL 15. CLD 27. INY 39. PLP 51. TAX 04. BCC 16. CLI 28. JMP 40. ROL 52. TAY 05. BCS 17. CLV 29. JSR 41. ROR 53. TSX 06. BEQ 18. CMP 30. LDA 42. RTI 54. TXA 07. BIT 19. CPX 31. LDX 43. RTS 55. TXS 08. BMI 20. CPY 32. LDY 44. SBC 56. TYA 09. BNE 21. DEC 33. LSR 45. SEC 10. BPL 22. DEX 34. NOP 46. SED 11. BRK 23. DEY 35. ORA 47. SEI ╘HE ASSEMBLER ALSO SUPPORTS 12 ADDRESSING MODES. ╘HE "ACCUMULATOR" ADDRESSING MODE THAT CAN BE USED WITH THE ROTATE AND SHIFT INSTRUCTIONS IS TREATED LIKE THE IMMEDIATE ADDRESSING MODE, SO A SHIFT-LEFT-ACCUMULATOR INSTRUCTION WOULD BE JUST "ASL" RATHER THAN "ASL A". ═ANY OTHER ASSEMBLERS GET RID OF THE ACCUMULATOR ADDRESSING MODE ALSO. ┴LSO, THE ",X" AND ",Y" ADDRESSING MODES MUST BE GIVEN WITH A LOWERCASE "X" OR "Y" OR THEY WILL NOT BE RECOGNIZED. ╚ERE IS THE TOKEN SYNTAX FOR THE ADDRESSING MODES (├╥ MEANS CARRIAGE RETURN): NUM NAME GEN BYT EXAMPLE TOKENS --- --------- --- --- ------- ------- 01. IMPLIED 00. 1 ├╥ 02. IMMEDIATE 00. 2 #123 # / EXP8 / ├╥ 03. RELATIVE 00. 2 *+20 EXP16 / ├╥ 04. ZEROPAGE 07. 2 123 EXP8 / ├╥ 05. ZP,X 08. 2 123,X EXP8 / , / X / ├╥ 06. ZP,Y 09. 2 123,Y EXP8 / , / Y / ├╥ 07. ABSOLUTE 00. 3 12345 EXP16 / ├╥ 08. ABS,X 00. 3 12345,X EXP16 / , / X / ├╥ 09. ABS,Y 00. 3 12345,Y EXP16 / , / Y / ├╥ 10. INDIRECT 00. 3 (12345) ( / EXP16 / ) / ├╥ 11. (IND,X) 00. 2 (123,X) ( / EXP8 / , / X / ) / ├╥ 12. (IND),Y 00. 2 (123),Y ( / EXP8 / ) / , / Y / ├╥ ┼ACH INSTRUCTION TAKES A COMPLETE LINE AND EACH ADDRESSING MODE MUST BE TERMINATED BY A CARRIAGE RETURN TOKEN (COMMENTS ARE SKIPPED). ╘HE FORMAT OF AN INSTRUCTION LINE IS AS FOLLOWS: [PREFIX_DIRECTIVES] INSTRUCTION ADDRESS_MODE_OPERAND ╔N THE CASE THAT AN EXPRESSION IN AN ADDRESSING MODE IS RESOLVED AT THE POINT IT IS ENCOUNTERED AND ITS VALUE IS LESS THAN 256, THE ASSEMBLER WILL TRY TO USE THE ZERO-PAGE ADDRESSING MODES IF POSSIBLE. ╧N THE OTHER HAND, IF A ZERO-PAGE ADDRESSING MODE IS UNAVAILABLE FOR AN INSTRUCTION, THEN THE ASSEMBLER WILL PROMOTE OR GENERALIZE THE ZERO-PAGE ADDRESSING MODE TO AN ABSOLUTE ADDRESSING MODE, IF POSSIBLE. ╘HIS IS WHAT THE "GEN" COLUMN IN THE TABLE ABOVE SHOWS. ╔F AFTER ATTEMPTING TO GENERALIZE THE ADDRESSING MODE THE GIVEN ADDRESSING MODE STILL NOT VALID WITH THE GIVEN INSTRUCTION, THEN AN ERROR WILL BE GENERATED. ╔N THE CASE THAT AN EXPRESSION IN AN ADDRESSING MODE CANNOT BE RESOLVED AT THE POINT WHERE IT IS ENCOUNTERED IN THE ASSEMBLER'S SINGLE PASS, A HOLE IS LEFT BEHIND, AND THAT HOLE IS MADE AS "LARGE" AS POSSIBLE; IT IS ASSUMED THAT YOU WILL FILL IN THE HOLE WITH THE LARGEST VALUE POSSIBLE. ╘HIS MEANS, FOR EXAMPLE, IF YOU WERE TO ASSEMBLE THE FOLLOWING INSTRUCTION: LDA VAR,X THEN THE ASSEMBLER WOULD ASSUME THIS IS AN ABSOLUTE MODE, AND WILL FILL IN THE HOLE LATER AS SUCH, EVEN IF IT TURNS OUT THAT "VAR" IS ASSIGNED A VALUE LESS THAN 256 LATER ON. ╘HIS RESULTS IN SLIGHT INEFFICIENCY IN THE CODE PRODUCED BY THIS ASSEMBLER, BUT IT CAUSES MOST TWO-PASS ASSEMBLERS TO FAIL COMPLETELY ON A "PHASE ERROR". ┴N EASY WAY TO AVOID THIS CIRCUMSTANCE IS TO MAKE SURE THAT ALL ZERO-PAGE LABELS ARE DEFINED BEFORE THEY ARE REFERRED TO. ╘HE ADDRESSING MODES THAT REQUIRE A SINGLE BYTE VALUE AND THAT WILL NOT "GENERALIZE" TO AN ABSOLUTE MODE WILL HAVE A SINGLE-BYTE HOLE CREATED FOR THEM. ╧NLY THE BRANCHING INSTRUCTIONS WILL BE INTERPRETED AS HAVING THE RELATIVE ADDRESSING MODE, AND A SINGLE-BYTE HOLE WILL BE LEFT. ╘WO EXCEPTIONS TO THE ABOVE RULES ARE THE "STX ZP,Y" AND "STY ZP,X", WHICH WILL LEAVE A SINGLE-BYTE HOLE ON AN UNRESOLVED EXPRESSION, SINCE THE ABSOLUTE-MODE GENERALIZATIONS FOR THESE INSTRUCTIONS ARE NOT SUPPORTED BY THE PROCESSOR. ------------------------------------------------------------------------------ 6. ─╔╥┼├╘╔╓┼╙ ╘HERE ARE CURRENTLY FIVE CLASSES OF ASSEMBLER DIRECTIVES; THERE WILL BE MORE IN THE FUTURE. 6.1. ─╧-╬╧╘╚╔╬╟ ─╔╥┼├╘╔╓┼╙ ╘HERE ARE TWO DO-NOTHING DIRECTIVES: # ;DOES NOTHING ;BLANK LINE--DOES NOTHING ┴ BLANK LINE IN YOUR SOURCE CODE WILL SIMPLY BE IGNORED. ╘HIS HELPS TO MAKE CODE MUCH MORE READABLE. ╘HE "#" DIRECTIVE IS A PREFIX DIRECTIVE. ╘HIS MEANS THAT IT DOES NOT OCCUPY AN ENTIRE LINE BUT ALLOWS OTHER DIRECTIVES AND PROCESSOR INSTRUCTIONS TO FOLLOW IT ON THE SAME LINE (INCLUDING OTHER PREFIX DIRECTIVES). (┬UT NOTE THAT YOU CAN FOLLOW ANY PREFIX DIRECTIVE BY THE BLANK-LINE DIRECTIVE, EFFECTIVELY ALLOWING PREFIX DIRECTIVES TO BE REGULAR FULL-LINE DIRECTIVES (POWERFUL COMBINING FORMS)). ╘HE "#" DIRECTIVE IS SIMPLY IGNORED BY THE ASSEMBLER, BUT YOU CAN USE IT TO HIGHLIGHT CERTAIN LINES OF CODE OR OTHER DIRECTIVES, LIKE THE FUTURE "INCLUDE" DIRECTIVE. 6.2. ┴╙╙╔╟╬═┼╬╘ ─╔╥┼├╘╔╓┼╙ ╘HERE ARE FOUR ASSIGNMENT DIRECTIVES. ╘HEY ALL ASSIGN (BIND) A VALUE TO AN IDENTIFIER. ╚ERE THEY ARE: LABEL = EXPRESSION ;ASSIGN GIVEN VALUE TO THE LABEL LABEL: ;ASSIGN THE CURRENT ASSEMBLY ADDRESS TO LABEL + ;GENERATE A TEMPORARY LABEL, ASSIGN CUR ADDRESS - ;GENERATE A TEMPORARY LABEL, ASSIGN CUR ADDRESS ╘HE FIRST (LABEL=EXPR) IS THE MOST GENERAL. ╔T ASSIGNS THE RESULT OF EVALUATING THE EXPRESSION TO THE GIVEN LABEL. ┬ECAUSE THIS ASSEMBLER IS SO GOSH-DARNED AWESOME, THE EXPRESSION DOESN'T EVEN HAVE TO BE RESOLVED; A "HOLE" WILL BE CREATED SAYING TO FILL IN THE ASSIGNED LABEL WHEN ALL OF THE UNRESOLVED IDENTIFIERS IN THE EXPRESSION EVENTUALLY BECOME RESOLVED. ═OST OTHER ASSEMBLERS (IN FACT, ALL THAT ╔ HAVE EVER HEARD OF) CAN'T DO THIS BECAUSE IT CAUSES UGLY IMPLEMENTATION PROBLEMS, LIKE CASCADING LABEL RESOLUTIONS. ├ONSIDER THE FOLLOWING EXAMPLE: LDA #A STA B,X A = B+3 B = C-1 C = 5 ┴T THE POINT WHERE C BECOMES DEFINED, THERE ARE NO "MEMORY HOLES" BUT THE LABEL HOLE "B" MUST BE EVALUATED AND FILLED IN. "B" GETS ASSIGNED THE VALUE 4. ┴T THIS POINT, THERE ARE TWO HOLES: THE ONE IN THE "STA" INSTRUCTION AND THE LABEL "A". ╫E FILL THEM BOTH IN, ASSIGNING "A" THE VALUE 8, AND WE DISCOVER THAT WE CAN FILL IN A HEW HOLE: THE ONE IN THE "LDA" INSTRUCTION. ╫E DO THAT AND WE ARE FINALLY DONE. ╘HE IMPLEMENTATION CAN HANDLE ANY NUMBER OF THESE RECURSIVE LABEL HOLE-FILLINGS, LIMITED ONLY BY THE AMOUNT OF NEAR+FAR MEMORY YOU HAVE. ┴ LABEL CAN ONLY BE ASSIGNED A VALUE ONCE, AND YOU WILL GET AN ERROR IF YOU TRY TO REDEFINE A LABEL, EVEN IF IT IS CURRENTLY UNRESOLVED. ┴LSO, ALL EXRESSIONS MUST BE RESOLVED BY THE END OF THE ASSEMBLY JOB, OR AN ERROR WILL BE REPORTED (BUT ONLY ONE--NAMING THE FIRST UNRESOLVED LABEL THAT THE ASSEMBLER RUNS ACROSS; ╔ MAY FIX THIS UP IN THE FUTURE). ╘HE SECOND ASSIGNMENT DIRECTIVE IS EQUIVALENT TO "LABEL = *", BUT IT IS MORE CONVENIENT AND IS ALSO A PREFIX DIRECTIVE. ╔T ASSIGNS THE CURRENT ADDRESS (AS OF THE START OF THE CURRENT LINE) TO THE GIVEN IDENTIFIER. ╘HE COLON IS USED WITH THIS DIRECTIVE TO MAKE IT EASY AND EFFICIENT TO PARSE, AND TO MAKE IT EASY FOR A HUMAN TO SEE THAT A LABEL IS BEING DEFINED. ═ANY OTHER ASSEMBLERS FOLLOW THIS DIRECTIVE WITH JUST WHITESPACE AND RELY ON OTHER TRICKS, LIKE PUTTING AN UGLY DOT BEFORE EACH DIRECTIVE, TO BAIL THEM OUT. ╘HE THIRD AND FOURTH SET RELATIVE REFERENCE POINTS. ╘HEY ARE EQUIVALENT TO "REL_LABEL = *", WHERE "REL_LABEL" IS A SPECIALLY GENERATED INTERNAL IDENTIFIER OF THE FORM "╠+123C" MENTIONED IN THE EXPRESSION SECTION. ╘HE LABELS DEFINED BY THESE DIRECTIVES SHOW UP IN THE SYMBOL TABLE DUMP, IF YOU ASK FOR ONE ON THE COMMAND LINE. ╘HESE ARE ALSO PREFIX DIRECTIVES, SO IF YOU WANTED TO SET A FORWARD AND A BACKWARD REFERENCE TO THE SAME ADDRESS, THEN YOU WOULD DO SOMETHING LIKE: +- LDA #1 ╔N FACT, YOU COULD PUT AS MANY OR THESE DIRECTIVES ON THE FRONT OF A LINE AS YOU WANT, THOUGH MORE THAN ONE OF EACH WILL BE OF LITTLE USE. ╬OTE THAT BACKWARD RELATIVE LABELS WILL ALWAYS BE DEFINED AT THE POINT THAT THEY ARE REFERENCED AND FORWARD RELATIVE LABELS WILL ALWAYS BE UNDEFINED (UNRESOLVED) WHEN THEY ARE REFERENCED. ╔F AT THE END OF YOUR ASSEMBLY JOB THE ASSEMBLER COMPLAINS OF AN UNRESOLVED REFERENCE INVOLVING A LABEL OF THE FORM "╠+123C", THEN YOU REFER TO A FORWARD-RELATIVE POINT THAT YOU DON'T SET, AND IF THE LABEL IS OF THE FORM "╠-4000000000C", THEN YOU REFER TO A BACKWARD RELATIVE POINT THAT YOU DON'T DEFINE. 6.3. ╧╥╔╟╔╬ ─╔╥┼├╘╔╓┼ ORG ADDRESS_EXPRESSION ;SET THE ORIGIN OF THE ASSEMBLY ╘HIS DIRECTIVE WILL SET THE CODE ORIGIN TO THE GIVEN EXPRESSION. ╘HE EXPRESSION ═╒╙╘ BE RESOLVED AT THE POINT WHERE IT APPEARS, SINCE IT WOULD BE VERY DIFFICULT TO FILL IN THE TYPE OF HOLE THIS WOULD LEAVE BEHIND (THOUGH NOT IMPOSSIBLE, HMMM...). ╘HE ORIGIN MUST BE SET BEFORE ANY PROCESSOR INSTRUCTION OR ASSEMBLER DIRECTIVE THAT GENERATES MEMORY VALUES IS ENCOUNTERED, AND THE CODE ORIGIN CAN ONLY BE SET ONCE. ╘HIS RESULTS IN A CONTIGUOUS CODE REGION, WHICH IS WHAT ┴├┼ AND THE ├OMMODORE ╦ERNAL REQUIRE. 6.4. ─┼╞╔╬┼-┬┘╘┼╙ ─╔╥┼├╘╔╓┼╙ DB EXP1, EXP2, ..., EXP╬ ;PUT BYTE VALUES INTO MEMORY DW EXP1, EXP2, ..., EXP╬ ;PUT WORD VALUES INTO MEMORY DT EXP1, EXP2, ..., EXP╬ ;PUT "TRIPLE" (3-BYTE) VALUES INTO MEMORY, LO->HI DL EXP1, EXP2, ..., EXP╬ ;PUT "LONG" (4-BYTE) VALUES INTO MEMORY, LO->HI ╘HESE DIRECTIVES ALL PUT BYTE VALUES INTO CODE MEMORY, AT THE CURRENT ADDRESS. ╘HE ONLY DIFFERENCE BETWEEN THE FOUR OF THEM IS THE SIZE OF DATA VALUES THEY PUT INTO MEMORY: BYTES (8 BITS), WORDS (16 BITS), TRIPLES (24 BITS), AND LONGS (32 BITS). ╘HE CODE ADDRESS IS INCREMENTED BY THE APPROPRIATE NUMBER OF BYTES BETWEEN PUTTING EACH VALUE INTO MEMORY. ┴NY NUMBER OF VALUES CAN BE SPECIFIED BY SEPARATING THEM BY COMMAS. ┴LL EXPRESSIONS ARE EVALUATED IN FULL 32 BITS, BUT MUST FIT INTO THE SIZE FOR THE DIRECTIVE. ╘HE EXPRESSIONS DON'T HAVE TO BE RESOLVED AT THE TIME THEY APPEAR. ╘HESE DIRECTIVES CAN ALSO BE GIVEN STRINGS FOR ARGUMENTS, WHICH MEANS THAT EACH CHARACTER OF THE STRING WILL BE STORED AS ONE BYTE/WORD/ETC. IN MEMORY, FOR EXAMPLE: DB 123, ABC+XYZ+%1101-"A"+$1, "HELLO", 0, "YO!", "KEEP ON HACKIN'\0" 6.5. ┬╒╞ ─╔╥┼├╘╔╓┼ BUF SIZE_EXPRESSION ;RESERVE "SIZE" BYTES OF SPACE, FILLED WITH ZEROES ╘HIS DIRECTIVE RESERVES THE GIVEN NUMBER OF BYTES OF SPACE FROM THE CURRENT CODE ADDRESS AND FILLS THEM WITH ZEROES. ╘HE EXPRESSION MUST BE RESOLVED, AND CAN BE ANY VALUE FROM 0 UP TO 65535 OR THE NUMBER OF BYTES REMAINING UNTIL THE CODE ADDRESS OVERFLOWS THE 64╦ CODE SPACE LIMIT. 6.6. ╨┴╥╙╔╬╟ ┬ECAUSE OF THE WAY THAT THE ASSEMBLER PARSES THE SOURCE CODE (IT USES A ONE-CHARACTER-PEEK-AHEAD AD-HOC PARSER), YOU CAN DEFINE LABELS THAT ARE ALSO DIRECTIVE NAMES OR PROCESSOR-INSTRUCTION NAMES. ╘HIS IS NOT A RECOMMENDED PRACTICE, SINCE YOU CAN END UP WITH LINES THAT LOOK LIKE: X: LDA: LDA LDA,X ╘HE PARSER WILL KNOW WHAT TO DO, BUT MOST HUMANS WON'T. ┴LSO, BECAUSE OF THE TOKENIZER, CAN PUT ARBITRARY SPACING BETWEEN TOKENS, EXCEPT BETWEEN TOKENS THAT WOULD OTHERWISE MERGE TOGETHER (LIKE TWO ADJACENT IDENTIFIERS OR DECIMAL NUMBERS). ------------------------------------------------------------------------------ 7. ┼╥╥╧╥ ╚┴╬─╠╔╬╟ ╫HEN AN ERROR IS DETECTED, THE ASSEMBLER WILL STOP THE WHOLE ASSEMBLY JOB AND PRINT OUT ONE ERROR MESSAGE (TO THE STDERR FILE STREAM). ╚ERE ARE TWO EXAMPLES OF ERROR MESSAGES: ERR ("K:":2:0) ╓ALUE IS TOO LARGE OR NEGATIVE ERR ("K:":3:0), REF("K:":2:0) ╓ALUE IS TOO LARGE OR NEGATIVE ╔N BOTH ERROR MESSAGES, THE STUFF INSIDE OF THE PARENTHESES IS THE FILENAME OF THE SOURCE FILE (THE KEYBOARD HERE), THE SOURCE LINE WHERE THE ERROR WAS DETECTED, AND THE COLUMN NUMBER WHERE THE ERROR WAS DETECTED. ├URRENTLY, THE COLUMN NUMBER IS NOT IMPLEMENTED SO IT IS ALWAYS ZERO. ╫HEN IT IS IMPLEMENTED, THE COLUMN NUMBERS WILL START FROM 1, LIKE IN THE ┌ED TEXT EDITOR, AND IT WILL POINT TO THE FIRST CHARACTER OF THE TOKEN WHERE THE ERROR WAS DISCOVERED. ╔N THE FIRST EXAMPLE, THE ERROR OCCURRED BECAUSE THE EXPRESSION WAS RESOLVED AND THE VALUE WAS FOUND TO BE TOO LARGE FOR WHATEVER OPERATION WAS ATTEMPTED. ╔N THE SECOND EXAMPLE, AN EXPRESSION WAS USED BUT UNRESOLVED ON LINE 2 OF THE SOURCE FILE, AND WHEN ITS UNRESOLVED IDENTIFIER(S) WAS FINALLY FILLED IN IN LINE 3 OF THE SOURCE, THE "HOLE" TO BE FILLED IN WAS FOUND TO BE TOO SMALL FOR THE VALUE, SO AN ERROR RESULTED. ╘HIS IS WHAT THE "REF" FILE POSITION MEANS. ╞ILENAMES ARE INCLUDED IN ERROR MESSAGES BECAUSE IN THE FUTURE, IT WILL BE POSSIBLE TO HAVE ERRORS CROP UP IN INCLUDED FILES AND ELSEWHERE. ╚ERE IS THE ENTIRE LIST OF POSSIBLE ERROR MESSAGES: ╬╒═ ═┼┴╬╔╬╟ --- ------- 01. "┴N IDENTIFIER TOKEN EXCEEDS 240 CHARS IN LENGTH" 02. "┴ STRING LITERAL EXCEEDS 240 CHARS IN LENGTH" 03. "╥AN INTO A ├╥ BEFORE END OF STRING LITERAL" 04. "╔NVALID NUMERIC LITERAL" 05. "╬UMERIC LITERAL VALUE OVERFLOWS 32-BITS" 06. "╙YNTAX ERROR" 07. "┴TTEMPT TO PERFORM NUMERIC OPERATORS ON A STRING" 08. "┼XPRESSION HAS MORE THAN 17 OPERANDS" 09. "╥AN OUT OF MEMORY DURING COMPILATION PROCESS" 10. "┴TTEMPT TO REDEFINE A SYMBOL" 11. "┴TTEMPT TO ASSEMBLE CODE WITH CODE ORIGIN NOT SET" 12. "╔NTERNAL ERROR: ATTEMPT TO ASSIGN TO UNEXPECTED ID" 13. "╬ON-NUMERIC SYMBOL IN A NUMERIC EXPRESSION" 14. "┼XPECTING AN OPERATOR" 15. "┼XPECTING AN OPERAND" 16. "┼XPECTING A COMMAND" 17. "╓ALUE IS TOO LARGE OR NEGATIVE" 18. "┬RANCH OUT OF RANGE" 19. "╞EATURE IS NOT (YET) IMPLEMENTED" 20. "╔NSTRUCTION DOES NOT SUPPORT GIVEN ADDRESS MODE" 21. "┴DDRESS WRAPED AROUND 64╦ CODE ADDRESS SPACE" 22. "┼RROR TRYING TO WRITE OUTPUT OBJECT FILE" 23. "─IRECTIVE REQUIRES RESOLVED EXPRESSION" 24. "├ODE ORIGIN ALREADY SET; YOU CAN'T SET IT TWICE" 25. "╒NRESOLVED SYMBOL: " 26. "╘HUS ASSEMBLER DOESN'T ACCEPT .DOT COMMANDS, ┬UDDY!" ┴ "╙YNTAX ERROR" (#06) WILL BE REPORTED WHENEVER A TOKEN OTHER THAN ONE THAT WAS EXPECTED IS FOUND. "╥AN OUT OF MEMORY" (#09) MAY TURN UP OFTEN ON AN UNEXPANDED 64. "┼XPECTING COMMAND" (#16) MEANS THAT THE ASSEMBLER WAS EXPECTING EITHER A PROCESSOR INSTRUCTION OR DIRECTIVE BUT FOUND SOMETHING ELSE INSTEAD. "╬OT IMPLEMENTED" (#19) MEANS THAT YOU'VE TRIED TO USE A DIRECTIVE THAT ISN'T IMPLEMENTED YET. "╒NRESOLVED SYMBOL" (#25) WILL BE PRINTED WITH A RANDOMLY CHOSEN UNRESOLVED SYMBOL, WITH THE LAST PLACE IN THE SOURCE CODE WHERE IT WAS REFERENCED. "─OT COMMANDS" (#26) IS A REMINDER THAT DIRECTIVES IN THIS ASSEMBLER ARE NOT PREFIXED WITH A DOT (.). ╘HERE ARE TWO MAIN REASONS BEHIND THE IDEA OF STOPPING AT THE FIRST ERROR ENCOUNTERED: SIMPLICITY AND INTEROPERABILITY. ╫HEN ┌ED IS IMPLEMENTED FOR ┴├┼, IT WILL HAVE A FEATURE THAT WILL ALLOW IT TO INVOKE THE ASSEMBLER (AS A SUB-PROCESS) AND HAVE THE ASSEMBLER RETURN AN ERROR LOCATION AND MESSAGE TO ┌ED, WHICH WILL DISPLAY THE ERROR MESSAGE AND POSITION THE CURSOR TO THE ERROR LOCATION (IF THE SOURCE FILE IS LOADED). ╫HILE ON THE SUBJECT OF MESSAGES COMING OUT OF THE ASSEMBLER, HERE IS AN EXAMPLE OF THE FORMAT OF THE SYMBOL TABLE DUMP THAT YOU CAN ASK FOR ON THE COMMAND LINE. ╧NE LINE IS PRINTED FOR EACH IDENTIFIER. ╘HE "HASH" VALUE IS THE BUCKET IN THE HASH TABLE CHOSEN FOR THE IDENTIFIER. ╘HIS MAY NOT HAVE A WHOLE LOT OF MEANING FOR A USER, BUT A GOOD DISTRIBUTION OF THESE HASH BUCKETS IN THE SYMBOL TABLE IS A GOOD THING. ╬EXT IS THE 32-BIT "HEXVALUE" OF THE LABEL FOLLOWED BY THE VALUE IN "DECIMAL". ╘HEN COMES THE TYPE. ┴ TYPE OF "V" MEANS VALUE AND "A" MEANS AN IN-CODE-RANGE ADDRESS. ╘HEN COMES THE NAME OF THE IDENTIFIER. ╔T COMES LAST TO GIVE LOTS OF SPACE TO PRINT IT. ╔F AN IDENTIFIER IS TEN OR FEWER CHARACTERS LONG, ITS SYMBOL-TABLE-DUMP LINE WILL FIT ON A 40-COLUMN SCREEN. ┴T THE BOTTOM, THE NUMBER OF SYMBOLS IS PRINTED. ╘HIS TABLE IS DIRECTED TO THE STDOUT FILE STREAM, SO YOU CAN REDIRECT IT TO A FILE IN ORDER TO SAVE IT. ╚┴╙╚ ╚┼╪╓┴╠╒┼ ─┼├╔═┴╠ ╘ ╬┴═┼ ---- -------- ---------- - ----- 8 00000F06 3846 V ACE┴RGV 469 00007008 28680 A MAIN -- ╬UMBER OF SYMBOLS: 2 ------------------------------------------------------------------------------ 8. ╔═╨╠┼═┼╬╘┴╘╔╧╬ ╔N EACH OF THE WAYS IN WHICH IT IS HEAVY-WEIGHT AND SLOWED-DOWN COMPARED TO OTHER ASSEMBLERS, IT IS ALSO MORE POWERFUL AND MORE FLEXIBLE. - ╔T USES FAR MEMORY FOR STORING SYMBOLS, SO THERE IS NO STATIC OR ARBITRARILY SMALL LIMIT ON THE NUMBER OF SYMBOLS. ═ACRO SIZES WILL ALSO BE LIMITED BY ONLY THE AMOUNT OF MEMORY AVAILABLE, AS WELL AS THE "HOLE TABLE". - ╔T HAS TO MAINTAIN A "HOLE TABLE" BECAUSE OF ITS STRUCTURE, BUT THIS MEANS THAT YOU CAN DEFINE LABELS IN TERMS OF OTHER UNRESOLVED LABELS, THAT YOU WILL NEVER GET A "SYNC ERROR" BECAUSE OF INCORRECT ASSUMPTIONS MADE (AND NOT RECORDED) ABOUT UNRESOLVED LABELS, AND THAT MODULAR ASSEMBLY CAN BE IMPLEMENTED WITHOUT TOO MUCH FURTHER EFFORT (I.E., ".O" OR ".OBJ" FILES), SINCE AN UNRESOLVED EXTERNAL REFERENCE HANDLING MECHANISM IS ALREADY IMPLEMENTED. - ╘HE ASSEMBLER KEEPS TRACK OF THE "TYPES" OF LABELS, EITHER "ADDRESS" OR "VALUE" THAT MAKES IT POSSIBLE TO PROVIDE CODE RELOCATION INFORMATION THAT WILL BE NEEDED BY MODULAR ASSEMBLY AND BY FUTURE MULTITASKING OPERATING SYSTEMS. - ┬ECAUSE A "HOLE TABLE" APPROACH IS USED, THE RAW OBJECT CODE MUST BE STORED INTERNALLY UNTIL THE ASSEMBLY IS COMPLETE AND THEN IT CAN BE WRITTEN OUT TO A FILE, BUT THIS ALSO MEANS THAT HEADER INFORMATION CAN BE PROVIDED IN AN OUTPUT FILE SINCE ALL ASSEMBLY RESULTS WILL BE KNOWN BEFORE ANY OUTPUT IS WRITTEN. - ╔ TOOK THE EASY WAY OUT FOR HANDLING ERRORS; WHEN AN ERROR IS DETECTED, AN ERROR MESSAGE IS GENERATED AND PRINTED AND THE ASSEMBLER ╙╘╧╨S. ┬UT THE EXIT MECHANISM PROVIDED BY ┴├┼ MAKES IT POSSIBLE TO INTEGRATE THE ASSEMBLER WITH OTHER PROGRAMS, LIKE A TEXT EDITOR, TO MOVE THE TEXT EDITOR CURSOR TO THE LINE AND COLUMN CONTAINING THE ERROR AND DISPLAY A MESSAGE IN THE TEXT EDITOR. ╘HERE ARE TWO SPEED ADVANTAGES THAT THIS ASSEMBLER HAS OVER (SOME?) OTHERS: - ╔T USES A 1024-ENTRY HASH TABLE OF POINTERS TO CHAINS OF LABELS, SO, FOR A PROGRAM THAT HAS 800 OR SO SYMBOLS, EACH CAN BE ACCESSED IN SOMETHING LIKE 1.3 TRIES. ╞OR ╬ TOTAL SYMBOLS, THE REQUIRED NUMBER OF REFERENCES IS APPROXIMATELY ═┴╪( ╬/1024, 1 ). - ╔T IS ONE-PASS, SO IT ONLY HAS TO GO THROUGH THE OVERHEAD OF READING THE SOURCE FILE ONCE. ─EPENDING ON THE TYPE OF DEVICE THE FILE IS STORED ON, THIS MAY GIVE A CONSIDERABLE SAVINGS. ╘HIS ALSO MAKES IT POSSIBLE TO "PIPE" THE OUTPUT OF ANOTHER PROGRAM INTO THE ASSEMBLER, WITHOUT ANY "REWIND" PROBLEMS. ╚ERE ARE SOME PERFORMACE FIGURES, COMPARED TO THE ┬UDDY ASSEMBLER FOR THE 128. ┴LL TEST CASES WERE RUN ON A ├128 IN 2-═╚Z MODE WITH A ╥┴═╠INK, ╥┼╒, AND 1571 AVAILABLE. ┴╙╙┼═┬ ╘╔═┼(SEC) ╞╔╠┼ ─┼╓╔├┼ ╞┴╥ ╙╘╧╥┴╟┼ ------ --------- ----------- ----------- ┬UDDY 45.5 ╥┴═╠INK N/A ┴├┼-AS 61.5 ╥┴═╠INK ╥┼╒ ┴├┼-AS 49.5 ┴├┼ RAMDISK ╥┼╒ ┴├┼-AS 75.6 ╥┴═╠INK ╥┴═0+╥┴═1 ┴├┼-AS 150.5 1571 ╥┴═0+╥┴═1 ┬UDDY 240.0 1571 N/A ╨ART OF THE ASSEMBLY JOB WAS LOADED INTO MEMORY FOR THE ┬UDDY ASSEMBLER, BUT THE LOAD TIME IS INCLUDED IN THE FIGURE. ┴S YOU CAN SEE, BUDDY PERFORMS FASTER WITH A FAST FILE DEVICE AND SLOWER WITH A SLOW FILE DEVICE (BECAUSE IT REQUIRES TWO PASSES). ╔ HAVE A COUPLE OF TRICKS UP MY SLEEVE TO IMPROVE THE ┴├┼ ASSEMBLER'S PERFORMANCE. ╘HERE ARE ALSO A COUPLE OF SUBTLE ERRORS IN THIS IMPLEMENTATION. ╞IRST, IF IT RECEIVES A "SHORT BLOCK" FROM THE SOURCE DEVICE, IT WILL PUT WHITESPACE BETWEEN THE CURRENT BLOCK AND THE NEXT, THUS POTENTIALLY SPLITTING A TOKEN. ┴LSO, IF MULTIPLE FILES ARE USED, THE "REF" FILENAME MAY NOT BE VALID. ╚ERE ARE A FEW DATA STRUCTURES FOR YOUR ENJOYMENT. ╔DENTIFIER DESCRIPTOR: ╧╞╞ ╙╔┌ ─┼╙├╥╔╨╘╔╧╬ --- --- ------------ 0 4 NEXT LINK IN HASH TABLE BUCKET 4 4 VALUE OF SYMBOL, POINTER TO REFERENCE LIST, OR PTR TO MACRO DEFN 8 1 OFFSET OF REFERENCE IN EXPRESSION OF REFERENCE LIST 9 1 TYPE: $00=VALUE, $01=ADDRESS, $80=UNRESOLVED, $FF=UNRESOLVED DEFINE 10 1 CLASS: $00=NORMAL, $01=PRIVATE, $80=GLOBAL (NOT USED YET) 11 1 NAME LENGTH 12 * NULL-TERMINATED NAME STRING (1-240 CHARS) ┼XPRESSION/╚OLE DESCRIPTOR: ╧╞╞ ╙╔┌ ─┼╙├╥╔╨╘╔╧╬ --- --- ----------- 0 1 HOLE TYPE: $01=BYTE, $02=WORD, $03=TRIPLE, $04=LONG, $40=BRANCH, $80=LABEL 1 1 EXPRESSION LENGTH: MAXIMUM OFFSET+1 IN BYTES 2 1 NUMBER OF UNRESOLVED REFERENCES IN EXPRESSION 3 1 SOURCE COLUMN OF REFERENCE 4 4 ADDRESS OF HOLE 8 4 SOURCE LINE OF REFERENCE 12 4 SOURCE FILE POINTER 16 14 EXPRESSION OPERAND DESCRIPTOR SLOT #1 30 14 EXPRESSION OPERAND DESCRIPTOR SLOT #2 44 14 EXPRESSION OPERAND DESCRIPTOR SLOT #3 58 14 EXPRESSION OPERAND DESCRIPTOR SLOT #4 72 14 EXPRESSION OPERAND DESCRIPTOR SLOT #5 86 14 EXPRESSION OPERAND DESCRIPTOR SLOT #6 100 14 EXPRESSION OPERAND DESCRIPTOR SLOT #7 114 14 EXPRESSION OPERAND DESCRIPTOR SLOT #8 128 14 EXPRESSION OPERAND DESCRIPTOR SLOT #9 142 14 EXPRESSION OPERAND DESCRIPTOR SLOT #10 156 14 EXPRESSION OPERAND DESCRIPTOR SLOT #11 170 14 EXPRESSION OPERAND DESCRIPTOR SLOT #12 184 14 EXPRESSION OPERAND DESCRIPTOR SLOT #13 198 14 EXPRESSION OPERAND DESCRIPTOR SLOT #14 212 14 EXPRESSION OPERAND DESCRIPTOR SLOT #15 226 14 EXPRESSION OPERAND DESCRIPTOR SLOT #16 240 14 EXPRESSION OPERAND DESCRIPTOR SLOT #17 254 - ┼╬─+1 ┼XPRESSION OPERAND DESCRIPTOR: ╧╞╞ ╙╔┌ ─┼╙├╥╔╨╘╔╧╬ --- --- ----------- 0 1 OPERATOR: "+" OR "-" 1 1 TYPE OF VALUE: $00=NUMBER, $01=ADDRESS, $80=UNRESOLVED IDENTIFIER 2 1 MONADIC-OPERATOR RESULT SIGN OF VALUE: $00=POSITIVE, $80=NEGATIVE 3 1 HI/LO OPERATOR COUNTS: HIGH_NYBBLE=">" COUNT, LOW_NYBBLE="<" CNT 4 4 NUMERIC VALUE OR UNRESOLVED-IDENTIFIER POINTER 8 4 NEXT UNRESOLVED REFERENCE IN CHAIN FOR UNRESOLVED IDENTIFIER 12 1 OFFSET IN HOLE STRUCTURE OF NEXT UNRESOLVED REFERENCE (OPERAND) 13 1 RESERVED 14 - ┼╬─+1 ------------------------------------------------------------------------------ 9. ╘╚┼ ╞╒╘╒╥┼ ╘HIS SECTION IS JUST RANDOM NOTES SINCE ╔ DON'T HAVE THE TIME RIGHT NOW TO FILL IT IN. ╔ WILL BE IMPLEMENTING INCLUDE FILES, CONDITIONAL ASSEMBLY, AND MACRO ASSEMBLY FEATURES IN THE FUTURE. ═ODULAR ASSEMBLY AND RELOCATABLE- CODE GENERATION ARE ALSO IN MY PLANS. ;TODO: -IMPLEMENT STORAGE CLASSES: $00=INTERNAL, $01=REL.LABEL, $80=EXPORTED ; -IMPLEMENT ALL VAR TYPES: 0=VALUE, 1=ADDRESS, 2=ADDR.HIGH, 3=ADDR.LOW ; -IMPLEMENT SOURCE COLUMN, MAKE LINE:COL POINT TO START OF CUR TOKEN ; -MAKE IT SO YOU CAN USE A "\<├╥>" TO CONTINUE A LINE ; -ADD MORE OPERATORS: * / & ▄ ▐ FULL PRECEDENCE? ; -CACHE CURRENT SYMBOL ; ; USAGE: AS [-HELP] [-S] [-D] [-B] [-R] [-L] [-A ADDR] [FILE ...] [-O FILENAME] ; ; -HELP : PRODUCE THIS INFORMATION, DON'T RUN ; -S : PRODUCE SYMBOL TABLE DUMP AT END ; -D : PROVIDE DEBUGGING INFORMATION (LOTS) ; -B : PRODUCE BINARY MODULE AT END (DEFAULT) ; -R : PRODUCE RELOCATABLE MODULE RATHER THAN BINARY MODULE ; -L : PRODUCE LINKABLE ".O" MODULE(S) ; -A : SET GLOBAL CODE ORIGIN TO GIVEN ADDRESS ; -O : PUT OUTPUT INTO GIVEN FILENAME ; ; ╔F -L OPTION IS NOT USED, ALL FILES, INCLUDING SOURCE AND OBJECT MODULES, ; WILL BE ASSEMBLED TOGETHER. ╘HE OUTPUT MODULE NAME WILL BE THE BASE NAME OF ; THE FIRST FILE GIVEN IF IT HAS A ".S" OR ".O" EXTENSION, "A.OUT" IF THE FIRST ; FILE HAS NONE OF THESE EXTENSIONS, OR WILL BE THE FILENAME GIVEN BY THE -O ; OPTION IF USED. ; ╔F THE -L OPTION IS USED, THEN EACH GIVEN SOURCE MODULE WILL BE ; ASSEMBLED INDEPENDENTLY INTO ITS OWN ".O" MODULE. ╧BJECT MODULES WILL BE ; IGNORED. ; ╘HE GLOBAL ORIGIN WILL BE EITHER THAT GIVEN BY THE -A OPTION (IF IT IS ; USED) OR BY THE LOCAL ORIGIN OF THE FIRST SOURCE/OBJECT MODULE. ┼ACH ; SOURCE MODULE THAT GENERATES CODE MUST HAVE A LOCAL CODE ORIGIN. ═ORE ─IRECTIVES: INCLUDE "FILENAME" IF <EXPRESSION> <RELOP> <EXPRESSION> ELSIF <EXPRESSION> <RELOP> <EXPRESSION> ELSE ENDIF MACRO MACRONAME ENDMACRO EXPORT LABEL1, LABEL2, ..., LABEL╬ BSS SIZE_EXPRESSION MACRO BLT ;?1=ADDR BCC ?1 ENDMACRO MACRO ADD ;?1=OPERAND CLC ADC ?1 ENDMACRO MACRO LDW ;?1=DEST, ?2=SOURCE IF ?# != 2 ERROR "THE LDW MACRO INSTANCE DOESN'T HAVE TWO ARGUMENTS" ENDIF IF @1 = # ARGSHIFT 2 0 LDA #<?2 STA ?1+0 LDA #>?2 STA ?1+1 ELSE LDA ?2+0 STA ?1+0 LDA ?2+1 STA ?1+1 ENDIF ENDMACRO ------------------------------------------------------------------------------ ╙O, THERE IS FINALLY A POWERFUL AND CONVENIENT ASSEMBLER UNIVERSALLY AVAILABLE FOR BOTH THE 64 AND 128... FOR FREE. ╘HE SOURCE CODE FOR THE ASSEMBLER (WRITTEN IN THE ASSEMBLER'S OWN ASSEMBLY FORMAT, OF COURSE) IS ALSO AVAILABLE FOR FREE. ╘HERE ARE A FEW MORE FEATURES THAT NEED TO BE IMPLEMENTED, BUT ╔ KNOW EXACTLY HOW TO IMPLEMENT THEM. ╦EEP ON ╚ACKIN'! -├RAIG ┬RUCE CSBRUCE@CCNGA.UWATERLOO.CA "╟IVE THEM APPLICATIONS AND THEY WILL ONLY WANT MORE; GIVE THEM DEVELOPMENT TOOLS AND THEY WILL GIVE YOU APPLICATIONS, AND MORE." ------------------------------------------------------------------------┼╬─---