home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / utils / asmutl / ucasm.lbr / UCASM.DZC / UCASM.DOC
Encoding:
Text File  |  1988-01-08  |  10.8 KB  |  219 lines
  1.  
  2. UCASM Micro-controller Assembler - copyright (c) 1987,1988 by J. L. Post
  3. Version 1.2 - Dec 21, 87.
  4.  
  5.  
  6.    UCASM is a CP/M (Z80 only) assembler for the 80xx series of micro-
  7. controller chips.  Controllers supported are the 8021 (subset), 8035,
  8. 8039, 8040, 8041, 8042, 8048, 8049, 8050, 8741, 8742, and 8748 (whew!).
  9. Release 1.2 is a very plain vanilla assembler, but it gets the job done.
  10. Other programmers are encouraged to add some bells and whistles.
  11.  
  12.    I request that anyone wishing to make additions or corrections to the
  13. source code first submit them to me.  Hopefully many changes from dif-
  14. ferent sources can be included in one update and avoid the problem of
  15. umpteen versions floating around on various bulletin boards.  Submit
  16. changes directly to me at 22726 Benner Ave, Torrance, CA 90505.  Log re-
  17. cords of included changes will be put in the source code for subsequent
  18. releases.
  19.  
  20.    There are several "features" of UCASM that were done the way they
  21. were for the sake of speed of execution, efficiency, or just plain lazi-
  22. ness.  Those that exist for one of the first two reasons should not be
  23. changed.
  24.  
  25.  
  26. Legal BS for the Lawyers:
  27. -------------------------
  28.    While the source code and object code for UCASM has been made avail-
  29. able for free, this in no way invalidates my copyright.  Feel free to
  30. pass it around or modify it in any way you see fit.  The one thing you
  31. cannot do is sell it.  Doing this would upset me greatly, to the point
  32. where I would feel obligated to cause you all kinds of legal difficul-
  33. ties and/or grief. UCASM is released to the public domain for personal
  34. use.  Using it for business purposes is tantamount to selling it.
  35.  
  36.    This software is released without warranty.    The author assumes no
  37. responsibility with respect to any liability, loss, or damage caused or
  38. alleged to be caused directly or indirectly by this software,including,
  39. but not limited to, any interruption of service, loss of business or
  40. anticipatory profits or indirect, special, or consequential damages.  So
  41. there.
  42.  
  43.    UCASM is my own creation, and any credit or blame lies solely with
  44. me.  I would like, however, to acknowledge the influence of Michael G.
  45. Lehman's Z80ASM. In particular, the expression evaluator was largely
  46. patterned after the one in Z80ASM. Thank you, Michael.
  47.  
  48.  
  49. Things Intentionally Left Out:
  50. ------------------------------
  51.    There is no PAGE or EJECT pseudo-op and I would prefer that no one
  52. add one.  This kind of nonsense wastes paper, and paper comes from
  53. trees.    I happen to like trees very much.  If you get a yen to add such
  54. a ridiculous function, consider that many people other than yourself may
  55. use it and how many trees will be killed in the long run.  Be nice to
  56. the world; it's the only one we've got.
  57.  
  58.    There is no END pseudo-op.  Any programmer who can't tell that he has
  59. reached the end of the file should consider going into plumbing or
  60. bricklaying.  Programming is apparently too difficult for him or her.
  61. If you haven't noticed by now, I'm very opinionated, and I will express
  62. my opinions in this document.  If you can't stand the heat......
  63.  
  64.    There are no macros and I don't want any.  Macros are for dummies.
  65. Contrary to popular opinion, I think that macros make the code MORE ob-
  66. scure.    If you need to have a section of code that can accept varying
  67. parameters as inputs, write an intelligent subroutine.    See above com-
  68. ments about optional career choices.
  69.  
  70.    There is no INCLUDE statement.  The 80xx series of micro-controllers
  71. have a small amount of ROM available and there is no reason why all of
  72. the source code won't fit into one file (unless you have a thing about
  73. going overboard with comments).  If you have a common subroutine library
  74. that you want to use in various and sundry applications, PIP it into a
  75. new file and add your application code to it.  Even I'm not that lazy.
  76.  
  77.  
  78. General Features of UCASM:
  79. --------------------------
  80.    UCASM creates .HEX and/or .LST files from your .ASM source file.  Al-
  81. though it is a two-pass assembler, the source file is read into memory
  82. only once.  This is done for the sake of sheer, unadulterated, raw speed.
  83. Therefore you must have enough memory in your system to hold both the
  84. source code and the symbol table, plus hex and list output buffers.  For
  85. all but the smallest systems, this should not be a problem.  Note that
  86. UCASM makes no check for the size of available memory, it just eats up
  87. what it needs.    As long as you have a full 64K of memory and you don't
  88. get crazy with comments in your source file, this should not be a prob-
  89. lem.
  90.  
  91.    There is not a typical parser in UCASM.  Input lines are parsed "on
  92. the fly".  This was not done because it seemed like a good idea, but
  93. simply because it was easier to implement.  Someone may wish to add a
  94. real parser.  Some more or less obvious advantages would result.  Good
  95. luck if you want to attempt this.
  96.  
  97.  
  98. The Good Stuff:
  99. ---------------
  100.    To invoke the assembler, type:
  101.  
  102.         UCASM filename<.typ> <hl>
  103.  
  104. at the CP/M prompt.  If no file type for the source file is specified,
  105. .Z80 is assumed.  If no options are specified, no output file will be
  106. created; the assembler will just assemble the source code and report any
  107. errors on the console.    The option 'H' will cause a .HEX output file to
  108. be created, and the option 'L' will cause the creation of a listing file.
  109. The output files will have the same filename as the source file, but with
  110. the extensions .HEX and .LST respectively.
  111.  
  112.    Valid pseudo-ops are EQU, ORG, DEFB, DEFW, and DEFS.  These are the
  113. minimum that any assembler needs.  Actually, DEFS isn't really needed.
  114. If there is enough interest, future releases may contain LIST, NOLIST,
  115. PHASE, DEPHASE, and any others that might be suggested.  As mentioned
  116. above, EJECT (PAGE) and END are intentionally not present.
  117.  
  118.    Valid expression operators are addition (+), subtraction (-), multi-
  119. plication (*), division (/), logical and (&), logical or (%), exclusive
  120. or (!), shift left (<), shift right (>), and control character defini-
  121. tion (^).  More may be added in future releases.  Expression evaluation
  122. is strictly left to right.  Parentheses will not only not give you what
  123. you expect, they will cause termination of the expression evaluation.
  124. Here is obvious room for improvement.  Source code (but not comments)
  125. must be in upper case.
  126.  
  127.  
  128. Things That Go Bump in the Night:
  129. ---------------------------------
  130.  o  Labels, mnemonic names, and pseudo-ops are currently limited to six
  131.     valid characters.  This may change in future releases.    As of
  132.     version 1.2, labels will be truncated to six characters when
  133.     they are defined.  However, reference to that label elsewhere
  134.     will always cause an undefined operand error.  Labels must con-
  135.     sist of alphanumeric characters only (A-Z, 0-9).
  136.  o  An exceptionally long source file with gobs of labels might cause
  137.     UCASM to eat up critical parts of the operating system.  Checks
  138.     to prevent this may be put in future releases, but then again
  139.     may not.  What kind of micro-controller program are you assem-
  140.     bling that requires such a long source file?
  141.  o  Not all operands are fully checked for validity.  As an example, the
  142.     EN opcode has only two valid operands, I and TCNTI. Only the
  143.     first character of these operands is checked.  Therefore EN IDIOT
  144.     will be correctly assembled as if it were EN I with no visible
  145.     error.    I assume you know what you're doing.
  146.  o  Fields in the input line are defined by tabs or spaces.  Lines with-
  147.     out labels must start with a space or a tab, otherwise the as-
  148.     sembler will define your mnemonic as if it were a label with
  149.     predictable and disastrous results.  Operands may be separated
  150.     from their opcodes by a space instead of a tab.  I think the
  151.     source code looks prettier if the operand is in a separate col-
  152.     umn, but there is no valid reason why it must be.  Suit yourself.
  153.  o  I assume nothing about your printer.  Tabs in the source code will
  154.     be expanded with spaces in the listing file.  If your operating
  155.     system is capable of skipping over the perforations on your
  156.     printer, then set the page length defaults to zero, otherwise
  157.     line feeds will be inserted in the output stream to simulate a
  158.     form feed at the end of a page.  Line widths are truncated at 80
  159.     characters.
  160.  o  No headers are put in the listing file. I think that this practice
  161.     is a result of the ego of the programmer and/or company market-
  162.     ing the assembler.  I personally detest it and usually write
  163.     printing utilities (filters) to remove this junk from the list-^
  164.     ing file as it's being printed.
  165.  o  While the source file is read only once and kept in memory to speed
  166.     execution of the program, the output files are not buffered but
  167.     are written to disk as each record (128 bytes) is available.
  168.     This is a good idea as far as the listing file is concerned,
  169.     since to do otherwise would effectively more than double the
  170.     memory requirements.  The hex output data could however be kept
  171.     in memory until the entire file is assembled and only then writ-
  172.     ten out to disk.  This would up the throughput and would not
  173.     need all that much more memory.  A suggestion to those who would
  174.     like to add to the effort.
  175. o  The DEFW pseudo-op will currently allow only one operand.  Hopefully
  176.     this limitation will be removed in the next release.  This
  177.     'drawback' also applies to the DEFS pseudo-op.    The DEFB pseudo-
  178.     op should be used in place of DEFM (which doesn't exist), as in
  179.     DEFB 'Hi there'.  Multiple operands are allowed with DEFB
  180.     (example:  DEFB 12, 'test', 84H).
  181.  
  182.  
  183. Summary:
  184. --------
  185. Pseudo-ops are: EQU as in    LABEL:    EQU    123
  186.         ORG as in        ORG    100H
  187.         DEFB or DB as in    DEFB    'A'+1
  188.         DEFW or DW as in    DEFW    STACK*2
  189.         DEFS or DS as in    DEFS    LENGTH & 0FFH
  190.  
  191. Expression operators are:
  192.     +  addition        -  subtraction
  193.     *  multiplication    /  divison
  194.     &  logical and        %  logical or
  195.     !  exclusive or     <  shift left
  196.     >  shift right        ^  control character
  197.  
  198.    The control character operator can be used with EQU or DEFB as in
  199.  NTRLC    EQU  ^C    (equivalent to CNTRLC  EQU  3).
  200.  
  201.    Note that operators and values may or may not be separated from each
  202. other by spaces.  A way around the strict left to right evaluation of
  203. expressions is to use something like:
  204.  
  205. TEMP:    EQU    THAT/2
  206. VAL:    EQU    THIS+TEMP
  207.  
  208. to get the equivalent of  VAL:      EQU      THIS+(THAT/2)
  209.  
  210.    Please direct any comments, complaints, suggestions, additions,
  211. deletions, changes, or diatribes of any kind to me at the address given
  212. above.    Useful alterations will be included in future updates, polite
  213. questions will be answered as promptly as possible, and abusive or
  214. obnoxious suggestions will produce a good laugh but will otherwise be
  215. ignored.  Above all, do not bug your BBS sysop about this software.
  216.  
  217.                     - Jeffery L. Post
  218.  
  219.