home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / asm1 / Docs / Manual < prev   
Encoding:
Text File  |  1996-06-15  |  9.9 KB  |  244 lines
  1.  
  2. !ASM v1.00
  3. ----------
  4.  
  5. Welcome to !ASM! !ASM is a very advanced assembler, with none of the 
  6. limitations imposed on you by BASIC or most of the other ARM assemblers
  7. available. Features include:
  8.  
  9.  - Auto expansion of commands with constants that do not assemble into one
  10.    instruction (no need for an ADRL!)
  11.  - Local labels, structs and macros
  12.  - RISC PC compatability
  13.  - full preprocessor including repeated sections of code, conditional 
  14.    assembly, multiple source files and more 
  15.  - support for floating point instructions (registered version only)
  16.  
  17. It takes no great mental strain to realise that !ASM was inspired by the
  18. excellent !extASM, which, while having most of the features !ASM does, it
  19. produces larger code and is not RISC PC compatable owing to a funny method
  20. of encryption...
  21.  
  22. !ASM is SHAREWARE! That means that you need to register it if you find it
  23. useful, or want to release any of your creations into the world. I impose
  24. no evaluation period, merely the fact that if you register, development will
  25. continue apace, and I'll fulfil my promises for the next few versions.
  26.  
  27. Other reasons for registering
  28. -----------------------------
  29.  
  30. It's cheap! It comes with a colour !Zap mode designed specifically for !ASM,
  31. a more comprehensive macro library. The shareware version is also slightly
  32. disabled in that you cannot have more than 10 macros, or 4000 lines of 
  33. assembled code.
  34.  
  35. The registered version also supports the floating point instructions, and
  36. I'm more likely to provide support to registered users.
  37.  
  38. Using !ASM
  39. ----------
  40.  
  41. !ASM takes in text files and regurgitates ARM code files. It can be used to
  42. create modules, utilities, absolute files, etc, etc.
  43.  
  44. For those of you who haven't used !extASM before, its syntax is very similar
  45. to BASIC's - labels begin with a '.', and the instructions all take the same
  46. format. However, it sports some features that, once you've used, you'll be
  47. unable to do without. It can auto-expand instructions that it would
  48. otherwise be unable to assemble meaningfully, using a temporary register
  49. where required. This makes instructions such as 'MOV R0,#257' finally
  50. possible, as well as removing the need for a 'ADRL' macro.
  51.  
  52. It supports throwback, so you can remove those irritating errors much 
  53. quicker if you have a copy of 'DDEUtils'. It supports local labels, allowing
  54. neater and more meaningful code, and has a comprehensive pre-processor. It
  55. also has the benefit of not needing all that extra code that BASIC requires
  56. to start itself up.
  57.  
  58. Auto-expansion
  59. --------------
  60.  
  61. Some commands (MOV, for example) can be auto-expanded without the need for
  62. a temporary register, and some (CMP, for example), need a temporary register
  63. to store intermediate values. You can assign a temporary register with the
  64. pseudo command 'TEMP Rn', where Rn is the register you wish to use as 
  65. temporary. I generally use R12 or R11, but any will do.
  66.  
  67. The ADR/LDR/STR auto-expansion may change the size of the code produced -
  68. this will result in extra passes being used to compensate for any inaccuracy
  69. incurred.
  70.  
  71. Local labels
  72. ------------
  73.  
  74. These are an immensely useful part of !ASM. Not only does use of these speed
  75. up assembly, it also allows much more sensible names for labels in large
  76. pieces of code. These are defined in the same way as global labels, but with
  77. the first letter of the label as an underscore ('_'). The next 'main' label
  78. (ie one without an underscore) will make all the previous local labels 
  79. invalid (they go 'out of scope'). While 'in scope' they perform just like
  80. any ordinary label.
  81.  
  82. The parser
  83. ----------
  84.  
  85. !ASM contains an advanced expression parser, similar in capability and
  86. operation to BASIC's. You can, therefore, have a constant like 
  87. '#45+(1<<3)-(2*3)' if you really want to. Note that these do compile
  88. slightly slower than if you just used a single number. Binary numbers
  89. may be prefixed with '%' and hexidecimal numbers with '&'.
  90.  
  91. The preprocessor
  92. ----------------
  93.  
  94. This supports several commands - see the reference file for full details.
  95.  
  96. #base <number> - this sets the 'code base' to <number>. By default, this is
  97.                  at &8000, so for a module, you may want to reset it to 0.
  98.                  
  99. #if/#else/#endif - these allow conditional assembly - their use should be
  100.                    obvious. Note that the conditions are in the same style
  101.                    as C condtions. This essentially means that '==' is now
  102.                    the equivilence operator rather than BASIC's '='.
  103.  
  104. #rept <n>/#endr - in speed critical applications, sometimes repeating code 
  105.                   several times is needed to achieve the necessary speed. 
  106.                   These two commands allow you to repeat the enclosed code 
  107.                   <n> times.
  108.  
  109. #include <filename> - this command allows you to include another source file
  110.                       at this point. It is useful to know that <tmp$path> is
  111.                       set to the directory in which the original source file
  112.                       is located.
  113.  
  114. #smile - produces a grin when things work well.
  115.  
  116. Pseudo-instructions
  117. -------------------
  118.  
  119. Aside from the macros, which create new pseudo-instructions, several are
  120. built in. Once again, the reference file contains full details, but some
  121. of the more useful are:
  122.  
  123. INCBIN <filename> - this includes a binary file into the final object code.
  124.                     Handy for including pre-calculated sine tables and 
  125.                     suchlike.
  126.  
  127. ALIGN - well, we should all know what this does by now. Unlike BASIC, it 
  128.         pads with 0's to ensure that no garbage is left in the code.
  129.  
  130. DIV Rd,Rn,Rs - Actually a macro... The code for this originates on World of
  131.                Kryten BBS and was originally written by Hugo Fiennes
  132.                (I think...). As there was no licencing information with the
  133.                code, I presume it is PD, so here it is. This requires a temp
  134.                register to assemble correctly.
  135.  
  136. Defining macros is fully documented in the reference file.
  137.  
  138. The licence
  139. -----------
  140.  
  141. By running !ASM or any companion program, you indicate that you agree to be
  142. bound by these conditions. If you cannot agree, you must delete the software
  143. from your system.
  144.  
  145. The software (!ASM and all associated files, including this one) is 
  146. SHAREWARE. This means that if you intend to use it for an extended period,
  147. or to produce work for public release, you should register it. Registration
  148. costs £10, and can be achieved by sending a cheque or postal order to:
  149.  
  150. Andrew Hunter,
  151. 18 Warren Close,
  152. Elmswell,
  153. Bury St. Edmunds,
  154. Suffolk,
  155. IP30 9DS
  156.  
  157. For your money, you will get the latest version, and will be informed of
  158. any major updates when they become available (to which you can upgrade
  159. by sending your orignal disc and and SAE). The registered version has
  160. numerous extensions and is well worth while.
  161.  
  162. YOU MAY NOT DISTRIBUTE ANY WORK ASSEMBLED ON THE SHAREWARE VERSION OF !ASM.
  163. THIS INCLUDES PUBLIC DOMAIN DISTRIBUTION AS WELL AS COMMERCIAL
  164. DISTRIBUTION. You may, however, freely distribute work created on the
  165. registered version of !ASM by any means you please.
  166.  
  167. The author (of !ASM) cannot accept responsibility for the mis-function of
  168. any software created using it. This is obviously the concern of the author
  169. of that software.
  170.  
  171. !ASM is Copyright © Andrew Hunter, 1996. However, you may distribute this
  172. ShareWare version so long as you ensure that all files remain intact and
  173. unaltered. If you suspect that your version has been tampered with, you
  174. can obtain a genuine copy by sending a blank disc with SAE to the address
  175. above. Any distributed version MUST have this file.
  176.  
  177. You may not disassemble, reverse engineer or alter any of the programs
  178. contained within the !ASM directory at any time.
  179.  
  180. This ShareWare version may not be sold as part of any commercial package,
  181. although PD libraries MAY distribute it so long as they comply with these
  182. conditions, and do not charge above a reasonable price for their 
  183. distribution (say, 3 pounds sterling).
  184.  
  185. The registered version MUST NOT be distributed. You are permitted to make
  186. backup copies for your personal use, but it MAY NOT be installed on more
  187. than one machine at any one time.
  188.  
  189. The author (Andrew Hunter) CANNOT accept responsibility for any damage 
  190. caused by your use/inability to use the software. You use the software
  191. entirely at your own risk. (That said, I doubt it could cause much damage).
  192.  
  193. Extra conditions may be imposed upon your use in the start-up banner that
  194. the assembler produces.
  195.  
  196. The future
  197. ----------
  198.  
  199. In the pipeline is an AOF version of this assembler... It will probably cost
  200. £20 (or £10 to registered users). This will allow you to compile projects
  201. quicker, as well as link them to C/Pascal/etc programs. I am also thinking
  202. of writing a debugging utility for this version.
  203.  
  204. Of course, you are welcome to send suggestions as to other features you'd
  205. like to see implemented - development of the ShareWare version is unlikely
  206. to progress much farther, but for registered users...
  207.  
  208. Contacting me
  209. -------------
  210.  
  211. To register, you must contact me by snail-mail. A digitised cheque is not
  212. acceptable...
  213.  
  214. Snail mail
  215.  
  216. Andrew Hunter
  217. 18 Warren Close,
  218. Elmswell,
  219. Bury St. Edmunds,
  220. Suffolk,
  221. IP30 9DS
  222.  
  223. E-mail
  224.  
  225. Internet - ahunter@spuddy.mew.co.uk
  226. Arcade - 'Ahunter'
  227.  
  228. Feel free to send money, suggestions, bugs or encouragement.
  229.  
  230. Gumph
  231. -----
  232.  
  233. For those of you who are interested, !ASM's first piece of useful code which it
  234. assembled was !VOOBars. This was actually distributed with a beta release just
  235. to prove it did work. Next, I ambitiously decided to try it out on !SpaceRoads,
  236. an 8,000 line monster of a program. After 3 minutes (it was very slow then) of
  237. chugging, it went bleagh and died. When I fixed that bug, it assembled OK, just
  238. didn't run. I decided to attempt the less taxing 'Tanx', a mere 5,000 lines, but
  239. with floating point support. After lots of swearing, debugging and more
  240. swearing, it worked! So, try on SpaceRoads again. Zip. To cut a long story
  241. short, I eventually tracked down and destroyed that bug, so you now know that
  242. !ASM is quite capable of handling enormous programs as well as small ones (and
  243. in a mere 45 seconds now... on my A3000!)
  244.