home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / ENTERPRS / CPM / UTILS / S / Z80ASM24.ZIP / Z80ASM24.DOC < prev   
Text File  |  1991-10-06  |  18KB  |  530 lines
  1. Z80ASM-DD 24 --->  Fixes to Z80ASM-20       09/12/87
  2.  
  3.  
  4.          <<<   Z80ASM24.DOC   >>>
  5.  
  6.  
  7. by Dianna Dearborn     September 12,1987
  8.  
  9.  
  10. This document outlines a number of fixes and enhancements to Z80ASM 2.0
  11. and identifies remaining the bugs that I'm aware of.
  12.  
  13. FIXES:
  14. -----
  15. -in JR and DJNZ relative addressing instruction operands to allow the
  16.  use of symbolic label references
  17.  
  18. -in JR and DJNZ instructions to allow the use of the $ symbol to repre-
  19.  sent current reference counter value.
  20.  
  21. -in the LABEL: character validation test to allow the use of the $ symbol
  22.  in labels
  23.  
  24. -in valid label test and error reporting routine
  25.  
  26. -in the "IBM" pseudo-op
  27.  
  28.  
  29. ENHANCEMENTS:
  30. ------------
  31. -in JR and DJNZ instructions, a displacement range test was added to trap
  32.  operand expression which evaluated outside the -126 to +129 byte limits.
  33.  
  34. -a routine was added to eliminate the initial page eject on the listing
  35.  output
  36.  
  37.  
  38. REMAINING BUGS:
  39. --------------
  40. -in reserved word test for LABELS:
  41.  
  42. -in the reference value of the last LABEL: used in a source file.
  43.  
  44. OTHER:
  45.  
  46. -a discussion is included on some of the syntax rules of Z80ASM discover-
  47.  ed along the way
  48.  
  49.  
  50. BACKGROUND:
  51. ----------
  52.      Some weeks ago, I started to do some serious Z80 assembly language
  53. programming.  I downloaded a copy of Z80ASM from a RCPM and started to
  54. write code.  My programs crashed immediately.
  55.  
  56.      First thing that happened was the assembler got caught in an
  57.  
  58.  
  59.  
  60.  
  61.     5
  62.  
  63.  
  64.  
  65.  
  66.  
  67. Z80ASM-DD 24 --->  Fixes to Z80ASM-20       09/12/87
  68.  
  69.  
  70. infinite loop and hung up.  I narrowed that down to the use of a dollar
  71. $ign in label names.
  72.  
  73.      Second, there was a bug when using the dollar $ign symbol convention
  74. to indicate the current value of the reference counter in operand expres-
  75. sions in JR and DJNZ relative addressing instructions i.e., "JR $+12H";
  76. it worked as expected in JP and CALL instructions.  I found that using
  77.  "JR +12H"  would work.
  78.  
  79.      Finally,  using LABELS: in the operands of JR as DJNZ instructions
  80. crashed i.e., JR    LOOP.  Again, they worked with JP and CALL operands.
  81. I found no way around this bug.  I was left with the choice of either
  82. counting the number of bytes of intervening instructions to calculate
  83. the relative offsets (too much work, prone to error and difficult to
  84. modify) or using only JP instructions. Neither was acceptable, so I
  85. started to debug the assembler.
  86.  
  87.  
  88. THE BUGS AND THE FIXES:
  89. ----------------------
  90.      $ in LABLE$: was indeed an infinite loop probably caused by a typo
  91. in the original source code.  The fix was simply to patch in the proper
  92. address in the JP instruction.
  93.  
  94.      Relative displacement errors were caused by a complete lapse of
  95. thought in the mind of the programmer. While evaluating the operand
  96. expressions, JP and CALL instructions create a two byte operand that is
  97. the absolute destination address of the jump.  Z80ASM handles them by
  98. getting the reference counter of the current instruction, in the case of
  99. "JP  $+12H", and adding to it the value of the expression, and in the
  100. case of "JP  LABEL:", by getting the address of the label from the symbol
  101. table and placing it in the operand.  Both methods are combined in such
  102. instructions as "JP  LABEL:+12H".
  103.  
  104.      JR and DJNZ relative addressing instructions were handled in the
  105. same manor by the same routine as the absolute addressing instructions
  106. and the seemingly random displacement values in their operands turned
  107. out to be the low byte of the absolute address of the instruction's
  108. destination.  Relative addressing instructions require that the signed
  109. DIFFERENCE between the current address and the destination address be
  110. placed in the operand which will then be added to the PROGRAM COUNTER of
  111. the Z80 prior to the jump.  To accomplish this, I had to add code to
  112. Z80ASM.
  113.  
  114.      After fixing these three bugs, I found that there was, of course,
  115. no trap for displacement range errors. This creates the possibility of
  116. writing an operand expression that evaluates out of range but looks cor-
  117. rect upon cursory examination and then sends your program to never-never
  118. land.  These errors can be quite difficult to detect.  I added a range
  119. test that is performed after the evaluation of the operand expression
  120. and used the $ symbol, appropriately enough, to flag assembly listing
  121. lines with range errors then forced the operand to 00.
  122.  
  123.  
  124.  
  125.  
  126.  
  127.     6
  128.  
  129.  
  130.  
  131.  
  132.  
  133. Z80ASM-DD 24 --->  Fixes to Z80ASM-20       09/12/87
  134.  
  135.  
  136.      Along the way I discovered that the reserved word and valid label
  137. length tests did not seem to work.  The labels were only tested on the
  138. first pass to validate them before putting them into the symbol table
  139. but the results were not saved for the second pass.  I changed the rou-
  140. tine so that now at least the label length is tested on the second pass
  141. and the results are passed on to the listing, however, using a reserved
  142. word or defining a label twice will still cause your program to crash
  143. without warning you of the error.
  144.  
  145.      What actually happens is that on the first pass when a reserved
  146. word or redefined label is detected, the label is not added to the symbol
  147. table and the reference counter is not updated.  On the second pass, the
  148. error goes undetected, the op code and operand are evaluated, the refer-
  149. ence counter is updated and all symbolic addresses from the line in error
  150. are off by the number of bytes in the op code of the error line.  I
  151. thought about disabling the test altogether, however, this type of error
  152. is easier to detect than one line with a reserved word where it doesn't
  153. belong because every symbolic reference pass the bad line points to a
  154. wrong address. The fix is messy and I need to get on with my project so
  155. I'll save this one for another day -- at least you were warned!!
  156.  
  157.      The other remaining label error has to do with the last label used
  158. in the assembly.  For some reason, the reference address (or EQUate
  159. value) of the last entry in the symbol table gets trashed and, when re-
  160. ferenced, will give erroneous results. The way around that is to make
  161. sure that the last label used does not get referenced. I do this by
  162. labeling the 'END' statement.  My last line in the assembly is usually:
  163.  
  164.         THEEND END    100H
  165.  
  166.      Again, I'll fix this bug when I get more time to work on it.
  167.  
  168.      While plowing through the Z80ASM code I found a (new to me) pseudo-
  169. op called "IBM".  It turned out to be an ASCII $tring formating in-
  170. struction for messages.  The routine had three major bugs and I'm certain
  171. that it was never tested after it was written. I sorted it out to what
  172. I think the programmer had in mind.  Anyhow, it now works according to
  173. the syntax rules discussed below.
  174.  
  175.      And, lastly, the initial page eject for the listing was a real irri-
  176. tation to me.  I tested for page 1 and skipped the form feed in the
  177. header.  The page number is stored as one byte of two BCD digits (maximum
  178. of 99) and "rolls over" at page 100 to 00.  If your program is more than
  179. 100 pages long, then page 101 will not eject but page 102 will catch up.
  180. This is untested and probably will remain so.
  181.  
  182.      Principally, I tried to keep Z80ASM intact as much as possible.  In
  183. some places, I corrected the original code without altering the rest of
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.     7
  194.  
  195.  
  196.  
  197.  
  198.  
  199. Z80ASM-DD 24 --->  Fixes to Z80ASM-20       09/12/87
  200.  
  201.  
  202. the routine. In the label routine, I altered the order of routine and
  203. changed only the JP addresses. The rest of the changes required the ad-
  204. dition of new code.  To make room for the new code, I moved the main
  205. look-up table at the end of the program to higher memory, staying within
  206. the last page, and added the new routines to the end of the program.
  207.  
  208.  
  209. TESTING:
  210. -------
  211.      I've tried to test Z80ASM thoroughly with benchmark programs and
  212. others that I've written, however, I am sure that the original programmer
  213.  
  214. thought he (she?) did also -- at least well enough to write a bigger and
  215. better assembler.  So help me. Run the assembler on some of your succes-
  216. sful programs and compare them.  If there is any bugs, please let me
  217. know.  I'll try to fix all of the real ones.
  218.  
  219.  
  220. EPILOG:
  221. ------
  222.      This was fun for me (she's crazy!!).  I didn't know the insides of
  223. assemblers before I started and now I have an appreciation for both as-
  224. semblers in general and, particularly, the work of 'LCS' -- I learned a
  225. lot!  I suppose the ultimate irony, after all this work, would be someone
  226. telling me that there is a more effecient, fully featured, bug-free as-
  227. sembler readily available in the public domain!!
  228.  
  229.      I have one more feature to add when I have time -- I feel lost with-
  230. out a symbol table so I'll dump that to the listing some day.  The way I
  231. get around that now is call DDT with a null program and check out the
  232. symbol table left in memory starting at 22A2H.
  233.  
  234.      About the version number, I worked it up to 24 to keep track of my
  235. work and, vainly enough, added my initials to easily identify this ver-
  236. sion with the fixes from any others in RCPM land.
  237.  
  238.      From the skeletons left in the code, it's become obvious that other
  239. features were planned for Z80ASM but never implemented.  Maybe I'll work
  240. on them some day.  Perhaps add a routine to allow lower case alpha en-
  241. closed in quotes.  If you have any ideas for new features or know of
  242. other bugs, please share them with me and I'll see what I can do.
  243.  
  244.      I'd like to hear from any users of this version -- tell me about
  245. your experiences, both the good and the bad.  Send E-mail to:
  246.  
  247.         Diamma Dearborn
  248.         Data Tech RCPM  408-238-9621.
  249.         San Jose, CA.
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.     8
  260.  
  261.  
  262.  
  263.  
  264.  
  265. Z80ASM-DD 24 --->  Fixes to Z80ASM-20       09/12/87
  266.  
  267.  
  268.   NOTES ON SYNTAX FOR Z80ASM-DD 2.4
  269.  
  270. DISCRIPTION OF Z80ASM:
  271. ---------------------
  272. Z80ASM is a two-pass assembler.  The first-pass creates the symbol table
  273. and the second pass does the assembly. The assembler accepts as input
  274. an <filename>.ASM source file written in ZILOG assembly language and out-
  275. uts both an Intel formatted
  276. <filename.HEX> object file and an assembly listing to the printer in
  277. realtime, either of which may be disabled.  This assembler does not
  278. create any intermediate files, <filename.PRN> or <filename.SYM> files.
  279.  
  280. The symbol table is created starting at 22A2H and may be expanded up to
  281. CCP base without harm. There is no trap for symbol tables that overwrite
  282. CCP.  The maximum number of symbolic entries is dependent on the memory
  283. available with the system configuration and the aggregate length of each
  284. symbol plus 4 bytes per symbol.
  285.  
  286. All program I/O is done through FDOS calls to 0005H.  All read, write and
  287. working buffers, except the symbol table, are internal to the program.
  288. This assembler was written in 8080 assembly language probably as a boot-
  289. strap to writing a more effecient and fully featured Z80 assembler.
  290.  
  291.  
  292. INVOKING Z80ASM:
  293. ----------------
  294. The format is:
  295.  
  296.    A>Z80ASM <filename>[.LH ]
  297.  
  298. The assembler expects an input source file named <filename>.ASM.  The
  299. optional .LH extension is the (L)isting output and (H)ex file output de-
  300. feat option mechanism. The true state of the option (defeated) is in-
  301. voked by typing 'N' in the appropriate location, any other character
  302. enables the function.  Without the extension both Listing output and .HEX
  303. file output functions are enabled.  When the listing function is dis-
  304. abled, only assembly line errors will be listed.  For example:
  305.  
  306.      <filename>.N     will disable the listing function but
  307.          create a <filename>.HEX file as output.
  308.      <filename>.xN    will disable the .HEX file output but
  309.          a listing is printed.  Where x is any
  310.          permissible CP/M .typ char except a space
  311.  
  312.  
  313. SOURCE CODE FILE LIMITATIONS:
  314. ----------------------------
  315. Source code files may be of any length acceptable to CP/M, however, there
  316. is a practical limit to the size of the symbol table which is not written
  317. to a file but held in memory between 22A2H and CCP base.
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.     1
  326.  
  327.  
  328.  
  329.  
  330.  
  331. Z80ASM-DD 24 --->  Fixes to Z80ASM-20       09/12/87
  332.  
  333.  
  334. SOURCE CODE LINES:
  335. -----------------
  336. Source code lines may not exceed 80 characters including CR & LF and
  337. must be terminated by LF (0AH).  Most routines test for CR to exit.
  338.  
  339.  
  340. LOWER/UPPER CASE TRANSLATION:
  341. ----------------------------
  342. Presently, ALL lower case ascii characters are translated to upper case,
  343. including strings enclosed by single quote marks.
  344.  
  345.  
  346. OPCODES AND OPERANDS:
  347. --------------------
  348. Opcodes may NOT start in column 1.  Opcodes and their operands follow the
  349. rules established by Zilog in the Z80-Assembly Language Programming Man-
  350. ual.
  351.  
  352.  
  353. RESERVED WORDS:
  354. --------------
  355. Certain symbolic names are reserved as key words in the operand fields.
  356. They are:
  357.  
  358. Register names:   A, B, C, D, E, H, L, AF, BC, DE, HL, AF'
  359. Flag Conditions:  C, NC, Z, NZ, M, P, PO, PE
  360.  
  361. Using a reserved word as a smybolic reference in the operand field will
  362. give erroneous operand values.
  363.  
  364.  
  365. EXPRESSIONS:
  366. -----------
  367. Expressions are operand entries and may be unary (single term) or binary.
  368. Elements of the expression are connected by the arithmetic operators +
  369. (addition), - (subtraction) , and  * (multiplication).
  370.  
  371. Expression elements may be numbers which begin with a numeric digit,
  372. symbolic references which begin with an alpha charater (LABELS: and
  373. EQUates), $ symbol for the current value of the reference counter and a
  374. single ASCII character enclosed in single quote marks which equates to a
  375. hexadecimal number.  Expressions are terminated by any other characters,
  376. usually a space or comma.
  377.  
  378. Expressions are evaluated from left to right, parentheses are not per-
  379. mitted.  Expression evaluation results are limited to 2 bytes (16 bits)
  380. in length with a maximum unsigned value of 65,535.
  381.  
  382.  
  383. NUMBERS:
  384. -------
  385. Numbers MUST begin with a numeric digit, leading zeroes will suffice.
  386. Numbers may be written in hexadecimal, decimal or binary bases.  Hexa-
  387. decimal numbers must be followed immediately by the 'H' radix indicator.
  388. Binary numbers must be followed immediately by the 'B' radix indicator.
  389. Decimal numbers are not followed by a radix letter indicator.
  390.  
  391.     2
  392.  
  393.  
  394.  
  395.  
  396.  
  397. Z80ASM-DD 24 --->  Fixes to Z80ASM-20       09/12/87
  398.  
  399.  
  400. LABELS:
  401. ------
  402. Labels MUST start in column 1. A label is a string of one or more char-
  403. acters and must begin with an alpha character. Valid characters are A-Z,
  404. 0-9, $, period (.) and trailing colon (:).  Labels are terminated by any
  405. other character, usually a space or comma.  Labels may be up to 11 char-
  406. acters in length (excluding colons), all characters are unique.  Trailing
  407. colons are optional and ignored by the assembler i.e., LABELS: = LABELS.
  408. Examples of valid labels are:
  409.  
  410.      LABEL     LABEL:  LABEL$    LONG.LABEL   LONGERLABEL
  411.  
  412.      WARNING: at present the reserved word trap does not work.
  413.      An opcode or reserved word in an expression or starting in
  414.      column 1 will cause your program to crash!  Also, the last
  415.      label stored in the symbol table will give erroneous values,
  416.      therefore, DO NOT reference the last label in the body of a
  417.      program.
  418.  
  419.  
  420. PSEUDO-OPS:
  421. ----------
  422. Pseudo-ops are instructions to the assembler and as such do not generate
  423. object code.  Psuedo-ops are summerized below:
  424.  
  425.      ORG  e     Sets the reference counter to the value of
  426.       expression e.
  427.  
  428.      EQU  e     Sets the value of a label to e.  Can occur
  429.       only once per label.
  430.  
  431.      END   e     Signifies the end of source code -- all code
  432.       after END is ignored.  Expression e evaluates
  433.       to the program starting address for .HEX
  434.       files loaded with LOAD (e = 100H is normal)
  435.  
  436.      EJECT     Forces a new page in listing.
  437.  
  438.      DEFS e     Reserves e bytes of memory.  Advances
  439.       reference counter RC = RC + e.
  440.  
  441.      DEFB e     Defines one byte of memory to equal value e.
  442.  
  443.      DEFB '$tring'  Defines n bytes of memory as the ascii
  444.       equivalent of the characters in the $tring
  445.       enclosed by single quote marks. n
  446.       equals the number of chars in the string.
  447.  
  448.      DEFW e     Defines two bytes of memory to be equal to
  449.       the value of e.  e is stored in memory as low
  450.       byte -- high byte, ie., CRLF  EQU 0D0AH...
  451.       DEFW   CRLF... produces 0A, 0D in consecutive
  452.       bytes of memory.
  453.  
  454.  
  455.  
  456.  
  457.     3
  458.  
  459.  
  460.  
  461.  
  462.  
  463. Z80ASM-DD 24 --->  Fixes to Z80ASM-20       09/12/87
  464.  
  465.  
  466.      IBM  e     Defines n bytes of memory as the hex equiva-
  467.       lent of the ascii elements in the expression
  468.       e where n is the number of elements and takes
  469.       the form:
  470.  
  471.     IBM  c1,c2,'$tring',c3,...,cn
  472.  
  473.       where values of c are the hex representation
  474.       of ascii characters without base indicator
  475.       (H) and elements are seperated by a comma.
  476.       Strings are enclosed by single quotes and
  477.       each character of a string is considred an
  478.       element. Single quotes may be included by
  479.       defining cx = 27 (H).  Symbolic equivalents
  480.       are not allowed (ie., CR  EQU  0DH...IBM
  481.       CR,..).  e is terminated by a CR.  Usage
  482.       example, a $ terminated message:
  483.  
  484.     IBM    0D,0A,'MESSAGE',0D,0A,'$'
  485.  
  486.    where e is an expression as defined above.
  487.  
  488. MACRO, CONDitional, EXTERNAL and GLOBAL pseudo-ops and LOGICAL
  489. operators are not implemented in this version of Z80ASM.
  490.  
  491.  
  492. COMMENT LINES:
  493. -------------
  494. Comment lines are defined as any string following a semicolon (;) in a
  495. line.  Comments may start in any column and are ignored by the assembler.
  496.  
  497.  
  498. ASSEMBLER ERROR MESSAGES:
  499. ------------------------
  500. Assembly error messages are one character codes which are placed in the
  501. first column of the line containing the error in the output listing.
  502.  
  503.  L    Label length error -- label > 11 characters long
  504.  
  505.  M    Label is either a reserved word or previously defined (not
  506.   implemented in version 2.4)
  507.  
  508.  O    "Overflow" -- indicates that the op code as spelled was
  509.   not found in reference table.
  510.  
  511.  U    Undefined label in the operand field
  512.  
  513.  $    Displacement range error -- range = -127 < expression <+130
  514.  
  515.      - Dianna Dearborn
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.     4
  524.  
  525.  
  526.  
  527.  
  528.  
  529. 
  530.