home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / lambda / soundpot / a / debug.lbr / DBUGINST.DZC / DBUGINST.DOC
Encoding:
Text File  |  1993-10-26  |  9.3 KB  |  279 lines
  1.                      AMYX DEBUG INSTRUCTIONS
  2.  
  3.  
  4. GENERAL
  5.  
  6. AMYX DEBUG is a debugger for Z80 CP/M that lets you examine and
  7. modify the contents of both the CPU registers and memory, search
  8. memory for specified contents, set breakpoints at specified pro-
  9. gram addresses, and single-step through a program.  You can also
  10. perform hexadecimal addition and subtraction while DEBUG is ac-
  11. tive without affecting either DEBUG or the program being tested.
  12.  
  13. Approximately 3000 bytes long, DEBUG is completely relocatable,
  14. with its highest relocated address determined by the equate REL-
  15. TOP.  If you want to change the location of DEBUG in memory, set
  16. RELTOP as you wish and reassemble.
  17.  
  18. If you are making your first excursions into using a debugger for
  19. assembly programs, you should be aware that while a debugger is a
  20. powerful tool for program testing, it also has the potential to
  21. cause disaster.  With DEBUG, you can absolutely cream your pro-
  22. gram, DEBUG itself, and the operating system.  If you are at all
  23. uncertain about what you're doing, be sure that you have a cur-
  24. rent backup copy of the program you're testing, and, for your
  25. first few attempts, you might want to leave the diskette drive
  26. doors open if your program will allow.
  27.  
  28.  
  29. LOADING DEBUG
  30.  
  31. To load DEBUG into memory, type DEBUG <CR>.  DEBUG will load and
  32. automatically relocate to high memory, then print a confirming
  33. message on the screen.  You should reload DEBUG any time you
  34. leave it to modify your source code or run any other program.
  35.  
  36.  
  37. INVOKING DEBUG
  38.  
  39. DEBUG is invoked by inserting the one-byte instruction RST 38H
  40. into the program being tested where you want DEBUG to become ac-
  41. tive.  Once you are in DEBUG, you can set and clear breakpoints
  42. as you wish without affecting the program addresses.  If you
  43. think you will want to change the place where you initiate DEBUG,
  44. place NOPs in your code where you want the other calls to be.
  45. You can then exchange any NOP for an RST 38H without affecting
  46. subsequent addresses.
  47.  
  48.  
  49.                            THE DISPLAY
  50.  
  51. The upper portion of the display shows the contents of the Z80
  52. registers as indicated.  The hex numbers to the right of the
  53. register contents (to the right of the ->) are the contents of
  54. the memory address in the register and the contents of the fif-
  55. teen next higher addresses.  To the right of the hex display are
  56. the ASCII representations of the hex values.  Hex values below 20
  57. (space) and above 7E (tilde) are shown as periods.
  58.  
  59. The eight characters to the right of the AF and AF' registers
  60. show the status of the flags in the F(lag) register.  A dash in-
  61. dicates a 0 in the F register (no flag set); a letter indicates a
  62. 1 (flag set), as follows:
  63.  
  64.          S (bit 7) Sign
  65.          Z (bit 6) Zero
  66.          x (bit 5) unused
  67.          H (bit 4) Half-carry
  68.          x (bit 3) unused
  69.          P (bit 2) Parity/Overflow
  70.          N (bit 1) Negative
  71.          C (bit 0) Carry
  72.  
  73. (See a Z80 reference book for a full explanation of how the flags
  74. are used and how to interpret their status.)
  75.  
  76. The lower portion of the display shows the contents of one 128-
  77. byte page of memory.
  78.  
  79. The line labeled "Breakpoints:" below the memory display shows
  80. the addresses of breakpoints that are set.  0000 means no break-
  81. point is set.
  82.  
  83. The last line of the display is used for command entry and error
  84. messages.
  85.  
  86.  
  87.                        IMMEDIATE COMMANDS
  88.  
  89. Immediate commands are single-character commands that are acted
  90. upon as soon as their key is pressed.  Immediate command Q, can-
  91. cel command being entered, in always active.  All other immediate
  92. commands are active only when no other command is in progress.
  93.  
  94.  
  95. Q  Cancel (Quit) command being entered
  96.  
  97. Cancels the command being entered, blanks the command line, and
  98. returns the Command? prompt.  Immediate command Q is always
  99. active.
  100.  
  101.  
  102. +  Page memory display forward
  103.  
  104. Moves the page of memory on display forward 128 bytes.  (The +/=
  105. key invokes the command; it's not necessary to shift up for the
  106. +.)
  107.  
  108. -  Page memory display backward
  109.  
  110. Moves the page of memory on display back 128 bytes.
  111.  
  112.  
  113. G  Continue from breakpoint (Go)
  114.  
  115. Continues user program execution beginning at the PC on display.
  116.  
  117.  
  118. O  Single-step
  119.  
  120. Executes the instruction located at the PC on display, then re-
  121. turns to DEBUG.  All CALLs are executed in full.  Single-step
  122. preempts use of the first breakpoint address.
  123.  
  124.  
  125. Z  Clear (Zero) all breakpoints
  126.  
  127. Clears all set breakpoints.  An available breakpoint is indicated
  128. by 0000 in the breakpoint display.
  129.  
  130.  
  131.  
  132.                         REGULAR COMMANDS
  133.  
  134.  
  135. Regular commands require the entry of some kind of data, and are
  136. not acted upon until the carriage return is pressed.  A command
  137. being entered can be cancelled at any time by using the immediate
  138. command Q.
  139.  
  140. All addresses or byte values must be specified in hexadecimal,
  141. and all hex digits must be entered.  Spaces between elements in
  142. regular commands may be used optionally.  The backspace key may
  143. also be used.
  144.  
  145. Command entry error checking is made as follows:
  146.  
  147. Commands are checked for a maximum length of 32 bytes.  If the
  148. maximum length is exceeded, the keyboard beeps and the character
  149. is ignored.
  150.  
  151. The first letter of any command is tested to be sure it is a val-
  152. id command.
  153.  
  154. All characters are tested to be sure they are valid in the com-
  155. mand string:  hex numbers, register indentifiers, +/- arithmetic
  156. operators, and the terminating period.
  157.  
  158. If an incorrect character is entered, the keyboard beeps and the
  159. character is ignored.
  160.  
  161. Command execution error checking is made as follows:
  162.  
  163. Each command is tested to be sure that the correct number of
  164. characters is present (so that you don't miss a byte and inadver-
  165. tently enter an unreasonable address).
  166.  
  167. Command execution errors are indicated by a keyboard beep and the
  168. message "BAD COMMAND!" to the right of the command.  The error
  169. message is held for about three seconds, then the command line is
  170. blanked and the "Command?" prompt is returned.
  171.  
  172. While this level of error checking is by no means foolproof, its
  173. intent is to try to be reasonably sure that typographic errors
  174. won't lead to disaster.
  175.  
  176.  
  177. B AAAA
  178.  
  179. Set breakpoint at address AAAA.  The breakpoint is set in the us-
  180. er program code and the address is shown on the breakpoint dis-
  181. play.  A breakpoint can be set only if there is space for it
  182. (0000 in the breakpoint display); a maximum of six breakpoints
  183. are allowed.  Trying to set a breakpoint when there is no space
  184. will result in a keyboard beep and the message BREAKPOINTS FULL!
  185. Breakpoints remain set until specifically cancelled by the F or Z
  186. commands, or until DEBUG is reloaded.
  187.  
  188.  
  189. D AAAA
  190.  
  191. Display memory at address AAAA.  The page of memory on display is
  192. updated to show AAAA.  Note that AAAA is placed near the middle
  193. of the memory page display so that memory contents below as well
  194. as above AAAA are shown.
  195.  
  196.  
  197. F AAAA
  198.  
  199. Clear (Fix) the breakpoint at AAAA.  The breakpoint at AAAA is
  200. repaired and the breakpoint display is updated to show an avail-
  201. able (0000) breakpoint.  Trying to clear a nonexistent breakpoint
  202. will result in a BAD COMMAND message.
  203.  
  204.  
  205. H BBBB +/- BBBB
  206.  
  207. Perform hexadecimal addition or subtraction.  The arithmetic
  208. takes place as indicated, and the answer remains on display until
  209. any key is pressed.
  210.  
  211.  
  212. J AAAA
  213.  
  214. Jump to address AAAA.  User program execution is recommenced at
  215. address AAAA.
  216.  
  217.  
  218. L SSSS EEEE BB
  219.  
  220. Fill (Load) memory with byte BB starting at address SSSS and end-
  221. ing at address EEEE.  Display does not change.
  222.  
  223.  
  224. M AAAA BB
  225.  
  226. Modify the contents of address AAAA to byte BB.  After the ini-
  227. tial command entry, the memory page display is changed to show
  228. AAAA (as with the command D).  The entry prompt then changes to
  229.  
  230.      Modify:  AAAA
  231.  
  232. where AAAA is the next address; you enter only the new byte val-
  233. ue.  The memory page display is updated as each byte is entered.
  234. This entry loop continues until the Modify command is terminated
  235. by entering a period in place of BB.
  236.  
  237.  
  238. R RP BBBB
  239.  
  240. Replace the contents of register pair RP with bytes BBBB.  The
  241. register pairs are specified as follows:
  242.  
  243.     Regular registers:  AF BC DE HL IX IY SP PC
  244.     Prime registers:    A' B' D' H'
  245.  
  246. The display is rewritten upon entry of new register pair
  247. contents.
  248.  
  249.  
  250. S SSSS EEEE BBBBBBBB.
  251.  
  252. Search memory for string BBBBBBBB starting at address SSSS and
  253. ending at address EEEE.  The length of the search string is lim-
  254. ited by the length of the command buffer (32 characters), so its
  255. maximum length is 11 bytes.  The search string must be terminated
  256. by a period (no period will result in a BAD COMMAND! message).
  257. When the string is found, the memory page on display is changed
  258. to show the find address.  If the string is not found, the key-
  259. board will beep and the message STRING NOT FOUND will be dis-
  260. played in the error message location.
  261.  
  262.  
  263. S.
  264.  
  265. Recommence search starting at the address immediately following
  266. the last find and continuing on to address EEEE.  (S. cannot be
  267. used if any other command has been issued following the initia-
  268. tion of a search.)
  269.  
  270. T SSSS EEEE DDDD
  271.  
  272. Move (Transfer) the memory contents starting at address SSSS and
  273. ending at address EEEE to destination DDDD.  The display does not
  274. change.
  275.  
  276.  
  277.                                ###
  278.  
  279.