NAS-DEBUG V3.1 -------------- Introduction ------------ Debug provides facilities which simplifies the writing and debugging of machine code programs. It is 1K in length and works together with the Nas-sys monitor and disassembler Nas-dis. The main feature of Debug is a comprehensive single step display that automatically replaces the Nas-sys display. This may be used with an alternative CRT page allowing single stepping of programs that use the CRT screen. All Z80 registers including the alternate set and the IFF2 flip flop are displayed. The mnemonic for the next instruction is displayed next to the program counter and the six main registers pairs have ten consecutive memory locations displayed next to them. The fifth byte is the one pointed to by the register. Editing the display using Nas-sys cursor control facilities allows memory loactions and register values to altered at will. Debug also provides a FIND command that allows memory to be searched for a string of up to 8 bytes. The bytes may be specified in ASCII or HEX form or as "wild" bytes. If the specified string is found it is displayed and may be edited in order to change the values in memory. A simple method of tracing through a program using the disassembler to display the instructions and their mnemonics is provided. Ten additional command characters are available for the user to extend the monitor facilities. Memory requirement and usage ---------------------------- Debug is 1K in length and is addressed at C000H. It requires the disassembler at C400H. The 1/4K of RAM from 0E00 to 0EFF is used by the disassembler and Debug at scratchpad area and should not be used by user programs while running Debug. The top 8 locations are used as follows. 0EFE 2 bytes point to Debug command table 0EFC 2 bytes for new user o/p address 0EFA 2 bytes for address of alternate CRT page 0EF8 2 bytes for the altername page cursor. OPERATING DEBUG --------------- Debug may be brought into use by executing at 0C000H. This will initialise Nas.sys and its workspace RAM. To avoid initialising Nas-sys, execute at C009h. On a Nascom 2 the restart address switches may be set to page C (LSW1 1&2 up and 3&4 down) so that Debug is entered on power up and whenever the reset key is pressed. All Debug commands must be entered with colon (:) as the first character on a line and with the command immediately following the colon. Loading zero's may be ommitted from data or addresses entered. The backspace or cursor control keys may be used to correct any erroneous entry before the enter key is pressed. For Debug to work, the user output jump $UOUT at 0C77H, in the Nas-sys workspace, must point to the routine DENT in Debug. The output table pointer must point to either OUTU or OUTX, so that the user output jump is used (this is done automatically when entering Debug). Any Nas-sys N command, executing at address 0, or using ZEAP) will turn off Debug, and it will be necessary to execute at C000H or C009H to restore Debug to use. The routine DENT in Debug, tests all the output characters. If the character is a CCR (18H) the single step display is triggered, if it is a CR (0DH) and the first character on that line was a colon, it is assumed that Debug command had been entered. For this reason it advisable to turn off Debug when using Basic or any program that may output a CCR or colon, by executing Nas-sys at address 0. EDITING THE SINGLE STEP DISPLAY ------------------------------- The registers PC, AF, BC, DE, HL, IX, IY and SP may have their contents altered by editing the single step display. The displayed memory locations may also be altered, but the register and memory locations may not both be changed in one editing operation. This is a safeguard to prevent accidental corruption of programs and, if attempted, only the register change will be accepted. The same restriction are applicable to the program counter and the bytes of the next instruction. The hex bytes of the instruction may be altered and as many characters as required may be entered provided that a space is left between the last byte and the instruction mnemonic. This allows several instructions to be altered in one operation. Nas-dis displays several lines of program for the RESTART instruct- ions used by Nas-sys for "RCAL", "SCAL" and "PRS". These extra lines may not be directly edited, but may changed by adding the required bytes to the "PC" line. To edit the display, move the cursor to the desired position, type in the new values and press the ENTER key. If the cursor is moved to another line without pressing the ENTER key the changes will not be accepted. If a non-hex digit is typed as part of a register or memory location value an Error message will be displayd, which may over-write part of the display. To restore the display move the cursor to an uncorrupted line and press the ENTER key. The Nas-sys X option may be used to output the single step display to a hand copy device. Changes made to the display during editing will only be shown on the CRT but the updated display may be output to a hand copy device by using the :P command ie. type :P and press the ENTER key. The Ascii representation of the flag register may not be directly edited. To alter the flags change the 3rd and 4th digits of the AF register display. THE :A and :O commands. Alternate page Option. ---------------------------------------------- These allow single stepping of programs that use the CRT screen without the loss of data which could occur when the single step display is put on the screen. Format :O nnnn where nnnn is the start address of an unused 1K of RAM above 1000 H. The specified RAM will now be used as the CRT "page" for any program that is executed or single stepped by Debug. The "page" is normally invisible to the user byu may be displayed by entering :A (Alternate page command). Commands may no be entered while this page is displayed as (ENTER) restores the original display. However, any other keys may be used to set up the alternate page, ready for single stepping or executing a program. : C command - Change user o/p ----------------------------- Debug utilises the user output location $UOUT provided by Nas-sys and allocates a new location to replace it at 0EFEH. on entering Debug this location is set to point at a return instruction within Debug. The :C command may be used to point the location at a use output program. Format :Cnnnn where nnnn is the users program address. :D command - Disassemble ------------------------ This provides a simple method of tracing through a program disass- embling and displaying each instruction. Format :Dnnnn where nnnn is the address to start disassembly. Each instruction is displayed by repeated pressing of the ENTER key. To change the address of the next instruction to be disassembled, type the address followed by (ENTER). To escape from the :D command press the SHIFT ENTER keys (ESC). Note. Attempting to disassemble through the FFFF-0000H boundary will case an indefinite loop, from which only escape is to press RESET. :F command - Find ----------------- This searches a specified area of memory for a string of up to 8 bytes which may be specified in Ascii and/or hexadecimal format. If the string is found the address at which it occurs is displayed followed by the 8 bytes at that address. The bytes are displayed in hexadecimal form and again in Ascii form if they can be printed. Non-printing characters are displayed as a dot. Format :Faaaa bbbb (ENTER) nn nn nn ,A ,B nn .......... etc. (ENTER). aaaa is the start and bbbb the finish address of the memory to be searched and nn nn etc is a string of up to 8 bytes to be searched for. The hex or Ascii values in the string are entered in the same manner as the Nas-sys MODIFY command, i.e. a comma immediately preceding a character specified the Ascii value of the character. e.g. :F 0 7FF ,N,A,S will display the part of Nas-sys that prints NAS-SYS on power-up or RESET. If less than 8 bytes are entered then the remainder will be treated as "wild". Wild bytes may be specified in a string by a dash (minus) without a comma preceding it. e.g. :F 0 7FF 22 - C This will display all parts of Nas-sys where the instruction LD (nnnn), HL is used to store a value in memory between addresses 0C00H and 0CFFH. The hexadecimal part of the data displayed may be edited in order to modify the memory contents provided the data is in RAM. To edit, simply move the cursor to the desired part of the display, type in the change(s) and press the ENTER key while the cursor is on the altered line. The Ascii part of the display will be seen to change to the new data. If the address of the displayed data is edited the bytes of data displayed will be entered at the altered address. :P command - Print Registers ---------------------------- No argument is required with this command, which displays the current status of the stored user registers in the same format as the single step display. The registers and locations pointed to by the registers may be modified using the screen editing facilities (see editing the sinlge step display). This facilitates the preperation for single stepping or executing a program. The :P command may also be used to restore the current display if ot has scrolled off the screen, due to other commands being used between single step operations. If Nas-sys 2 is in use the leading colon may be omitted. P (ENTER) is all that is required. ADDING ADDITIONAL COMMANDS -------------------------- The command table in Debug is at address C3E0H and may copied to RAM allowing additional command to be added. The table consists of 16 addresses (low byte first) one for each of the command characters :A to :P, starting with the address of the :A command. The characters B,E,G,H,I,J,K,L,M and N are not used by Debug and the adress in the table for these characters is that of Debug's error routine. To copy the table to RAM use Nas-sys I command e.g. I C3E0 nnnn 20 where nnnn is the new starting address of the table. Use the M command to update the table with the addresses of your own routines. To bring the new table into use, the command table pointer at 0EFEH must be changed to pint at the new table address minus 82H. This is easily calculated using the A command. e.g. A 82 nnnn where nnnn is the start address of the table. Nas-sys will print two numbers and ??. Use the second of these numbers, low byte first at 0EFEH and 0EFFH.