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