home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / mbug / mbug078.arc / README.21 < prev    next >
Text File  |  1979-12-31  |  11KB  |  265 lines
  1.  
  2.  
  3.  
  4.                          January 11, 1986
  5. This is the READ-ME file from the Z80DIS.LBR package, version 2.1
  6. -----------------------------------------------------------------
  7.  
  8. Version 2.1 change note:
  9.  
  10.      Version 2.0 added artificial intelligence to Z80DIS.
  11.  
  12.      Version  2.1 corrects a small bug in the processing of  INC,
  13.      DEC,  and    LD using index registers IX and IY.  Version  2.1
  14.      also  significantly enhances the abilities of the    disassem-
  15.      bler  to  distinguish between ASCII blank (20 hex)  and  the
  16.      instruction  "JR NZ,xxxx" (also 20 hex) which leads to  lots
  17.      and lots of phony instruction jump references.  Version  2.0
  18.      worked well in determination of correct break types for 8080
  19.      code.  With version 2.1,  you now have that reliability with
  20.      Z80 code as well.
  21.  
  22. Z80DIS    is  an entirely new disassembler for Z80 based CP/M  sys-
  23. tems.    Z80DIS is written in TURBO PASCAL.  Z80DIS generates  Z80
  24. mnemonics  and prepares an assembly language file with many  spe-
  25. cial  features for ease of understanding the intent of the disas-
  26. sembled code. The source for Z80DIS has grown, with this version,
  27. up to 5800 lines of coding.
  28.  
  29. With versions 2.0 and higher, you need know very little about the
  30. format of the *.COM file to produce a nearly finished source file
  31. in most cases. In addition a large number of convenience features
  32. and defaults have been added that were not present in version  1.
  33. A full synopsis of the versions of the program in current distri-
  34. bution    is included in the Z80DIS20.DOC file.  Highlights of  the
  35. current changes follow at the end of this paper.
  36.  
  37. Both  the  Z80DIS program and the Z80DIS  documentation  are  (C)
  38. Copyright  1985 and 1986 by Kenneth Gielow;  All Rights Reserved.
  39. While  I  am freely distributing the binary code  for  non-profit
  40. use, I am reserving the source code as a trade secret.
  41.  
  42. This  program requires a Z80 based computer running CP/M  version
  43. 2.2  or  higher.  The code was compiled for a 50K  TPA;  the  top
  44. address is C7FF. This slightly small size was done for compatibi-
  45. lity with CP/M 3.0 and ZCPR3.
  46.  
  47. The following files will be found on Z80DIS21.LBR for this  prog-
  48. ram distribution library package:
  49.  
  50.      Z80DIS.COM    - the disassembler program
  51.      Z80DIS.000    - overlay file for Z80DIS
  52.      Z80DIS.001    - overlay file for Z80DIS
  53.  
  54.      ZDINSTAL.COM  - a terminal command installation program
  55.      ZDINSTAL.MSG  - contains text of ZDINSTAL messages
  56.      ZDINSTAL.DTA  - contains terminal characteristics data
  57.  
  58.      Z80DIS20.DOC  - an abbreviated user manual in ready to print
  59.                format. (See documentation notice )
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67. Z80DIS 2.1                         01/11/86
  68.  
  69.  
  70. The Z80DIS binary is in three files. The ZDINSTAL files are based
  71. on  the TURBO Toolbox GINST program and will tailor the  interac-
  72. tive displays to your terminal.
  73.  
  74. The  program  is easy to use with interactive displays for  para-
  75. meter specification.  All control parameters have defaults preset
  76. to  the most likely values.  The DOC file is the text of a  short
  77. user manual which explains most of the important points needed to
  78. get going.
  79.               DOCUMENTATION NOTICE
  80.               --------------------
  81. The original, forty-plus page user manual gave extensive examples
  82. and  used  disassembly of the public domain program D.COM  as  an
  83. example.  Unfortunately, with the additions to document the newer
  84. features  and  give additional suggestions  for  use,  that  user
  85. manual     and expanded program together have both gotten so  large
  86. that  most system operators would not carry the complete library.
  87. Something  had to give.  I feel that the program is largely  self
  88. explanatory  so  that you can get started very well with  only    a
  89. shortened manual.  This abbreviated manual is included here.  The
  90. short user manual deals mainly with installing the Z80DIS program
  91. and doing a simple disassembly.  This short manual is all that    a
  92. casual user would probably need.
  93.  
  94. The  longer manual expands on the discussion of the features  and
  95. explains  the  step-wise  approach to dealing  with  much  larger
  96. source codes. The manual also deals with disassembling code which
  97. relocates  itself.  Extensive  examples are included.  All  error
  98. messages and secondary options are discussed in detail.
  99.  
  100. The full Z80DIS USER MANUAL is available by mail.  I am asking    a
  101. nominal  charge  of $ 20.00 which includes the    manual,  postage,
  102. handling, and an update notification service. You are granted the
  103. right  to make not-for-profit copies of the manual.  The  program
  104. itself    is  not  available by mail as I do  not  have  extensive,
  105. multi-format disk copy capability.  The notification service will
  106. consist  of a letter to you anytime a new version is released  so
  107. that you may be on the lookout for it.
  108.  
  109. To  order a copy of the Z80DIS USER MANUAL,  send a request  with
  110. your name, address, and a check for $ 20.00 to --
  111.  
  112.       Kenneth Gielow
  113.       79 Tulip Lane
  114.       Palo Alto, CA  94303
  115.  
  116. -----------------------------------------------------------------
  117.  
  118.                FEATURES OF Z80DIS
  119.                ------------------
  120. The  major  feature  of Z80DIS is an extensive    analysis  of  the
  121. memory    usage by the program under investigation.  This  analysis
  122. capability  forms the basis for an automatic partitioning of  the
  123. code to generate the break table.  This analysis also produces    a
  124. fully-annotated cross reference of all addresses.
  125.  
  126. A  disassembler  must know whether the bytes are instructions  or
  127.  
  128.  
  129.                 2
  130.  
  131.  
  132.  
  133. Z80DIS 2.1                         01/11/86
  134.  
  135.  
  136. data  in order to proceed.  Z80DIS is the first  disassembler  to
  137. produce  its  own  break table for this  purpose.  Some  previous
  138. programs, such as RESOURCE, have included a search for ASCII text
  139. regions,  but have left the verification and interpretation up to
  140. the  user.  Most other disassemblers are fooled by the    trick  of
  141. adding    nonsense bytes after jumps to cause the analysis to  fall
  142. out of synchronization with instruction code interpretation.
  143.  
  144. Z80DIS    produces an output listing  which itemizes all    addresses
  145. referenced by the code,  distinguishes types of label references,
  146. marks  subroutines  and  jumps and produces an    annotated  cross-
  147. reference.  This listing shows the exact mode of usage for  every
  148. reference:  Jump absolute, Jump relative, Call, Restart, Load 16-
  149. bit,  Store 16-bit, Immediate 16-bit, Load 8-bit, Store 8-bit. In
  150. version  2.1,  this listing also shows the break table region  of
  151. residency  for    each label so that you may inspect the    list  for
  152. inconsistencies.
  153.  
  154.      An  address labeling convention assists in understanding the
  155. assembly  code generated.  Each label generated on  the  assembly
  156. listing  indicates,  by format,  not only the generic type (Jump,
  157. Call, Data, Other) of any references, but also the singularity of
  158. the reference.
  159.  
  160.       For  example,  J#02E3 used at address 02E3  indi-
  161.       cates that only one reference was made to address
  162.       02E3 and that that reference was a JUMP.
  163.  
  164. In  addition to helping you by automatic analysis of memory  use,
  165. Z80DIS also assists you by styling the presentation of the disas-
  166. sembled code.  The disassembled code is output in two forms: Both
  167. the usual *.MAC file and a printer formatted *.PRN file.
  168.  
  169. The *.PRN file is styled to look like the output of an    assembler
  170. with both the instructions and assembled bytes shown.  The juxta-
  171. position  of  the  hexadecimal bytes and the  assembly    mnemonics
  172. allows    the  user to recognize errors caused  by  an  incorrectly
  173. defined break table.
  174.  
  175. -----------------------------------------------------------------
  176.  
  177. A personal note:
  178.  
  179.      I    wrote this disassembler because I could not find  another
  180. that  would  really  open up a foreign    program  for  inspection.
  181. RESOURCE  and  its spin-offs give you only a pin-hole look  at    a
  182. program  without indicating the important interactions with other
  183. parts  of  the code.  Z80DIS rectifies that lack via  the  cross-
  184. reference,  disassembly comments,  and automatic structure analy-
  185. sis. I hope that you will find it as useful as I have.
  186.  
  187.                   Kenneth Gielow
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                 3
  196.  
  197.  
  198.  
  199. Z80DIS 2.1                         01/11/86
  200.  
  201.  
  202.            Significant Changes in Version 2.1
  203.            ----------------------------------
  204.  
  205.      1) BUG CORRECTION:  During automatic break table creation in
  206. version 2.0,  the codes DD34,  DD35,  DD36, FD34, FD35, FD36 were
  207. not  correctly    recognized.  This resulted in  false  assumptions
  208. about  the  legality  of some Z80 code regions    which  were  then
  209. thought to be data regions rather than instruction regions.  This
  210. has been corrected in version 2.1.
  211.  
  212.      2) IMPROVEMENT IN HANDLING JR REFERENCES:    In  disassembling
  213. 8080  coding,  instruction jumps and calls use 3-byte addressing;
  214. that is unambiguous and not easily misinterpreted. With Z80 code,
  215. ASCII text blocks contain codes that are easily mistaken for  Z80
  216. relative  jumps;  that    creates apparent jump references to  code
  217. within    128 bytes before or after the  misinterpreted  byte.  The
  218. ASCII blank (20 hex) is especially bad as it looks exactly like a
  219. "JR NZ,xxxx" code. Version 2.1 has been much improved to distrust
  220. relative  jump references as a basis for declaring a region to be
  221. instructions.  Version    2.1  examines corroborative  evidence  to
  222. distinguish ASCII data from instruction codes.
  223.  
  224.      3) OTHER IMPROVEMENTS:  The entire Expert system  comprising
  225. the Automatic Break Determination feature was enhanced to yield a
  226. more complete analysis of the code structure.
  227.  
  228.           Highlights of Changes in Version 2.0
  229.           ------------------------------------
  230.  
  231.      1) AUTOMATIC BREAK TABLE CREATION: When the program asks for
  232. break  table inputs,  you may now enter '*' which will trigger    a
  233. detailed analysis of the structure and relationships of the input
  234. code.
  235.  
  236.      2) The COM file and overlay files for Z80DIS no longer  need
  237. to be on your default disk drive.
  238.  
  239.      3)  The  cross-reference listing now shows the  break  table
  240. region of residency for each label.
  241.  
  242.      4)  Overflow of memory or disk space during pass 1 will  not
  243. abort execution.
  244.  
  245.      5)  You may now disassemble direct to your printer by speci-
  246. fying LST: as the list file name.
  247.  
  248.      6)  You  may  now suppress creation of either .PRN  or  .MAC
  249. output files.
  250.  
  251.      7) The default name for the break table save file is now the
  252. same name as that of your input file.
  253.  
  254. _________________________________________________________________
  255. CP/M is a registered trademark of Digital Research Inc.,
  256. TURBO PASCAL is a trademark of Borland International,
  257. Z-80 is a trademark of Zilog Corp.
  258.  
  259.  
  260.  
  261.                 4
  262.  
  263.  
  264.  
  265.