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