home *** CD-ROM | disk | FTP | other *** search
/ 8bitfiles.net/archives / archives.tar / archives / genie-commodore-file-library / C64-128Toolkit / CASSM.SFX / assmdoc.fo < prev    next >
Encoding:
Text File  |  1992-11-27  |  10.8 KB  |  357 lines
  1. .IN 10
  2. .RM 75
  3. .HE /├-┴╙╙═/6502 ┴SSEMBLER FOR ├-╨OWER/╓ 2.0/
  4. .FO //-#-//
  5.  
  6. ─ISCLAIMER:
  7. .SP 1
  8. .TI +5
  9. ╘HIS PROGRAM IS HEREBY GIVEN INTO THE HANDS OF THE PUBLIC,
  10. AND IS CONSIDERED TO BE PUBLIC DOMAIN.  ┘OU MAY USE IT FOR
  11. ANY NON-PROFIT PURPOSE.  ╞EEL FREE TO ALTER IT AS YOU SEE
  12. FIT.  ╔F YOU MODIFY AND REDISTRIBUTE THIS PROGRAM, PLEASE GIVE
  13. CREDIT TO THE PRIOR AUTHORS (ORIGINAL: ╩.╚. ╓AN ╧RNUM, ╟EORGE ╓. ╫ILDER;
  14. ├-╨OWER VERSION: ═ARK ╥. ╥INFRET, REVISION 2.0: ╥. ╠. ┌ARLING) AS WELL AS TAKING THE BLAME/GLORY FOR
  15. ANY CHANGES THAT YOU SHOULD MAKE.  ╨LEASE REPORT ANY ENHANCEMENTS TO:
  16. .NF
  17. .SP 1
  18. .IN +5
  19. ═ARK ╥. ╥INFRET     AND     ╥AYMOND ╠. ┌ARLING
  20. 348 ╔NDIAN ┴VE.             245 ╫ILEY ├T.
  21. ╨ORTSMOUTH, ╥╔  02871       ╘URLOCK, ├┴  95380
  22. (401)-846-7639              (209)-634-4106
  23. .IN -5
  24. .FI
  25. .SP 
  26. ╬O WARRANTIES ARE MADE WITH REGARD TO THE USE OF THIS PROGRAM,
  27. NOR IS ANY SUPPORT PLEDGED (BUT YOU MIGHT ASK).
  28. ╒SE IT/ABUSE IT AT YOUR OWN RISK.
  29. .SP 2
  30. ╔NTRODUCTION
  31. .SP 1
  32. .TI +5
  33. ├-┴╙╙═ IS A 6502 ASSEMBLER SPECIFICALLY
  34. TARGETED TO THE ├OMMODORE 64 COMPUTER
  35. RUNNING ╨RO-╠INE'S ├-POWER (TM) ├ LANGUAGE
  36. DEVELOPMENT SYSTEM.  ├-┴╙╙═ IS DERIVED
  37. FROM A GENERIC 6502 ASSEMBLER WHICH WAS
  38. CONTRIBUTED TO ╒╙┼╬┼╘ BY ╩. ╚. VAN ╧RNUM
  39. OF ┴╘&╘ ┬ELL ╠ABORATORIES.  ╫ITHOUT THAT
  40. HEAD START, THIS PROGRAM WOULD STILL BE
  41. IN THE DESIGN STAGES.  
  42. .SP 2
  43. .TI +5
  44. ┴NYONE FAMILIAR WITH THE ORIGINAL SOURCE WILL, HOWEVER,
  45. OBSERVE THAT MAJOR CHANGES WERE MADE TO
  46. TAILOR THE SOURCE TO FIT THE CONSTRAINTS
  47. OF THE ├-╨OWER COMPILER, SUCH AS CHANGING
  48. INTS TO UNSIGNED'S WHERE POSSIBLE.  ╘HE
  49. OPCODE TABLES WERE SPLIT APART INTO TWO
  50. SEPARATE PIECES.  ┴LSO, AN #╔╬├╠╒─┼ FACILITY
  51. HAS BEEN ADDED AS A CONVENIENCE.
  52. ╧THER MINOR ENHANCEMENTS LIKE ADDITIONAL
  53. EXPRESSION HANDLING CAPABILITIES AND
  54. CONDITIONAL ASSEMBLY WILL ALSO BE
  55. APPARENT.  ╘HIS
  56. ASSEMBLER WILL GENERATE ├-╨OWER COMPATIBLE
  57. OBJECT FILES WHICH CAN BE LINKED TO ├
  58. LANGUAGE PROGRAMS, IF THE PROPER PARAMETER
  59. PASSING CONVENTIONS ARE OBSERVED, OR THE
  60. OBJECTS CAN BE LINKED INTO A STAND-ALONE
  61. ASSEMBLY LANGUAGE PROGRAM, WHILE USING THE
  62. EXCELLENT ENVIRONMENT OF THE ├-╨OWER SHELL
  63. , EDITOR AND LINKER.
  64. .TI +5
  65. ┴LTHOUGH IT IS TAILORED FOR THE ├-╨OWER
  66. ENVIRONMENT, THE CODE IS HIGHLY STANDARD,
  67. PORTABLE ├.  ╘HIS IS DEMONSTRATED BY THE
  68. MINIMAL NUMBER OF CHANGES THAT NEED TO
  69. BE MADE TO PORT THE CODE TO ╒NIX (#IFDEF ╒╬╔╪).
  70. .TI +5
  71. ╘HIS DOCUMENT IS ABOUT AS TERSE AS THEY COME.
  72. ╔F YOU'RE LOOKING FOR A TUTORIAL ON ASSEMBLY
  73. LANGUAGE, IT AIN'T HERE.  ╘HE ACCOMPANYING
  74. TEST PROGRAMS SHOULD BE SUFFICIENT TO ILLUSTRATE
  75. THE VARIOUS SYNTAX ELEMENTS FOR A MODERATELY
  76. EXPERIENCED PROGRAMMER.
  77.  
  78. .BP
  79. ╙╧╒╥├┼ ╠╔╬┼ ╞╧╥═┴╘
  80. .SP 1
  81. <LABEL> <OPERATION> <OPERAND> <COMMENT>
  82. .SP 1
  83. ┼ACH FIELD IS TERMINATED BY ONE OR MORE SPACES, A TAB OR A ';' (WHICH
  84. BEGINS THE COMMENT FIELD IMMEDIATELY).
  85. .SP
  86. ╠┴┬┼╠ ╞╔┼╠─:
  87. .SP 1
  88. ╔F FIRST CHARACTER IS ';', ENTIRE LINE IS A COMMENT.
  89. .SP 1
  90. ╔F THE FIRST CHARACTER IS '#', THE ASSEMBLER WILL 
  91. EXPECT AN #INCLUDE STATEMENT IDENTICAL IN SYNTAX TO
  92. A ├ PREPROCESSOR INCLUDE STATEMENT.  ╘HE FILENAME
  93. COMPONENT MAY BE ENCLOSED IN BRACKETS (<FILENAME>)
  94. OR DOUBLE QUOTES ("FILENAME").
  95. .SP 1
  96. ╔F THE FIRST CHARACTER IS A SPACE,
  97. THE LABEL FIELD IS NULL.
  98. ╠ABELS ARE ALPHANUMERIC STRINGS BEGINNING
  99. WITH 'A' THROUGH 'Z', '┴' THROUGH '┌',
  100. UNDERSCORE OR PERIOD FOLLOWED BY ANY OF THE ABOVE
  101. CHARACTERS, '$', OR '0' THROUGH '9'.  ╠ABELS ARE
  102. CASE-SENSITIVE ('A' IS NOT THE SAME AS '┴') AND
  103. MAY BE UP TO 12 CHARACTERS LONG.
  104. ┴, ╪, ┘, A, X AND Y ARE RESERVED LABELS.
  105. (╘HESE RULES ARE DESIGNED TO BE COMPATIBLE
  106. WITH THE RULES FOR EXTERNAL LABELS IN
  107. ├-╨OWER.)
  108. .SP 2
  109. ╧╨┼╥┴╘╔╧╬ ╞╔┼╠─
  110. .SP 1
  111. ╒PPER AND LOWER CASE LETTERS ARE EQUIVALENT.
  112. ═ACHINE OPERATION MNEMONICS ARE:
  113. .NF
  114. .IN +5
  115. .SP 1
  116. ┴─├     ┬═╔     ├╠─     ─┼╪     ╩╙╥     ╨╚┴     ╥╘╙     ╙╘┘
  117. ┴╬─     ┬╬┼     ├╠╔     ─┼┘     ╠─┴     ╨╚╨     ╙┬├     ╘┴╪
  118. ┴╙╠     ┬╨╠     ├╠╓     ┼╧╥     ╠─╪     ╨╠┴     ╙┼├     ╘┴┘
  119. ┬├├     ┬╥╦     ├═╨     ╔╬├     ╠─┘     ╨╠╨     ╙┼─     ╘╙╪
  120. ┬├╙     ┬╓├     ├╨╪     ╔╬╪     ╠╙╥     ╥╧╠     ╙┼╔     ╘╪┴
  121. ┬┼╤     ┬╓╙     ├╨┘     ╔╬┘     ╬╧╨     ╥╧╥     ╙╘┴     ╘╪╙
  122. ┬╔╘     ├╠├     ─┼├     ╩═╨     ╧╥┴     ╥╘╔     ╙╘╪     ╘┘┴
  123. .FI
  124. .IN -5
  125. .SP 1
  126. ╨SEUDO OPERATION MNEMONICS ARE:
  127. .IN +4
  128. .SP 1
  129.  =      EQUATE LABEL NAME TO OPERAND FIELD VALUE
  130. (SPACE IS NOT NEEDED TO TERMINATE THIS OPERATION).
  131. .SP
  132.  .╫╧╥─  ASSIGN 16 BIT VALUE OF OPERAND FIELD TO NEXT
  133. TWO LOCATIONS; LOW BYTE OF VALUE FIRST, THEN HIGH BYTE.
  134. .SP
  135.  .─┬┘╘  ASSIGN 16 BIT VALUE OF OPERAND FIELD TO NEXT
  136. TWO LOCATIONS; HIGH BYTE OF VALUE FIRST, THEN LOW BYTE.
  137. .SP
  138.  .┬┘╘┼  ASSIGN 8 BIT VALUE OF OPERAND FIELD TO NEXT
  139. LOCATION.
  140. .SP
  141.  .─┼╞ <LABEL>,...,<LABEL>  ╘HE <LABEL>S, WHICH MUST
  142. APPEAR LATER IN THE SOURCE, WILL BE EXTERNALLY DEFINED
  143. SO THAT THEY MAY BE REFERENCED (VIA .╥┼╞) IN A 
  144. SEPARATE SOURCE.
  145. .SP
  146.  .╥┼╞ <LABEL>,...,<LABEL>  ╘HE <LABEL>S ARE DEFINED TO
  147. BE EXTERNAL TO THIS PACKAGE, THEREBY ALLOWING REFERENCES
  148. WITHOUT CAUSING "╒NDEFINED SYMBOL" ERRORS.  ┴NY ATTEMPT 
  149. TO LINK THIS MODULE WITHOUT INCLUDING THE MODULE WHICH
  150. EXTERNALLY DEFINES THESE <LABEL>S WILL RESULT IN AN
  151. "UNSATISFIED EXTERNAL REFERENCE" ERROR IN THE LINKER.
  152. .SP
  153.  .╬╠╙╘  TURN LISTING MODE OFF (THIS SOURCE
  154. LINE IS NOT LISTED).
  155. .SP
  156.  .╠╔╙╘  TURN LISTING MODE ON (NORMAL MODE) (THIS
  157. SOURCE LINE IS NOT LISTED).
  158. .SP
  159.  .┬╙╙ N  ╥ESERVE N BYTES OF STORAGE AT THE
  160. CURRENT LOCATION (N MUST BE AN ABSOLUTE
  161. EXPRESSION).  ╘HESE BYTES ARE INITIALIZED
  162. TO ALL ZEROS.
  163. .SP
  164.  .─╙┼╟ N  ┴LLOCATE A SEPARATELY RELOCATABLE
  165. DATA SEGMENT OF N BYTES.  ╘HIS STATEMENT MUST HAVE
  166. A LABEL, AND THE LABEL IS THE NAME OF THE
  167. DATA SEGMENT.  ╘HIS DATA SEGMENT WILL BE
  168. EXTERNAL, AND THUS CAN BE REFENCED
  169. FROM OTHER MODULES WHICH DECLARE IT IN A
  170.  .╥┼╞ STATEMENT.  ╘HE .─╙┼╟ STATEMENT WILL
  171. NOT RESERVE ANY IN-LINE STORAGE.
  172. .SP
  173.  .╔╞┼╤, .╔╞╬┼, .╔╞╟╘, .╔╞╟┼, .╔╞╠╘, .╔╞╠┼,
  174. ALL REQUIRE TWO OPERANDS, SEPARATED BY
  175. A COMMA.  ┴LL TERMS IN THE OPERANDS MUST
  176. BE DEFINED EARLIER IN THE SOURCE CODE.
  177. ╘HE FOLLOWING CODE WILL BE ASSEMBLED ONLY
  178. IF THE STATED CONDITION IS TRUE.  ╧PERAND
  179. VALUES ARE INTERPRETTED AS UNSIGNED VALUES,
  180. AND ANY RELOCATION ATTRIBUTE IS IGNORED.
  181. .SP
  182.  .┼╠╙┼  MAY OPTIONALLY BE USED AFTER A .╔╞XX
  183. OPERATOR.  ╘HE FOLLOWING CODE WILL BE
  184. ASSEMBLED IF THE MOST RECENT .╔╞XX THAT
  185. HAS NOT BEEN MATCHED BY A .┼╠╙┼ OR .╞╔
  186. WAS FALSE, AND NO
  187. PREVIOUS .╔╞XX IS INHIBITING ASSEMBLY.
  188. .SP
  189.  .╞╔  ENDS THE .╔╞XX CONSTRUCT.  ╘HE
  190. FOLLOWING CODE IS ASSEMBLED IF AND ONLY
  191. IF ASSEMBLY WAS IN PROGRESS PRIOR TO THE
  192. ORIGINAL .╔╞XX.
  193. .IN -4
  194. .SP 2
  195. ╧╨┼╥┴╬─ ╞╔┼╠─
  196. .SP 1
  197. ╧PERAND FIELD EXPRESSIONS USE INFIX NOTATION AND ARE EVALUATED
  198. FROM LEFT TO RIGHT.  ╨RECEDENCE CAN BE MINIMALLY CONTROLLED 
  199. THROUGH THE USE OF PARENTHETICAL EXPRESSIONS WHICH ARE BRACKETED
  200. BY THE LEFT AND RIGHT BRACKET CHARACTERS (E.G. [<EXPRESSION>] )
  201. RATHER THAN THE USUAL PARENTHESES.  ╘HIS CHOICE WAS MOST LIKELY
  202. MADE TO AVOID CONFLICT WITH THE INDIRECT ADDRESSING MODES WHICH
  203. USE PARENTHESES AS IN ╠─┴ (ADDR),┘.  ╬O IMBEDDED SPACES ARE
  204. PERMITTED.
  205. .SP1
  206. ╙INCE THIS IS A RELOCATING ASSEMBLER, OPERANDS
  207. MUST EVALUATE TO A VALUE WHICH IS EITHER
  208. "RELOCATABLE", "ABSOLUTE", OR "EXTERNAL".
  209. ┴ RELOCATABLE EXPRESSION IS ONE WHOSE VALUE
  210. MUST BE ADJUSTED BY ADDING THE LOAD ADDRESS
  211. OF THE MODULE WHEN IT IS LINKED.  ╘HE VALUE OF ABSOLUTE
  212. EXPRESSIONS DO NOT CHANGE WITH RELOCATION.
  213. ╘HE VALUES OF EXTERNAL EXPRESSIONS DEPEND
  214. PRIMARILY UPON A SINGLE EXTERNAL SYMBOL NAME,
  215. WHOSE VALUE WILL BE DETERMINED WHEN THE MODULE
  216. IS LINKED WITH ANOTHER WHICH DEFINES THE
  217. SYMBOL.  ╔N THIS ASSEMBLER, EXTERNAL SYMBOLS
  218. MAY BE MODIFIED BY ADDING OR SUBRACTING AN
  219. ABSOLUTE QUANTITY LESS THAN 0X2000  (E.G.
  220. LDA XREF+2).  ╔N THAT CASE, THE EXTERNAL
  221. SYMBOL NAME MUST COME FIRST, FOLLOWED BY +
  222. OR - ABSOLUTE EXPRESSION.
  223. .SP 1
  224. ╧PERAND FIELD TERMS INCLUDE LABELS AND NUMBERS.
  225. ┴STERISK (*) IS THE LABEL FOR THE LOCATION COUNTER VALUE.
  226. ╬UMBERS ARE BINARY, OCTAL, DECIMAL, HEXADECIMAL OR ┴╙├╔╔.
  227. ╬UMBER TYPE IS INDICATED BY THE FIRST CHARACTER OF THE NUMBER STRING AS FOLLOWS:
  228. .NF
  229. .IN +5
  230. .SP 1
  231. %       BINARY PREFIX
  232. @ OR 0  OCTAL PREFIX
  233. 1 - 9   DECIMAL BY DEFAULT (PREFIX IS PART OF NUMBER)
  234. $       HEXADECIMAL PREFIX
  235. '       ├┬═-┴╙├╔╔ CHARACTER PREFIX
  236. "       ├┬═-┴╙├╔╔ CHARACTER STRING PREFIX AND SUFFIX;
  237.         \N IS A NEW LINE; \L IS A FORM FEED.
  238.  
  239. .FI
  240. .IN -5
  241. .SP 1
  242. ╧PERAND FIELD OPERATIONS AND THE CORRESPONDING SYMBOLS ARE:
  243. .NF
  244. .IN +5
  245. .SP 1
  246. +       ADDITION
  247. -       SUBTRACTION (OR UNARY NEGATION)
  248. /       DIVISION
  249. *       MULTIPLICATION
  250. %       MODULO (REMAINDER AFTER INTEGER DIVISION)
  251. ^       (UP-ARROW) LOGICAL EXCLUSIVE ╧╥
  252. &       LOGICAL ┴╬─
  253. ▀       LOGICAL ╧╥
  254.  
  255. .IN -5
  256. .SP 1
  257. .FI
  258. ╘HE FOLLOWING MAY APPEAR ONLY AT THE
  259. BEGINNING OF AN EXPRESSION:
  260. .NF
  261. .IN +5
  262. .SP 1
  263. !       USE TWO BYTE ADDRESSING, EVEN IF OPERAND<256
  264. <       LOW BYTE
  265. >       HIGH BYTE
  266. .FI
  267. .IN -5
  268. .SP 2
  269. ┼╥╥╧╥ ═┼╙╙┴╟┼╙
  270. .NF
  271. .SP 1
  272. ╒╬╦╬╧╫╬ ┼╥╥╧╥!!!                 (SOMEBODY GOOFED)
  273. ╔NTERNAL ERROR                   (OOPS)
  274. ╔NVALID OPERATION CODE
  275. ┴,╪,┘ ARE RESERVED SYMBOLS
  276. ╙YMBOL TABLE OVERFLOW            (SAME AS "╧UT OF MEMORY")
  277. ─UPLICATE DEFINITION
  278. ╙YNC ERROR                       (╨ASS 1/╨ASS 2 SYMBOL VALUE DIFFERS)
  279. ┬RANCH OUT OF RANGE
  280. ═ISSING OPERAND
  281. ╔NVALID ADDRESSING MODE
  282. ═ISSING STRING TERMINATOR        (NO SECOND ")
  283. ╓ALUE ERROR                      (OPERAND VALUE TOO LARGE OR SMALL)
  284. ╒NDEFINED SYMBOL
  285. ╙YMBOL REQUIRED
  286. ═ULTIPLY DEFINED
  287. ╥ELOCATION ERROR                 (ILLOGICAL EXPRESSION INVOLVING
  288.                                   A SYMBOL )                                   
  289. ├OND ASSBLY NESTED TOO DEEPLY    (NO MORE THAN 6 NESTED .╔╞XX'S ALLOWED)
  290. ╒NBALANCED PARENTHESES           (MISSING ])
  291. ─IVIDE BY ZERO
  292. ╚I/╠O OPERATOR MUST BE FIRST     (< OR > OUT OF SEQUENCE)
  293. ╔NVALID OPERAND FIELD
  294. ╧UT OF MEMORY                    (TOO MANY SYMBOLS OR REFERENCES)
  295. ".╞╔" WITHOUT ".╔╞"
  296. ╠ABEL REQUIRED
  297. ╠ABEL NOT ALLOWED
  298.  
  299. .FI
  300. .SP 1
  301. ╔╬╓╧╦╔╬╟ ├-┴╙╙═:
  302. .SP 1
  303.  
  304. ASSM █-CDFILOS▌ <FILE...FILE>
  305. .SP 1
  306. ╧PTIONS:
  307. .NF
  308. .IN +5
  309. .SP 1
  310. -C   DO NOT LIST CODE EXCLUDED BY .╔╞XX
  311. -D   PRINT DEBUGGING INFORMATION
  312. -F   DO NOT REFORMAT SOURCE LINES FOR LISTING
  313. -I   IGNORE ANY .NLST PSEUDO OPERATIONS
  314. -L   LIST ERRORS ONLY
  315. -O   SUPPRESS OBJECT FILE CREATION
  316. -S   GET SYMBOL TABLE PRINTOUT 
  317.  
  318. .FI
  319. .IN -5
  320.  
  321. ╙OURCE <FILE> NAMES MUST END WITH A '.A' SUFFIX.
  322. ╫HEN AN OBJECT FILE IS CREATED, A '.O' SUFFIX IS
  323. APPENDED TO THE ROOT OF THE SOURCE NAME.  ╞OR
  324. EXAMPLE, TEST.O WILL BE CREATED WHEN TEST.A IS
  325. ASSEMBLED.  ╔F MORE THAN ONE FILE NAME IS GIVEN,
  326. SEPARATE ASSEMBLIES ARE PERFORMED ON EACH ONE IN
  327. TURN.
  328.  
  329. .SP 2
  330. ─┼╞╔├╔┼╬├╔┼╙:
  331.  
  332. ╘HE ASSEMBLER IS QUITE LARGE.  ╘HIS IS DUE IN PART
  333. TO THE CODE GENERATION CHARACTERISTICS OF THE ├-╨OWER
  334. COMPILER.  ╘HE SOURCE COULD PROBABLY BE
  335. FURTHER OPTIMIZED TO FINE TUNE THE GENERATED CODE OR
  336. IMPROVED ALGORITHMS.
  337. .SP
  338. ╔T WOULD BE NICE TO HAVE A WILDCARD FACILITY
  339. WITH THE SOURCE FILENAMES.  ╞OR INSTANCE,
  340. ASSM -F ATEST*.A WOULD ASSEMBLE ALL .A FILES
  341. ON THE CURRENT DISK WHICH BEGIN "ATEST".
  342. ╔ FEAR THAT THIS WOULD MAKE THE ASSEMBLER
  343. PROHIBITIVELY BIG, HOWEVER.
  344. .SP 
  345. ╬O MACRO FACILITY CURRENTLY EXISTS.  ╔ WOULD LIKE TO SEE
  346. A SYNTAX OF THE FORM:
  347. .BR
  348. .NF
  349. #DEFMAC <MACRONAME>[(PARAM,...,PARAM)
  350.         <STATEMENT>
  351.              .
  352.              .
  353.              .
  354.         <STATEMENT>
  355. #ENDMAC
  356. .FI
  357.