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