The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/prgtools/programm.ing/abztos.arc/ABZMON.DOC

Text File | 1985-06-01 | 20.9 KB | 443 lines

************************************************************************
**************************     ABZMON2    ******************************
************************** by Alain Birtz ******************************
************************************************************************

 This program was first written for the FASTER news disk. You can
contact the FASTER group on their BBS: 514-489-0680 or 514-489-3489.
ABZMON2 is now a public domain program; you may copy and distribute
it freely.

 The ABZMON menus are in the form:

     Alpha  Bravo  Exit:

 The user may select any option by typing its first letter only (in
upper or lower case). The default option is always the first item of
any menu. By example, for selecting the "Alpha" choice, you need only
to press the <Return> key. But to select the "Bravo" option, you need
to type 'B' or 'b', and confirm your choice by pressing the <Return>
key. Any invalid typing confirmed by <Return> key (here, other than A,
B, E, a, b, e) will re-display the same menu.

 When the program will ask you to enter an address or other value,you
may type it in hexadecimal form like: 12ea5 or 12EA5. But if the value
is preceded by the symbol '#' you can use the decimal form as: #77477.

 There's are important keys: the <UNDO> or the 'Q' or 'q' keys; hitting
any of these keys will stop the current process and the main menu will
be displayed. Some menus also have an Exit option (type 'E' or 'e',
followed by <Return>) doing the same job.

 The main menu is:

 Disasm Trace Hexed Search Free Move Load Break Go Regs CCR Info Exit:

 the meaning of each option is:

- Disasm: disassemble in the Motorola 68K mnemotechnic key word form
          with leading hexadecimal code

- Trace:  single step execution of the program with disassembled
          instruction, status flags and register values displayed

- Hexed:  full screen hexadecimal and/or ascii EDITOR

- Search: ascii or hexadecimal search with wild card char:
          '?' will replace any single character, same position

- Free:   reserve and/or display the free memory available

- Move:   data transfer from file/memory to file/memory

- Load:   load a program into memory

- Break:  set a breakpoint and the frequency of this breakpoint

- Go:     start execution of a program at a given address, exit at the
          breakpoint if any, or at a bug, or at the end of a program.

- Regs:   display/set address or data registers

- CCR:    set the CCR register

- Info:   display the current file information

- Exit:   return to the desktop

Note: In version 2.0, the other control key substitutions have been
activated in order to make the program friendlier and easier to use. The
cursor movement keys may be substituted with the 'L' ('l') for left, 'R'
('r') for right, 'U' ('u') for up, and 'V' ('v') for down. We cannot use
the 'D' ('d') key because it's already used and would conflict with the
hexadecimal notation system. The 'Q' ('q') and UNDO keys are now all
used for the same function (to abort the current process).

 The next section will describe each item of this main menu in detail.

 The first four options (Disasm Trace Hexed Search) accept many input
or output devices. When calling any one of these options, the user
will first see the OUTPUT menu:

 output-> Screen, Printer, File, Exit:

 As the Screen is the first item of this menu, you may select it by
pressing the <Return> key alone. The File option will prompt for a file
name. Warning: no information about an existing file will be given, and
in this case the file will be overwritten.

 Remember: the UNDO, 'Q', or 'q' keys exit to the main menu, stopping
the activity of the printer or closing the (incomplete) output file. If
the output is File or Printer, hitting the space bar will freeze the
output, hitting one more time will continue the output. The default path
name will be always the drive (and the folder, if any) from which you
have loaded the ABZMON.TOS program. So, if ABZMON was loaded from hard
disk "D:\MON.SRC", any file or program stored in this drive and folder
will need only their file name to be accessible to you. Any other file
or program will ask for a full path name.

 Note: you can use wildcards * and ? in the file name.

 Next, the user will see the INPUT menu:

 input-> Memory, Prg file, Data file, Exit:

 The Memory option needs a start address (if the 'current address', as
displayed by Info option is the address needed; only press the <Return>
key at the 'start address:' prompt). And if the output is File or
Printer you will also need to give the end address. Input file can be
of two kinds: The program file (Prg file option) loads a program in
memory, relocates all position dependant addresses, displays the base
page info (length and start address of the text, data and bss) and sets
the 'current address' to the first instruction of the program.

 The second type of input file is the data file. When the Data file
option is selected, the file is just copied in memory, whether the file
is a program file or a real data file. The start and the end addresses
of this data file is then displayed. But 'current address' will not be
affected.

 Now a word about the 'current address'. This address is the default
start address for the Memory input option (the default for the end
address is the start address + $ffff). This address is updated each
time a program is traced; also, after going through a Go option, this
address will be set to the breakpoint address. Such updating will give
a new default start address.

 ------------ Disasm

 The output form is like:

 000B9AC2   10D9                        MOVE.B  (A1)+,(A0)+
 000B9AC4   51CA FFE8                   DBRA    D2,$B9AAE
 000B9AC8   4E75                        RTS

 The first field is the hexadecimal address of the instruction, the
second field is the hexadecimal instruction code, and the third is the
Motorola 68K mnemotechnic key word. If the screen is the output, hit a
key to see the next instruction or press the <UNDO> key to return to
the main menu. Unknown instructions are singled out by the question
mark (?).

 ------------ Trace

 The output form is like:

  000BA25A   status: -----    ANDI.B     #$F,D0
 D 00003501 00000007 0016D741 00000000 00000000 00000000 00000000 00000000
 A 000BB2E9 00000000 00000000 00000000 0016D741 00000000 00000000 000B8900
  000BA25E   status: -----    BSR        $BA26A
 D 00003501 00000007 0016D741 00000000 00000000 00000000 00000000 00000000
 A 000BB2E9 00000000 00000000 00000000 0016D741 00000000 00000000 000B88FC
  000BA26A   status: -----    ADDI.B     #$30,D0
 D 00003531 00000007 0016D741 00000000 00000000 00000000 00000000 00000000
 A 000BB2E9 00000000 00000000 00000000 0016D741 00000000 00000000 000B88FC
  000BA26E   status: -N--C    CMPI.B     #$39,D0
 D 00003531 00000007 0016D741 00000000 00000000 00000000 00000000 00000000
 A 000BB2E9 00000000 00000000 00000000 0016D741 00000000 00000000 000B88FC
  000BA272   status: -N--C    BGT        $BA27A
 D 00003531 00000007 0016D741 00000000 00000000 00000000 00000000 00000000
 A 000BB2E9 00000000 00000000 00000000 0016D741 00000000 00000000 000B88FC

 The first line begins with the address of the instruction, followed by
the status flag and the mnemotechnic key word. If the Screen is the
output, this line is displayed in reverse video mode. The next two
lines are the values of the data and address registers, from 0 to 7.

 The status flags X,N,Z,V,C (Extended, Negative, Zero, oVerflow, Carry)
are shown by their first letter if set, otherwise only a minus sign
is shown.

 At program address $BA272, above, only the Negative and Carry flags
are set.

 With Screen output, hitting a key will display the next instruction.
If the output is a File or the Printer, the output is also driven to
the screen, but in a continuous display. Hitting the space bar will
freeze the display, so the user will be able to see where the program
is. Hitting the space bar again will continue the display. Emergency
exit is provided by the <UNDO> key.

 The ABZMON will trace only TRAP, TRAPV and CHK exceptions. Other
exceptions produce unpredictable result. ABZMON can also lose control
when executing DOS functions like GEM DOS Pterm function (in this case,
returns to desktop). If the program climbs the stack and passes over
the initial stack state, a message is sent and the Trace process exits
to main menu.

Note: Version 2.0 contains a nice feature (so everybody tells me!). The
possibility to quickly go through the subroutine with a press of the
left cursor key (also with the 'L' or 'l' keys). This will cause ABZMON
to go through and cleanly return from the subroutine without bothering
you with information you already know about that part. The program will
report the number of instructions executed before the return from the
subroutine. Symetrically, you may access to the next routine with a
press of the right cursor key ('R' or 'r'). Any alterations (up or down)
of the stack will be detected. The '=' key will detect and report the
first alteration to the stack and break the execution of the current
program at the address of the instruction which brought about a change
of the stack pointer.

 ------------ Hexed

 This is a powerful examine-modify memory/file tool. The output form is:

 000B8AA4  69 66 20 65 78 69 73 74 20 25 31 20 70 61 75 73 if exist %1 paus
 000B8AB4  65 0D 0A 61 73 36 38 20 25 31 2E 73 0D 0A 6C 69 e..as68 %1.s..li
 000B8AC4  6E 6B 36 38 20 25 31 0D 0A 72 6D 20 25 31 2E 6F nk68 %1..rm %1.o

 The first field is the hexadecimal address, the second field is the 16
next bytes values (in hexadecimal) starting at that address and the
third is the ascii characters for these values. If the output is the
Screen, the first and the third fields are in reverse video mode for
more readability and the third field uses the full ST character set. If
the input is a File, the address in the first field is the offset from
the beginning of the file.

 To examine, move the cursor up and down. If the cursor is already at
the top or bottom line, the screen will scroll to display another line.
To modify, move the cursor left and right on the second field. At the
right byte, change the hexadecimal value. You must enter this value at
the first digit of the byte, and then, you must forcibly enter the
second digit.

 Another way to modify values is by using the ascii character field. To
enter this field, hit the RIGHT-SHIFT key (to exit LEFT-SHIFT) and then
enter text in the usual way. After the 16th character, the cursor moves
down to the first character of the next line. You can move the cursor
within this field with the down, up, left and right cursor keys.

 The <UNDO> key exits to the main menu. At this point, if the input is
a file and if a byte has been modified, ABZMON.TOS will ask to save the
modified file.

 ------------ Free

 Gives the amount of free memory. Some memory can also be reserved. The
Free menu is like:

 bytes free $0003f560    need:

 Here, $3f560 (259 424) bytes are available, if you just hit <Return>
no memory will be reserved, otherwise, type the number of bytes needed.
ABZMON will reply with the start and end addresses of the memory block
reserved.

 ------------ Move

 Data transfer from file/memory to file/memory. If the source and/or
destination is memory you must supply the start (and end) addresses,
otherwise, a file name is needed. You can reserve some room in memory
via the Free option in the main menu.

 The move menu is:

 1- file to memory  2- memory to file  3- memory to memory  0- exit:

 ------------ Load

 Loads a program in memory, relocates all position dependant addresses,
displays the base page info (length and start addresses of the text,
data and bss) and sets the 'current address' to the first instruction
of the program.

 ------------ Break

 Use this option to set a breakpoint. ABZMON.TOS will ask you for the
breakpoint address, then you will see "how many times:". If you want a
normal breakpoint, just hit <Return>. And when you'll select the Go
option, ABZMON.TOS will stop the program's execution at the previously
given address and display the state of the status flag, the value of
the address and data registers and set the 'current address' to the
next instruction to be executed, which will be the breakpoint address.

 If you do not want the program to stop at the first time, give any
needed value, ex. #117, then ABZMON will count (from 1) the number of
times that program passes by the (breakpoint) address and will stop
the program's execution when the count will be 117. The default number
of iterations before a breakpoint is 1.

 Warning: the breakpoint address must not be set in a middle of an
instruction or otherwise, unpredictable results will occur, the address
must be the beginning of the instruction. Use the Disasm option to find
the correct address.

 Note also that the program stops BEFORE executing the instruction at
the breakpoint address. So if you have asked for 117 passes, your
program execution will be stopped just before the execution of the
117th pass.

 ------------ Go

 The Go menu is:

 start address:

 ABZMON starts the execution of the program at the given address. If
you just hit <Return> execution begins at the 'current address'. ABZMON
exits at the breakpoint address, if a breakpoint is set. Otherwise the
program will probably return to the desktop.

 ------------ Regs

 With this option you can at any time change the value of the data
and/or register value. When calling this option you will see something
like this:

 D 00003531 00000007 0016D741 00000000 00000000 00000000 00000000 00000000
 A 000BB2E9 00000000 00000000 00000000 0016D741 00000000 00000000 000B88FC

but in reverse video mode, and the cursor will be located at the value
of the D0 register. You can move the cursor to any register and at any
digit inside the register value with the left, right, up and down
cursor keys. You can change a register value by changing any of its
digit values. Use <UNDO> keys to return to the main menu.

 ------------ CCR

 The CCR is stored in bits 0-4 in the lower byte of the Status
Register, bits 5-7 are not used. When ABZMON asks for a new value of
the CCR register. Simply hit the <Return> key if you do not wish to
change anything or else, give an appropriate value (from $00 to $1F).

 Exemple: Look at line $000BA272 in the output example of the Trace
instruction. The CCR is -N--C and you want to clear the N bit and set
the Z bit in order to have a CCR like this: --Z-C (bit value= 00101).
You will type '5' (which is $05 or %00000101) confirmed by <Return>. To
have all flags set (bit value=11111), you will type '1F' or '1f'.

 ------------ Info

 Gives the info on the last program loaded in memory: file name, length
and addresses of the text, data and bss, and the value of the 'current
address'. Also gives the info about the last data file: file name and
start and end addresses. If you have more than one data file in memory,
the Info option will not provide info on data files except for the last
one. But first loaded, data files are still in memory. Many data files
can sit at the same time in memory, but when a program is loaded, all
free memory is allowed to the program execution, so only one program
may be in memory at the same time. However you can load a new program,
the old one will be overwritten by the new program. Remember to move to
disk all needed data files in memory before loading a program file.

 This is a safe way if something has to go wrong. With Raoul's 1040ST,
we were able to put in memory a data file (using Disasm, output Screen,
input Data file) after loading a program. But with my 520ST (upgraded
to 1 Meg), I was unable to do the same, all attempts resulted in an I/O
error no $0027.

 ERROR MESSAGES:

 If an Input-Output error is generated when ABZMON.TOS is working for
you, you will be notified by a message giving the hexadecimal ID number
of the error like: "I/O error no $0021". If you wish to know the
meaning of those numbers, you will have to look at a book giving
information on GEM such as "INTERNALS" from Abacus Software (page 139
and 146). The ID numbers from $0001 to $001F are for the BIOS or XBIOS
and numbers from $0020 to $0031 are for the GEMDOS. When such errors
occur, press the <Return> key.

 When your program is executed by the Go option or traced by the Trace
option, a Bus error, Address error or Illegal instruction error will
stop the process and the error type will be displayed with three
addresses like: "Bus error at: $57A28 [$5288C $55CF8]". The first
address is the PC at fault. The last two addresses are (generally) the
sub routine address where the instruction came from. WARNING!! Some
desk accessories (like THUNDER when activated) may interfere with
ABZMON.TOS, so we strongly suggest you to make a special ABZMON.TOS
boot disk with only the essential desk accessories files.

 When ABZMON.TOS loads a program in memory, it will place it according
to the available memory at the loading time. So, in order to have the
same starting address and same relative addresses in a listing, from
one ABZMON.TOS session to any other, you will have to load your program
just after recalling the ABZMON.TOS. Any use of the Free option before
loading a program will put it higher in the memory, making the starting
address and relative addresses different from a previous work session.
Same when reloading a program without using the Exit option. If this
happens, you will have to calculate an offset for each relative address
when comparing a previous listing with the new one.

 A SHORT SESSION ON ABZMON:

 You have worked very hard to compose your program, but there is a bug
and you don't know where it is. Do not use DDT or SID stuff, just call
"ABZMON.TOS" instead.

 Have a copy of your program on the "ABZMON.TOS" disk and after booting
call "ABZMON.TOS". Select from the main menu the Load option and give
as path name the file name of your program. As the 'current address' is
now pointing to the first instruction of your program, select the Go
option and just hit the <Return> key. This will execute your program
from its first instruction. But as soon as the ST will try to execute
the bugged instruction, the  process will be stopped and an error
message will be displayed like: Address error at: $B8020 [$B6A40
$B7ACC]. The bug is probably in the neighbourhood of $B8020.

 Now, as it is best to exit from "ABZMON.TOS", write down these
addresses and the starting address of your program, then Exit. This
will clear all registers. Recall "ABZMON.TOS" and reload your program.
The 'current address' of your program should be the same as previously.
It is possible to reload your program without going through the Exit
option, but in this case, it will be loaded some few bytes higher in
the memory and you will have to calculate an offset. The next step will
be to Disasm your program in order to find the beginning address of an
instruction before the suspected one (like $B8020). After finding such
addresses, press the <Undo> key to exit from the Disasm mode. Now, use
the Break option to set a breakpoint at the located address like $B8012.
After, you will use the Go option to execute your program from its
first instruction.

 "ABZMON.TOS" will stop your program execution at the breakpoint
address and set the 'current address' to the breakpoint (like $B8012).
Then select the Trace option. Press the <Return> key three times, one
for the default output (Screen), one for the default input (Memory) and
the last one for the default address (current address). Now, any key
press (except the <Undo> key) will execute only one instruction at a
time and will display the Trace information. When the monitor tries to
run the bug, ABZMON.TOS will display an error message giving the error
type and three addresses. The bug is there. Look at the value of the
registers, you should find the bug as an odd address (ex. $16B25). Now
you will need to examine the program in more detail to see where the
bug comes from, like me with my odd address bug.

 I do Info to find the text segment of the program (start and end
addresses), then Disam, with output driven to the Printer, input being
Memory from the start address to the end of the text segment. I now
have a complete listing of the program. Using the Trace again, in
conjunction to the listing, I find my error in few minutes.

 ACKNOWLEDGMENTS TO:

-My brother Daniel for his relevant suggestions for improvement.

-Raoul Charbonneau and Alain Plouffe who have participated in the
writing of the documentation and the testing of ABZMON.TOS.

                                       Alain Birtz
                                       1683 Haut de la Riviere Sud,
                                       St-Pie, P.Q., Canada J0H-1W0

                                       CompuServe id: 72467,2770