@c -*-texinfo-*-
@node Debugger, Low Level Foreign, Low Level, Top
@comment  node-name,  next,  previous,  up
@appendix ICP Debugger User Guide 

This section is not for the faint-hearted! It is intended for developers 
of the ICP system only and will not be useful to most users of the 
system.

The ICP debugger allows the user to debug programs at the instruction level,
rather than at the Prolog level.  There are commands to examine the various
stacks and registers, setting breakpoints and tracing instruction execution.
An understanding of the WAM architecture and instruction set is required to
make full use of this debugger.

The debugger can be entered in three ways:

@enumerate
@item
executing the Prolog call @code{debugicp/0},
@item
choosing option d in the interrupt handler,
@item
choosing option d in the Prolog tracer.
@end enumerate

In all cases, the contents of the registers are displayed like this:
@example
| ?- debugicp.

P = 6488 : succ
CP=10540 : put_slash1
H =0x0006d, HB=0x0006d, HMAX=0x17e4c, S=0x0006d:trace
E =0x1806b, CE=0x1806b, TR=0x1ffff
B =0x18061, SB=0x18061, CSB=0x1804e, GC_B=0x18000, CATCH=0x18061
A[00]=[]        A[01]=debugicp  A[02]=889420    A[03]=889420
A[04]=889272    A[05]=trace     A[06]=3 A[07]=$$$
---------------------------------------------------------
[0] >> 
@end example

The first line shows the contents of P (the program counter) and the
instruction at that address.  The second line displays the same information
for the CP register (continuation program counter). The next 3 lines show the
contents of all the other WAM registers. These are all pointers into the stack
area, so the contents are displayed as stack addresses.  In addition, the
contents of the address pointed at by the S register is displayed.  Finally
the contents of the argument registers and local environment are shown.  The
debugger makes a guess at the number of arguments and size of environment
currently in use and shows only those to avoid cluttering up the s creen.
This can be changed by the user.

It is important to note that there are two separate address spaces. The first
is the code area which is pointed to by P and CP registers. These addresses
are displayed as decimal.  The other area is shared by the local stack, trail
and heap.  Addresses in this area are shown as hexadecimal.

@menu
* DisplayingPrologCell::        Displaying a Prolog Cell 
* DebuggerMenuOptions::         Menu Options 
* SettingBreakpoints::          Setting Breakpoints 
* Disassembling::               Disassembling 
* DisplayingStacksRegisters::   Displaying Stacks and Registers 
* DisplayingTrail::             Displaying the Trail 
* DisplayingHeap::              Displaying the Heap 
* DisplayParameters::           Display Parameters 
* MiscellaneousCommands::       Miscellaneous Commands 
@end menu

@node DisplayingPrologCell, DebuggerMenuOptions,  , Debugger
@comment  node-name,  next,  previous,  up
@appendixsec Displaying a Prolog Cell 
The contents of argument registers and local environment are Prolog cells.  A
Prolog cell can hold an integer, the nil list, a variable (or a link), a list
pointer, a tuple pointer or a symbol pointer.  If the cell contains a pointer,
the term pointed at is displayed rather than the pointer itself unless in
verbose mode (see below).  Symbols are displayed as the print name in quotes.

Lists are denoted using square brackets (@samp{[} and @samp{]}).  Tuples
are shown as predicated relations.  Known garbage is displayed as either
`@kbd{$$$}' or `@kbd{???}' depending on whether the tag of the cell is
valid or not. There is a user-settable limit on the display of large
terms, the default is a depth of 10.  The rest of the term is displayed
as `@kbd{...}'. Variables are shown by their address (hexadecimal)
prefixed by an underscore.

If verbose mode is on, the pointers are displayed also.  This takes the form
of a letter denoting a tag (C for constant symbols, L for lists and T for
tuples), followed by the address in hexadecimal.  Links are shown in verbose
mode as arrows `@code{->}' between addresses.

When examining heap cells, there is another tag type - the guard.  This
is used to mark the beginning and end of a block containing unstructured
data.  The most usual case is constant symbols or floating point numbers
in the heap.  The guard cell is displayed as @kbd{G:n} where @kbd{n} is
the length of the block.

@node DebuggerMenuOptions, SettingBreakpoints, DisplayingPrologCell, Debugger
@comment  node-name,  next,  previous,  up
@appendixsec Menu Options 
Typing `@kbd{?}' will display a menu of debugger options as follows:
@example
[0] >> ?
  <CR>      - single step
  g         - Go until breakpoint reached
  b [addr]  - set Break point
  B <rel>   - set Break point on a relation
  c [addr]  - Clear break point

  l [a [n]] - List/disassemble from address a, n instructions
  L <rel>   - List/disassemble a relation (pred/arity)
  r         - display Registers
  s [n]     - display top n records of local Stack
  t [n]     - display top n entries of Trail
  h [n]     - display top n cells of Heap (constructed term stack)
  m a1 a2   - dump Memory (heap cells) from address a1 to a2
  u         - list Undefined relations
  M         - output Memory map of predicates and addresses

  d [level] - change Debug level
  D [depth] - change max display Depth of terms
  R [n]     - change #Regs and #locals displayed
  v         - toggle Verbose mode (show pointers)
  ?         - display this help page
  q         - Quit
---------------------------------------------------------
[0] >> 
@end example

The prompt displays the debug level within square brackets.  There are 4 debug
levels numbered 0 to 3.  The `@kbd{d}' command changes the debug level.

@table @code
@item Level 0
no debugging
@item Level 1
stop at call or jump instructions, echo fail and succeeds
@item Level 2
stop at every instruction (single stepping)
@item Level 3
show unifications, resets and stack allocations
@item Level 4
for debugging the garbage collector
@end table

Hitting @kbd{@key{RET}} will single step at at the call or instruction level,
depending on whether the debug level is less than 2 or not.  If the debug
level is 0, @kbd{@key{RET}} will cause an exit from the debugger.

Note that in commands which take arguments, the separator is a space
character, not a comma.

@node SettingBreakpoints, Disassembling, DebuggerMenuOptions, Debugger
@comment  node-name,  next,  previous,  up
@appendixsec Setting Breakpoints 
Breakpoints can be set by using predicate names or addresses. Use 
`@code{B Pred/Arity}' to set a breakpoint on a relation.
Breakpoints are set using decimal addresses only.  Use `@kbd{b}' to set a 
breakpoint and `@kbd{c}' to clear it.  If no argument is given, the current 
address is used. Once a breakpoint is set, you can use `@kbd{g}' to skip to 
the next breakpoint.

@node Disassembling, DisplayingStacksRegisters, SettingBreakpoints, Debugger
@comment  node-name,  next,  previous,  up
@appendixsec Disassembling 

We can disassemble programs by specifying the predicate name or the
address. To disassemble a predicate, use the command `@kbd{L
Pred/Arity}'.  The alternative is the use of the `@kbd{l}' command which
takes up to two arguments. If no arguments, a page of instructions
(default 20) starting from the current address of @kbd{P} is displayed.
Subsequent `@kbd{l}' commands will continue the listing with the next
page of instructions. This allows a rapid scanning of the code. If given
one argument, the listing will start from that address. If a second
argument is present, this will change the default number of instructions
per page.

@node DisplayingStacksRegisters, DisplayingTrail, Disassembling, Debugger
@comment  node-name,  next,  previous,  up
@appendixsec Displaying Stacks and Registers 

The command `@kbd{r}' displays all the main registers. `@kbd{s}'
displays the local stack containing environments and choicepoints. There
are three types of records on the stack - choicepoints, currently active
environments and inactive environments which will only b ecome active if
backtracking occurs. The currently active environments are displayed
flush left. The stored values for @kbd{CP}, @kbd{CE}, @kbd{CSB} and
@kbd{HMAX} are displayed together with the contents of variables in the
environment. The inactive environments are displayed similarly but
indented by one tab. The choicepoints are indented by 3 tabs and show
the argument registers and WAM registers. The stack is displayed top to
bottom. The example below shows an active environment on the top of the
stack followed by a choicepoint, two inactive environments and another
active one. The lines displaying variables in the environment or
argument registers in the choicepoint are prefixed by the address in the
stack of the first variable/argument.

@example
[0] >> s

18073: Y[00]=940104   Y[01]=939864   
CP= 30376, CE=0x18058, CSB=0x18041, HMAX=0x17e47

            H=0x0007f, TR=0x1ffff, E=0x18058, B=0x1804e
            P= 10559, CP= 30376, CSB=0x18041, HMAX=0x17e48
            18060: A[00]=[]   A[01]=append([],[5],_73)
                   A[02]='$toperror$'(append([],[5],_73),_7e)
                   A[03]=_7e   A[04]=939864   

1805c: Y[00]=['='('X',_73)]   Y[01]=append([],[5],_73)
       Y[02]=[]   Y[03]='='('X',_73)   
CP= 10540, CE=0x18033, CSB=0x1801a, HMAX=0x17e4d

            H=0x0007b, TR=0x1ffff, E=0x18033, B=0x18041
            P= 30421, CP= 10540, CSB=0x1801a, HMAX=0x17e53
            1804b: A[00]=[]   A[01]=append([],[5],_73)
                   A[02]=['='('X',_73)]   

            H=0x00055, TR=0x20000, E=0x18039, B=0x18029
            P= 18929, CP= 30140, CSB=0x18029, HMAX=0x17e53
            18040: A[00]=[]   

    1803d: Y[00]=['='('X',_73)]   Y[01]=append([],[5],_73)
           Y[02]=['='('X',_73)]   
    CP= 10540, CE=0x18033, CSB=0x1801a, HMAX=0x17e53

18037: Y[00]=939864   Y[01]=939700   
CP= 30038, CE=0x18015, CSB=0x18000, HMAX=0x17e5d

            H=0x00055, TR=0x20000, E=0x18015, B=0x1801a
            P= 10559, CP= 30038, CSB=0x18000, HMAX=0x17e5e
            18024: A[00]=[]   A[01]=query_handler
                   A[02]='$toperror$'(' ',_54)   A[03]=_54
                   A[04]=939700   

            H=0x00051, TR=0x20000, E=0x18015, B=0x1800b
            P= 18929, CP= 30024, CSB=0x18000, HMAX=0x17e5f
            18019: A[00]=[]   

18019: 
CP=-631664, CE=0x18000, CSB=0x18000, HMAX=0x17e5f

            H=0x00021, TR=0x20000, E=0x18000, B=0x18000
            P= 30039, CP=-631664, CSB=0x18000, HMAX=0x17e6c
            1800a: A[00]=[]   
---------------------------------------------------------
[0] >> 
@end example

By default, `@kbd{s}' will display the entire stack. If an argument is
given, this will be the number of records to display.

@node DisplayingTrail, DisplayingHeap, DisplayingStacksRegisters, Debugger
@comment  node-name,  next,  previous,  up
@appendixsec Displaying the Trail 
Trail entries are indented by 5 tabs and show the address and current contents
of that cell.  The most recent trail entry is displayed first. By default, the
entire trail is shown.  If an argument is given, only that number of entries
will be displayed.

@node DisplayingHeap, DisplayParameters, DisplayingTrail, Debugger
@comment  node-name,  next,  previous,  up
@appendixsec Displaying the Heap 
The heap is displayed by showing an address in square bracket followed by the
contents of that cell.  By default, the top 256 cells are displayed, or the
entire heap if less than 256 cells.  If an argument n is given, the top n
cells will be shown.

To examine a selected portion of the heap, use the `@kbd{m}' command. This
takes a start and end address, displaying all the cells in that range.

@node DisplayParameters, MiscellaneousCommands, DisplayingHeap, Debugger
@comment  node-name,  next,  previous,  up
@appendixsec Display Parameters 

There are three user-settable parameters to control the display of cells.
`@kbd{D}' controls the maximum depth of term to be displayed. The default
is a depth 10. This also controls how much of a long list or tuple is
shown. `@kbd{R}' controls how many argument registers and environment
variables to show. The default is 8 registers and no locals. The single
argument changes both. `@kbd{v}' toggles the verbose mode - whether to
display links and pointers. The debugger prompt changes to reflect whether
verbose mode is on.

@node MiscellaneousCommands,  , DisplayParameters, Debugger
@comment  node-name,  next,  previous,  up
@appendixsec Miscellaneous Commands 

To list all the relations which are referenced but not defined, use the
`@kbd{u}' command. This can be used to check whether all calls to a
predicate have the same arity.

The `@kbd{M}' command creates a list of predicate/arity and address pairs
in a file @file{memory.map}.

