home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / program / a / as1_23 / ReadMe < prev   
Encoding:
Text File  |  1994-01-02  |  10.2 KB  |  303 lines
  1. Intoduction
  2. ===========
  3.  
  4. !AS is a simple assembler. It is designed to be used with the desktop
  5. development environment supplied with Desktop C, as Desktop C doesn't
  6. include an assembler. This assembler was at the beginning a backend to
  7. another compiler and does therefore not contain all the glorious commands in
  8. Acorn's assembler. The most obvious omissions are macros and debug
  9. informations. I have included the source in the distribution to compensate
  10. this: If you want it, add it. 
  11.  
  12. !AS generates aof files, that contain type-2 relocations, so some old
  13. linkers might not be able to link them. There should not be any problem if
  14. the linker can handle aof files of version 1.50 or later.
  15.  
  16. For condition of use read the file Conditions which is included in this
  17. distribution.
  18.  
  19. It should be possible to run !AS on a UNIX machine thanks to Andy Duplain.
  20. Only the command line version are ported (No DDE on UNIX). No UNIX binaries
  21. are included but 'MakefileU' contains a makefile for UNIX that might work.
  22. Otherwise it can be done by hand. The only special thing is to compile and
  23. run mkendian.c before you try to compile the assembler. This creates an
  24. include file (endiandef.h) with endian information. The version included
  25. is for a little endian machine, which is correct for Archimedes.
  26.  
  27. Installation
  28. ------------
  29. To install !AS to a hard disc simply copy the !AS directory into the
  30. DDE directory on your hard disc, and copy/rename AS to your library
  31. directory. 
  32.  
  33. Copy the following lines to your !Make.choices.tools file in the DDE
  34. directory.
  35.  
  36. ------------------------------------
  37. AS
  38. s
  39. -dde -throwback
  40. as $(asflag
  41. s) -o $@ $<
  42. DDE:!AS.desc
  43. DDE:!AS.!setup
  44. ------------------------------------
  45.  
  46. There is an incomplete help file that can be used with SrcEdit. If you
  47. want to use it then copy/rename the file HelpAs to !SrcEdit.help.AS and copy
  48. the following lines to your !SrcEdit.choices.languages.
  49.  
  50. ------------------------------------
  51. As
  52. none
  53. <SrcEdit$dir>.help.AS
  54. ------------------------------------
  55.  
  56. Compilation
  57. -----------
  58.  
  59. Try the Makefile that is included. If !Make complain then the easiest is
  60. to make a new Makefile. All c-files, C:o.stubs and C:o.RISC_OSlib is
  61. needed.
  62.  
  63. Using !AS
  64. =========
  65.  
  66. To start !AS double click on the !AS application. This will place the
  67. !AS icon on the icon bar.
  68.  
  69. Click Select on the !AS icon, this will open a setup dialog box
  70. containing a single writeable icon labelled "Source:", a number
  71. of option icons and two action icons labelled "Run" and "Cancel".
  72.  
  73. To assemble a file drag the assembler file to the Source
  74. icon and click Run. Note that the assembler source must be stored in a
  75. directory called "s".
  76.  
  77. The output will be saved with the same tail name as the source file, but in
  78. a directory called "o" instead of "s".
  79.  
  80. If errors are encountered in the source then the errors will be listed in a
  81. window. If you are using the editor !SrcEdit and the "Throwback" option is
  82. enabled the errors will also be displayed in a "Throwback" window. Double
  83. clicking on an error in the Throwback will cause !SrcEdit to open the source
  84. file containing the error at the line which generated the error, this line
  85. will be highlighted for clarity.
  86.  
  87. You can only assemble one file at a time, if you drop more than one file on
  88. the "Source" icon only one will be assembled.
  89.  
  90.  
  91. Setup dialog box options
  92. ------------------------
  93.  
  94. There are only four options.
  95.  
  96. Pedantic:
  97.  
  98. The assembler will complain in some places where it otherwise would fix the
  99. problem silent, e.g., if you add with a negative number which the assembler
  100. must change to a subtraction, or when it must change the order of the
  101. operands in a multiplication. It will also tell you if it thinks your code
  102. are ugly, e.g., compare instructions with an explicit 's' or using a
  103. coprocessor mnemonic with coprocessor 1. (This is the floating point unit
  104. which has its own mnemonics.)
  105.  
  106. Verbose:
  107.  
  108. The assembler will inform about the progress. Currently messages are given
  109. about which files that are included.
  110.  
  111. Throwback:
  112.  
  113. If this option is enabled and the editor !SrcEdit is loaded errors
  114. in compilation are listed in a Throwback window. This window can
  115. be used to rapidly locate and correct errors in your program.
  116.  
  117. Autocast:
  118. The assembler converts integers to float if needed by a command or
  119. mnemonic. Note that no conversion is done inside expressions, it's
  120. only the result that can be converted.
  121.  
  122. Only throwback is enabled by default.
  123.  
  124. Setup menu options
  125. ------------------
  126.  
  127. Other less commonly used options may be accessed from the menu
  128. on the setup dialog box. Only one option is availible here.
  129.  
  130. Command line:
  131.  
  132. This option allows you to examine and/or change the command line
  133. generated by the !AS frontend which is used to run the assembler. When you
  134. change the command line and wish to execute the changed command click on the
  135. Run icon in the Command line dialog box. Once you move off the Command line
  136. dialog box onto the setup menu the changed command line will be forgotten
  137. and the original command line (as constructed by the !AS tool) will be
  138. reconstructed.
  139.  
  140. The command line
  141. ================
  142.  
  143. The syntax of the Assembler command line is:
  144.  
  145. *as [options] [-Idirectory] [-o filename] [filename]
  146.  
  147. [filename]
  148.  
  149. This is the optional source file, stdin will be used if it isn't present.
  150.  
  151. [-o filename]
  152.  
  153. This is the optional destination file. If no destination file is given and a
  154. source file is given then its "s"-directory is changed to "o", otherwise
  155. stdout is used.
  156.  
  157. [-Idirectory]
  158.  
  159. Directory to search when executin lnk and get commands. It's possible to give
  160. more than one directory but there must be a '-I' before every directory.
  161.  
  162. The following options are available
  163.  
  164. -v
  165.  
  166. Print version.
  167.  
  168. -p
  169.  
  170. Enable pedantic mode.
  171.  
  172. -h
  173. -H
  174. -?
  175.  
  176. Print command line syntax.
  177.  
  178. -verbose
  179.  
  180. Print some information about the progress.
  181.  
  182. -dde
  183.  
  184. Replaces '@' in the beginning of filenames with <Prefix$Dir>
  185.  
  186. -throwback
  187.  
  188. Enable throwbacks.
  189.  
  190. -autocast
  191.  
  192. Enable casting from integer to float.
  193.  
  194. -gcc
  195.  
  196. '@' now means start of comment.
  197.  
  198. -noalign
  199.  
  200. !As won't complain about nonalignend words (and instructions). Note that neither
  201. link 4.00 nor drlink 0.24 can reallocate non aligned words.
  202.  
  203. ===========================================================
  204. A short description of what is legal in an assembler source
  205. -----------------------------------------------------------
  206.  
  207. Max line length is 4096 characters. The following lines are legal:
  208.  
  209. Label      Instruction      ;Comment
  210.  
  211. All fields are optional, but the Instruction-field can not start at the
  212. first column. The Label-field must however start at the first position of a
  213. line.
  214.  
  215. Label      Command          ;Comment
  216.  
  217. Some commands make the Label-field compulsary but in most cases all fields
  218. are optional. The Command-field can not start at the first column. The
  219. Label-field must however start at the first position of a line.
  220.  
  221.  
  222. Identifier
  223. ----------
  224.  
  225. Identifiers start with a letter or an underscore, and can contain letters,
  226. digits and underscores. There are no limits on identifier length and all
  227. characters are significant. It is possible to include any character except
  228. '|' and newline in an identifier by enclosing it in '|'s:
  229.   |This is a funny label%%^&*(|
  230. The bars does not belong to the identifier so:
  231.   |abc|
  232. and
  233.    abc 
  234. are equal. The case of the characters are significant, and it is legal to
  235. define identifiers with the same name as mnemonics.
  236.  
  237.  
  238. Label
  239. -----
  240.  
  241. A label is an identifier with an optional colon at the end. The label gets
  242. the value  of the next free byte in the current area.
  243.  NOTE:
  244. This differs from Acorn's assembler as it always word align labels that are
  245. on the same line as an instruction. This assembler will however generate a
  246. warning in those cases so it is easy to change the assembler code by
  247. inserting an explicit align command at the previous line.
  248.  
  249.  
  250. Instruction
  251. -----------
  252.  
  253. The case is not significant for instructions. The assembler knows about the
  254. following instructions:
  255.  
  256. adc     add     and     bic     rsb     rsc     sub
  257. sbc     eor     orr     mov     mvn     cmn     cmp
  258. teq     tst     mul     mla     b       bl      swi
  259. ldr     str     ldm     stm
  260. cdp     mcr     mrc     ldc     stc                  (Coprocessor instructions.)
  261. swp                                                  (Not legal on ARM2.)
  262. adr                                                  (Syntesized instructon.)
  263. adf     muf     suf     rsf     fvf     rdf     pow  (Floating point instructions.)
  264. rpw     rmf     fml     fdv     frd     pol     exp  (Floating point instructions.)
  265. mvf     mnf     abs     rnd     sqt     log     lgn  (Floating point instructions.)
  266. sin     cos     tan     asn     acs     atn          (Floating point instructions.)
  267. cmf     cmfe    cnf     cnfe    ldf     stf          (Floating point instructions.)
  268. fix     flt     rfs     wfs     rfc     wfc          (Floating point instructions.)
  269.  
  270. A short description of most of the instructions is availible in the file
  271. HelpAs that is included in this distribution. (If you followed the
  272. instructions above then this file is moved to !SrcEdit.help.AS. In this case
  273. select the mnemonic you are interested in and press F1. This will bring up a
  274. window with a description of the selected mnemonic if you have choosen As as
  275. language in the option.language menu in !SrcEdit). You can locate the
  276. mnemonic in the file by searching after the mnemonic with a %-character in
  277. front, e.g., %swp.
  278.  
  279.  
  280. Command
  281. -------
  282.  
  283. The case is not significant for commands. The assembler knows about the
  284. following commands:
  285.  
  286. get     lnk     bin
  287. dcb     =       dcw     dcd     &       dcfs    dcfd
  288. area    align   %       ^       #       
  289. globl   export  import  entry  ltorg    (Normally not used together with a Label-field.)
  290. rn      fn      cn      equ     *       (Label-field is compulsary.)
  291. lnk     get
  292. dcfe    dcfp                            (These commands are not implemented, 
  293.                                                                    but they are known :-)
  294.  
  295. A short description of most of the commands is availible in the file
  296. HelpAs that is included in this distribution. (If you followed the
  297. instructions above then this file is moved to !SrcEdit.help.AS. In this case
  298. select the command you are interested in and press F1. This will bring up a
  299. window with a description of the selected command if you have choosen As as
  300. language in the option.language menu in !SrcEdit). You can locate the
  301. command in the file by searching after the command with a %-character in
  302. front, e.g., %dcfs.
  303.