Debug
Some rough notes until I find a Debug manual…
Command summary here: {{:documentation:software:debug_summary.pdf|Debug Summary}}
Start with PROG.ST$X to load and use a symbol table.
$N to change output base.
TAB TAB n to change global output mode (addr/instr etc.).
<ESC>T followed by 1 for numeric output, 3 for instructions, 7 for characters.
<ESC>A to show ACs, ‘F’ for FPACs, ‘E’ for Wide Stack regs, ‘L’ for PC, ‘V’ for PSR
<addr>/ display word at addr.
<addr>\ display doubleword at addr.
<addr><ESC>B set breakpoint.
<ESC>R to start running.
<ESC>-P to continue (“Proceed”) from the current breakpoint
Help
Welcome to DEBUG4, the AOS/VS User Debugger.
For help on any of the following topics, enter: <keyword><escape>H
while debugging a program.
The DEBUG keywords are:
A - examine/modify accumulators N - examine/modify output radix
B - set/display breakpoints P - proceed from breakpoint
C - push to the cli Q - examine/modify bkpt proceed count
D - delete breakpoint(s) R - proceed from program counter
E - examine/modify stack regs S - memory display/search
F - examine/modify floating ACs T - examine/modify display mode
G - examine/modify ring reg V - examine/modify PSR
H - this help message W - memory dump to disk file
I - define/list temp symbols X - enable/disable symbol table
J - delete temp symbol(s) Y - enable/disable logfile
K - type out TCB and UST info Z - exit
L - examine/modify PC ? - display verbose error message
M - examine/modify input radix UC - change debugger input/output console
UL - display/search linked list
MEM - examining/modifying memory LOCAL - local symbol support
DIS - changing display modes
A B C D DIS E F G I J K L Local M N P Q R S T V W X Y Z
A
$A - EXAMINE/MODIFY FIXED POINT ACCUMULATORS AND CARRY BIT
To display all of the fixed point accumulators and carry, type:
<escape>A
The ordering of the display is AC0, AC1, AC2, AC3 and CARRY.
To open a fixed point accumulator, type:
<number><escape>A
where <number> is 0 (for AC0), 1 (for AC1), 2 (for AC2), 3 (for AC3),
or 4 (for CARRY).
To modify an accumulator, first open it, and then immediately type
the new value, followed by <carriage-return> or <new-line>.
B
$B - SET/DISPLAY BREAKPOINTS
Issue the following command to set a breakpoint:
<address>,<condition><escape>B
where <address> is the address of the breakpoint; and
<condition> is an optional argument where you may enter an expression.
If you supply this argument, DEBUG evaluates the expression
every time the instruction at <address> is executed. If the
expression's value is non-zero, DEBUG stops execution at the
breakpoint; otherwise, program execution continues.
To display all currently set breakpoints, type:
<escape>B
This command displays the breakpoint numbers, the breakpoint addresses,
and the proceed counts associated with each breakpoint.
C
$C - PUSH TO THE CLI
The Debugger allows you to temporarily suspend your debugging session
and execute the CLI. The command for this is:
<escape>C
This command does not accept arguments.
When the CLI terminates, your debugging session will resume.
D
$D - DELETE BREAKPOINTS
The command to delete a given breakpoint is:
<breakpoint_number><escape>D
where <breakpoint_number> is the number of the breakpoint you wish
to delete as shown in a breakpoint display (see the
<escape>B command).
To delete all breakpoints, type:
<escape>D
This removes all breakpoints from your program.
DIS
DISPLAY MODES
DEBUG provides local and global display mode commands. To redisplay
the last output value in a different display mode, strike one of the
function keys; to change the global display mode, enter the control
character sequence <CTRL-function key>.
The ordering of the function keys is (from left to right): numeric,
numeric word, instruction, symbolic, half-word, byte-pointer, ASCII,
floating-point, system call, and CLI error message formats.
If your console doesn't have function keys, type:
<tab><number> - for local display mode commands
<tab><tab><number> - for global display mode commands
where <number> represents one of the following modes:
0 - AOS/VS error message format 5 - half-word format
1 - numeric format (default) 6 - byte-pointer format
2 - numeric word format 7 - ASCII format
3 - instruction format 8 - floating-point format
4 - symbolic format 9 - system call format
E
$E - EXAMINE/MODIFY MV/8000 STACK REGISTERS
To display all of the MV/8000 stack registers, type:
<escape>E
The ordering of the display is ESP, EFP, ESL and ESB.
To open a stack register, type:
<number><escape>E
where <number> is 0 (for SP), 1 (for FP), 2 (for SL) and 3 (for SB).
To modify a stack register, first open it, and then immediately type
the new value, followed by <carriage-return> or <new-line>.
F
$F - EXAMINE/MODIFY FLOATING POINT ACCUMULATORS AND STATUS REGISTER
To display all of the floating point accumulators and status register,
type:
<escape>F
The ordering of the display is FPAC0, FPAC1, FPAC2, FPAC3, FPSR and FPPC.
To open a floating point accumulator or status register, type:
<number><escape>F
where <number> is 0 (for FPAC0), 1 (for FPAC1), 2 (for FPAC2), 3 (for FPAC3),
4 (for FPSR) or 5 (for FPPC).
To modify an accumulator or status register, first open it,
and then immediately type the new value, followed by <carriage-return>
or <new-line>.
G
$G - EXAMINE/MODIFY RING REGISTER
The ring register provides the default ring number that you will be
working in during your debugging session. Any address you type in that
contains a zero in the ring field will be modified to hold this
ring number instead.
To open the ring register, type:
<escape>G
This will display the current value in the ring register. When you
first begin your debugging session, the ring register holds the ring
value of your program's starting address (i.e., the ring of the
initial program counter).
To change the ring field register, first open it, and then
immediately type the new value, followed by <carriage-return> or
<new-line>.
Legal values for the ring register are 3 through 7. Also, you may
only address the unshared portion of ring 3.
I
$I - DEFINE/LIST TEMPORARY SYMBOLS
DEBUG allows you to define symbols during your debugging session.
The Debugger treats these symbols, referred to as temporary symbols,
the same as it treats global symbols from the .ST file.
To define a temporary symbol, type:
<symbol_name>,<value><escape>I
where <symbol_name> is the name of the temporary symbol; and
<value> is the value you assign to this symbol.
Note that <symbol_name> can be 32 characters long, and it
may duplicate a symbol name in the .ST file. In the
event of duplicate names, DEBUG uses the temporary
symbol's value.
To list all temporary symbols, type:
<escape>I
This command displays all currently defined temporary symbols
and their values.
J
$J - DELETING TEMPORARY SYMBOLS
You may remove a particular temporary symbol from the temporary symbol
table by entering the command:
<symbol_name><escape>J
To delete all temporary symbols, type:
<escape>J
K
$K - DISPLAY UST AND TCB INFORMATION
The Debugger will type-out information for you from your UST and TCB.
You cannot do this otherwise because you don't have read access to ring 3.
The command to do this is:
[<number>]<escape>K
where-
<number> is an optional field where you can enter the ordinal
number of the TCB you want displayed.
If you do not enter a TCB number, UST information is typed out, such as
memory limits for all rings, currently active TCB number, etc...
If you enter a TCB number, information concerning that TCB is typed out, such
as the Accumulators, the task status word, the current system call, etc...
L
$L - EXAMINE/MODIFY THE PROGRAM COUNTER (PC)
When you first enter the Debugger, your program's starting address
resides in the program counter (PC). Also, when your program stops
at a breakpoint, the address of that breakpoint is in the program
counter (PC).
To open the program counter (PC), type:
<escape>L
DEBUG will display the current contents of the program counter,
and leave that register open for modification.
To modify the program counter, open the register and immediately
enter the new value, followed by either <carriage-return> or
<new-line>.
Note that modifying the value of the program counter
changes the address of the next instruction to be executed
when you proceed with program execution.
Local
Local symbols, if present in the .ST file, can be used for typing in
any expression. Also, DEBUG4 will use them for typing out locations if a
module has been specified via the % command (see below). The MASM and LINK
manuals describe the use of /LOCAL switch to include local symbols in your
.ST file.
Use the % command to specify the name of a module for local symbol
support. The command has the format:
<title>%
where <title> is the name of a module (don't type the angle brackets)
corresponding to a MASM .TITLE statement, and % is the ASCII percent sign
character. DEBUG4 will use the local symbols for this module until the
process terminates or you give a new % command.
If you have not given the % command, you can still use a local symbol
to type in expressions. The symbol will be used if it is unique, although it
will take longer for DEBUG4 to find it. If DEBUG4 finds the symbol in more
than one module, it will give the error "?Non-unique local symbol". You can
avoid this error by using the % command.
M
$M - EXAMINE/MODIFY INPUT RADIX REGISTER
All of DEBUG's numeric input is in the radix specified in the input
radix register, except if that number is suffixed with an implicit radix
specifier. The input radix specifiers are-
nnnnnO - specifies octal (default)
nnnnn. - specifies decimal
nnnnnH or nnnnnZ - specifies hex (this must always start with number)
To examine the current input radix, type:
<escape>M
This will display the current input radix (in decimal).
To change the input radix, first open the radix register, then
immediately enter the new radix, followed by either <carriage-return>
or <new-line>. DEBUG allows radices in the range 2. through 16.
(i.e., binary to hexadecimal).
N
$N - EXAMINE/MODIFY OUTPUT RADIX REGISTER
All of DEBUG's numeric output is in the radix specified in the
radix register. The default radix is octal.
To examine the current output radix, type:
<escape>N
This will display the current output radix (in decimal).
To change the output radix, first open the radix register, then
immediately enter the new radix, followed by either <carriage-return>
or <new-line>. DEBUG allows radices in the range 2. through 16.
(i.e., binary to hexadecimal).
P
$P - PROCEED FROM A BREAKPOINT
To continue program execution after a breakpoint, enter
the proceed command:
<escape>P
When entering this command, you may also specify a new proceed count
for the last breakpoint encountered. The syntax for this command is:
<count><escape>P
where <count> is the number of times your program must encounter
the last breakpoint before execution stops at that
breakpoint again.
Note that this command associates a proceed count with
the last breakpoint taken; proceed counts on all
other breakpoints are unaffected. Default proceed count = 1.
Also note that you may only use this command when proceeding from a
breakpoint. You can NOT use this command to start program execution
when you first enter the Debugger.
Q
$Q - EXAMINE/MODIFY BREAKPOINT PROCEED COUNT
The proceed count for a breakpoint is the number of times your program
must encounter the instruction at that breakpoint address before
execution stops. The default proceed count for all breakpoints
is one; that is, stop execution each time your program encounters
the breakpoint.
The following command allows you to access the proceed count for
any breakpoint:
<breakpoint_number><escape>Q
where <breakpoint_number> is the number of the breakpoint as shown in
the breakpoint display list (see the <escape>B command).
The above command will display the current proceed count for the
specified breakpoint.
To change a proceed count, first display its current value (with the
above command), then immediately enter the new value,
followed by either <new-line> or <carriage-return>.
R
$R - START/CONTINUE PROGRAM EXECUTION AT SPECIFIED ADDRESS
To start or continue execution of your program, enter the command:
<escape>R
This command starts program execution at the address specified in the
program counter (PC). If you have not modified this register, then
the PC already contains the address of the next instruction to be
executed in your program.
You may enter an optional address in this command as follows:
<address><escape>R
This command places <address> into the program counter (PC),
and then starts or continues program execution at that address.
Note that you must use one of these commands to start program execution
when you first enter a debugging session. You may also use this command
to continue execution after a breakpoint.
S
$S - MEMORY DISPLAYS AND SEARCHES
DEBUG allows you to display any portion of your logical address
space in the current display mode, or search your address space
for all locations where a specified condition holds true.
The syntax for the command that performs these
operations is:
<addr_low>,<addr_high>,<condition>,<increment>,<size><escape>S
where <addr_low>,<addr_high> are the memory bounds to be traversed,
inclusively.
<condition> is an optional field which contains an expression
to be evaluated at each address between <addr_low>,<addr_high>.
If the expression evaluates to a non-zero value, DEBUG
displays the contents of that location; otherwise, DEBUG
does NOT output the contents of the location.
Use the location counter symbol . (period) to reference the
current address value. The default value for the
condition is TRUE.
<increment> is an optional field that specifies the number
of words DEBUG increments the location counter by between
each display or search. The default is one word.
<size> is an optional field for specifying how many words to
display at each location examined. The <size> value
may range from 0 to 4. The default is one word.
T
$T - EXAMINE/MODIFY GLOBAL DISPLAY MODE
DEBUG stores the global display mode in an internal register.
To examine this register, type:
<escape>T
The value in this register appears as an encoded value that
corresponds to one of the display modes as follows:
0 - CLI error message format 5 - half-word format
1 - numeric format (default) 6 - byte-pointer format
2 - numeric word format 7 - ASCII format
3 - instruction format 8 - floating-point format
4 - symbolic format 9 - system call format
You may change the global display mode by modifying the value
in this register. To do this, first open the register, then
immediately enter the new value, followed by <carriage-return>
or <new-line>.
Note that you may also modify this register with the global display
mode commands: <CTRL><function-key> or <tab><tab><number>
V
$V - EXAMINE/MODIFY PROCESSOR STATUS REGISTER (PSR)
The PSR contains the overflow bit (OVR) and overflow mask (OVK).
To open the PSR, enter the command:
<escape>V
There are only 2 bits of interest in the PSR:
Overflow mask (OVK) = 100000
Overflow bit (OVR) = 40000
You may modify the contents of the PSR by opening it,
and then entering the new value, followed by either
<carriage-return> or <new-line>.
Note that you may only modify the overflow mask (OVK) and
overflow bit (OVR). The resume bit and the rest of the bits
in the PSR are reserved for use by the hardware, and if you
try to modify them, DEBUG will return an error.
W
$W - DUMP MEMORY CONTENTS TO A FILE
The Debugger allows you to dump the memory image of a given ring
to a disk file. The command for this is:
[<addr>][,<filename>]<escape>W
where-
<addr> is an optional field where you specify an address in
the ring you want to dump; default is to ring 7.
<filename> is an optional field where you specify the filename
you want the memory image dumped to. If not specified,
a filename is chosen for you, similar to the way Breakfile
names are chosen.
The dump file has a preamble which contains your UST and TCB information
which may be examined by FED.
You must have read access to the .PR file of the specified ring to dump it.
X
$X - ENABLE/DISABLE SYMBOL TABLE
When you first enter a debugging sesson, DEBUG searches for
your program's symbol table file. This file has the same name
as your program, but has an .ST extension (instead of .PR).
If DEBUG finds the .ST file, it can recognize all global symbols
you define in your program.
The format for explicitly enabling a symbol table file is:
<filename.ST><escape>X
where <filename.ST> is the complete pathname of the .ST file;
you must include the .ST extension when specifying
the filename.
This command enables symbols in the .ST file for both your input
and DEBUG's output.
To disable the current .ST file, enter:
<escape>X
This closes the symbol table file that is currently in use.
Y
$Y - ENABLE/DISABLE LOGFILE
You may open a logfile to record all console activity.
The format for specifying the logfile name is:
<filename><escape>Y
where <filename> is the complete pathname of the logfile.
If the file doesn't exist, it will be created; else, the new
information will be appended to the end of the existing file.
To close the current logfile, enter the command:
<escape>Y
This command disables the open logfile.
Z
$Z - EXIT FROM THE CURRENT DEBUGGING SESSION
To terminate the current debugging session
and return to the CLI, enter:
<escape>Z
On termination, DEBUG removes all breakpoints from your program
file.
Note the the control character sequence <CTRL-D> also terminates
your debugging session and returns control to the CLI.