home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 196.lha / APP / README < prev    next >
Text File  |  1988-12-27  |  7KB  |  260 lines
  1. A.P.P.    Assembly Pre-Processor
  2. ------------------------------
  3.  
  4. PUBLIC DOMAIN
  5.  
  6. written by Karl Lehenbauer, 12/8/88
  7. with a lot of design input by Peter da Silva
  8.  
  9.  
  10. Disclaimer and Redistribution Information
  11. -----------------------------------------
  12.  
  13. APP is placed freely into the public domain for any use without restriction.
  14. APP comes without warranties, expressed or implied.  This is free software.
  15. We don't have a contract.
  16.  
  17. I'm not asking for money for this, but if you feel compelled to send it 
  18. anyway, it is always appreciated.  Make checks to Hackercorp, 3918 
  19. Panorama, Missouri City, TX  77459
  20.  
  21.  
  22. What it is
  23. ----------
  24.  
  25. APP is a preprocessor for the 68000 assembler that comes with Aztec C for 
  26. the Amiga.  It will probably work with other 68000 assemblers.  APP 
  27. provides structured programming constructs for the assembly language
  28. programmer.  Specifically, APP provides support for IF-THEN-ELSE-ELSEIF-
  29. ENDIF constructs and for DO-WHILE-UNTIL-ENDDO constructs.  
  30.  
  31. Consider the C pseudocode fragment:
  32.  
  33. long a, b;
  34.  
  35.     if (a < 0)
  36.     {
  37.         less_than_zero_stuff();
  38.     }
  39.     else
  40.     {
  41.         not_less_that_zero_stuff();
  42.     }
  43.  
  44. In assembler (or pre-77 FORTRAN, for example) to do the same thing requires 
  45. the creation of two bogus labels, as in:
  46.  
  47.     move.l    _a,d0
  48.     bge        else_part
  49.     jsr        _less_than_zero_stuff
  50.     bra        past_the_else
  51. else_part
  52.     jsr        _not_less_than_zero_stuff
  53. past_the_else
  54.  
  55. When you start nesting these deeply, the code quickly becomes unreadable.
  56. Note also that you have to reverse the sense to branch around the code
  57. you really want to execute.  This makes the code less clear.
  58. If the assembler had structured programming constructs like C, Modula 2,
  59. Forth, etc, the creation of these superfluous labels is unnecessary.
  60. Using APP, the above code fragment can be rewritten:
  61.  
  62.     move.l    _a,d0
  63.     .if    lt
  64.     jsr        _less_than_zero_stuff
  65.     .else
  66.     jsr        _not_less_than_zero_stuff
  67.     .endif
  68.  
  69. To define an "if", enter an opcode of ".if" and an operand of a condition
  70. code that the assembler recognizes as a branch when following behind a 'b',
  71. as in condition codes "le", "lt", "eq", "ne", "gt", "ge" yielding "ble",
  72. "blt", "beq", "bne", "bgt", "bge"  You will have set up the condition
  73. codes before the ".if".
  74.  
  75. For in "if", APP will assemble a conditional branch with the sense reversed,
  76. branching to the matching ".else", ".elseif", or ".endif".  APP will make
  77. up labels and produce the equivalent branching code as above.  I have chosen
  78. to make APP's labels be 'L' followed by an increasing sequential integer
  79. label number.  This was chosen to avoid conflicting with Manx's '.' followed
  80. by the number so you can incrementally "structurize" and test as you hand
  81. optimize the output of cc with "-AT" flags selected.
  82.  
  83. APP also supports a do/enddo construct.  The way it works is ".enddo"
  84. compiles a "branch always" instruction back to the corresponding ".do".
  85. To exit the do/enddo, two constructs are provided.  These are ".while"
  86. and ".until".  ".while" takes a condition code and, if it is true,
  87. execution continues below the while, else a branch past the enddo is
  88. taken.  ".until" in the opposite manner, if the condition code is true
  89. a branch past the enddo is taken otherwise it isn't.  For example,
  90.  
  91.     .do
  92.       ;conditional setup stuff
  93.       .
  94.       .
  95.     .while ne
  96.       ; execution stuff
  97.       .
  98.       .
  99.     .enddo
  100.  
  101. ...will execute code between the do and the enddo until the condition code
  102. at the "while" isn't true anymore.  Multiple .whiles and .untils may be
  103. used and .whiles and .untils may be freely intermixed.
  104.  
  105. Nesting of conditionals is permitted to a depth of 32.  When nesting, I
  106. reccomment indenting your code, as in:
  107.  
  108.     tst.l    d0
  109.     .if gt
  110.         add.l    d0,d1
  111.         cmp.l    #max,d1
  112.         .if gt
  113.             move.l    #max,d1
  114.         .endif
  115.     .endif
  116.  
  117. Setting tab stops at four seems to work well.
  118.  
  119.  
  120. How To Invoke APP
  121. -----------------
  122.  
  123. APP requires that the sources files given to it end in ".app" and that
  124. the .app extension be specified.  APP produces an output file where
  125. the name is the name of your source file with ".asm" as the extension.
  126.  
  127.     app foo.app
  128.  
  129. ...produces foo.asm if app doesn't detect any errors while processing you
  130. .app source.
  131.  
  132.  
  133.  
  134. Integrating with your makefile
  135. ------------------------------
  136.  
  137. If you add the following rules to your makefile and list object files
  138. corresponding to your assembly preprocessor source .app files in your 
  139. make dependencies, make will run APP over your .app files and then
  140. run "as" over the resulting .asm files.
  141.  
  142. .app.o:
  143.     app $*.app
  144.     as $*.asm
  145.  
  146.  
  147. Condition Codes Known by APP 
  148. ----------------------------
  149.  
  150.     The following condition codes may be used APP's .if, .elseif, .while
  151.     and .until statements:
  152.  
  153.     "ne"
  154.     "eq"
  155.     "lt"
  156.     "ge"
  157.     "le"
  158.     "gt"
  159.     "cc"
  160.     "cs"
  161.     "vc"
  162.     "vs"
  163.     "hi"
  164.     "ls"
  165.     "pl"
  166.     "mi"
  167.  
  168. Consult your 68000 Reference Manual if you need to know
  169. what status register bits and states correspond to these 
  170. codes.  They're the standard ones.
  171.  
  172.  
  173. APP Error Messages
  174. ------------------
  175.  
  176. APP does a lot of checking of your APP "dot" statements to insure their
  177. validity.  Specifically, APP insures that all .ifs have matching .endifs,
  178. that all .dos have matching .enddos, that only one .else is specified
  179. inside a .if, that .elseifs are only specified inside .ifs, that .whiles
  180. and .untils are only specified inside a .do and that all "dot" structures
  181. are closed at end of file.  If APP does detect an error, it prints an
  182. error message including the line number and exits.  (It could conceivably
  183. go on, but I have yet to take it this far.)  If APP is pointing to the
  184. last line in the file, the problem is that you didn't close a .if or .do
  185. structure somewhere earlier in the file.
  186.  
  187. If APP exits with an error, it removes the .asm output file so the file
  188. won't confuse make into thinking everything went OK with APP when it really
  189. didn't.
  190.  
  191.  
  192. Enumeration of Variations by Pseudo-Example
  193. -------------------------------------------
  194.  
  195.     .if cc
  196.     .endif
  197.  
  198.     .if cc
  199.     .else
  200.     .endif
  201.  
  202.     .if cc
  203.     .elseif cc
  204.     .endif
  205.  
  206.     .if cc
  207.     .elseif cc
  208.     .elseif cc
  209.     .endif
  210.  
  211.     .do
  212.     .enddo
  213.  
  214.     .do
  215.     .while cc
  216.     .enddo
  217.  
  218.  
  219.     .do
  220.     .until cc
  221.     .enddo
  222.  
  223.  
  224.     .do
  225.     .until cc
  226.     .until cc
  227.     .while cc
  228.     .enddo
  229.  
  230.  
  231. Miscellaneous Notes
  232. -------------------
  233.  
  234. APP conditionals may be nested up to 32 levels deep.  If you need to go
  235. deeper (seven or eight seems like the realistic-use upper limit to me), 
  236. change the MAX_NESTING_LEVELS define in app.c.
  237.  
  238. All the APP constructs must be entered in lower case only, and the condition
  239. codes as well.  It would of course be a simple matter to add support for
  240. upper case, but I have yet to feel compelled to do so.
  241.  
  242. Note that the functions provided by APP could have been done by assembler
  243. macros if the Aztec assembler had supported the ability to expand a macro
  244. with an argument being the *value* of a SET variable, had string variables 
  245. or the ability to concatenate text with a SET variable -- it doesn't.
  246.  
  247. Note also that APP doesn't check condition codes for validity unless their
  248. sense has to be reversed.  It probably should check them, but invalid ones 
  249. won't get past the assembler in any case.
  250.  
  251. APP is so vanilla in its construction that it should run on about any
  252. machine with a C compiler and a stdio library.  It for sure runs under
  253. Aztec C on the Amiga and on Intel '286 Multibus Xenix (don't ask why).
  254.  
  255. The documentation was significantly more work than the code.
  256.  
  257. Warm Regards,
  258. Karl @ The Alternate Hacker's Haven -- Houston, TX, 12/11/88
  259. usenet: uunet!sugar!karl  internet: karl@sugar.uu.net   bix: kelehen
  260.