OpenBoot provides debugging tools that include a Forth language decompiler, a machine language disassembler, register display commands, a symbolic debugger, breakpoint commands, a Forth source level debugger, a high-level language patching facility and exception tracing. This chapter describes the capabilities specified by IEEE Standard 1275-1994.
The built-in Forth language decompiler can be used to recreate the source code for any previously-defined Forth word. The command:
--------------------
ok see old-name --------------------
displays a listing of the source for old-name (without the source comments, of course).
A companion to see is (see) which is used to decompile the Forth word whose execution token is taken from the stack. For example:
--------------------------
ok ' old-name (see) --------------------------
(see) produces a listing in a format identical to see.
--------------------------------------------------------------------------
ok see see : see ' ['] (see) catch if drop then ; ok see (see) defer (see) is : (f0018a44) 40 rmargin ! dup dup (f00189c4) dup (f0018944) (f0018980) (f0018658) ??cr ; ok f0018a44 (see) : (f0018a44) 40 rmargin ! dup dup (f00189c4) dup (f0018944) (f0018980) (f0018658) ??cr ; --------------------------------------------------------------------------
The preceding listing shows that:
For words implemented in Forth assembler language, see displays a Forth assembler listing. For example, decompiling dup displays:
-------------------------------------------
ok see dup code dup f0008c98 sub %g7, 8, %g7 f0008c9c stx %g4, [%g0 + %g7] f0008ca0 ld [%g5], %l0 f0008ca4 jmp %l0, %g2, %g0 f0008ca8 add %g5, 4, %g5 -------------------------------------------
The built-in disassembler translates the contents of memory into equivalent assembly language.
Table 47 lists commands that disassemble memory into equivalent opcodes.
Table 47 Disassembler Commands
------------------------------------------------------------------------------------
Command Stack Diagram Description ------------------------------------------------------------------------------------
+dis ( -- ) Continue disassembling where the last disassembly left off.
dis ( addr -- ) Begin disassembling at the specified address.
------------------------------------------------------------------------------------
dis begins to disassemble the data content of any desired location. The system pauses when:
Disassembly can then be stopped or the +dis command can be used to continue disassembling at the location where the last disassembly stopped.
Memory addresses are normally shown in hexadecimal. However, if a symbol table is present, memory addresses are displayed symbolically whenever possible.
You can enter the User Interface from the middle of an executing program as a result of a program crash, a user abort, or an encountered breakpoint. (Breakpoints are discussed on page 104.) In all these cases, the User Interface automatically saves all the CPU data register values in a buffer area. These values can then be inspected or altered for debugging purposes.
Table 48 lists the SPARC register commands.
Table 48 SPARC Register Commands
------------------------------------------------------------------------------------------------------
Command Stack Diagram Description ------------------------------------------------------------------------------------------------------
%g0 through %g7 ( -- value ) Return the value in the specified global register.
%i0 through %i7 ( -- value ) Return the value in the specified input register.
%l0 through %l7 ( -- value ) Return the value in the specified local register.
%o0 through %o7 ( -- value ) Return the value in the specified output register.
%pc %npc %y ( -- value ) Return the value in the specified register.
%f0 through %f31 ( -- value ) Return the value in the specified floating point register.
.fregisters ( -- ) Display the values in %f0 through %f31.
.locals ( -- ) Display the values in the i, l and o registers.
.registers ( -- ) Display values in processor registers.
.window ( window# -- ) Same as w .locals; display the desired window.
ctrace ( -- ) Display the return stack showing C subroutines.
set-pc ( new-value -- ) Set %pc to new-value, and set %npc to (new-value+4).
to regname ( new-value -- ) Change the value stored in any of the above registers.
Use in the form: new-value to regname.
w ( window# -- ) Set the current window for displaying %ix, %lx, or %ox.
------------------------------------------------------------------------------------------------------
Table 49 SPARC V9 Register Commands
---------------------------------------------------------------------------------
Command Stack Diagram Description ---------------------------------------------------------------------------------
%fprs ( -- value ) Return the value in the specified register
%asi
%pstate
%tl-c
%pil
%tstate
%tt
%tba
%cwp
%cansave
%canrestore
%otherwin
%wstate
%cleanwin
.pstate ( -- ) Formatted display of the processor state register
.ver ( -- ) Formatted display of the version register
.ccr ( -- ) Formatted display of the %ccr register
.trap-registers ( -- ) Display trap-related registers
---------------------------------------------------------------------------------
The values of all of these registers are saved and can be altered with to. After the values have been inspected and/or modified, program execution can be continued with the go command. The saved (and possibly modified) register values are copied back into the CPU, and execution resumes at the location specified by the saved program counter.
If you change %pc with to, you should also change %npc. (It is easier to use set-pc, which changes both registers automatically.)
For the w and .window commands, a window value of 0 usually specifies the current window - that is, the active window for the subroutine where the program was interrupted. A value of 1 specifies the window for the caller of this subroutine, 2 specifies the caller's caller, and so on, up to the number of active stack frames. The default starting value is 0.
The User Interface provides a breakpoint capability to assist in the development and debugging of stand-alone programs. (Programs that run over the operating system generally do not use this OpenBoot feature, but use other debuggers designed to run with the operating system.) The breakpoint feature lets you stop the program under test at desired points. After program execution has stopped, registers or memory can be inspected or changed, and new breakpoints can be set or cleared. You can resume program execution with the go command.
Table 50 lists the breakpoint commands that control and monitor program execution.
Table 50 Breakpoint Commands
---------------------------------------------------------------------------------------------------------
Command Stack Diagram Description ---------------------------------------------------------------------------------------------------------
+bp ( addr -- ) Add a breakpoint at the specified address.
-bp ( addr -- ) Remove the breakpoint at the specified address.
--bp ( -- ) Remove the most-recently-set breakpoint.
.bp ( -- ) Display all currently set breakpoints.
.breakpoint ( -- ) Perform a specified action when a breakpoint occurs. This word can be
altered to perform any desired action. For example, to display registers at
every breakpoint, type: ['] .registers to .breakpoint. The default
behavior is .instruction. To perform multiple behaviors, create a single
definition which calls all desired behaviors, then load that word into
.breakpoint.
.instruction ( -- ) Display the address, opcode for the last-encountered breakpoint.
.step ( -- ) Perform a specified action when a single step occurs (see .breakpoint).
bpoff ( -- ) Remove all breakpoints.
finish-loop ( -- ) Execute until the end of this loop.
go ( -- ) Continue from a breakpoint. This can be used to go to an arbitrary address
by setting up the processor's program counter before issuing go.
gos ( n -- ) Execute go n times.
hop ( -- ) (Like the step command.) Treat a subroutine call as a single instruction.
hops ( n -- ) Execute hop n times.
return ( -- ) Execute until the end of this subroutine.
returnl ( -- ) Execute until the end of this leaf subroutine.
skip ( -- ) Skip (do not execute) the current instruction.
step ( -- ) Single-step one instruction.
steps ( n -- ) Execute step n times.
till ( addr -- ) Execute until the given address is encountered. Equivalent to +bp go.
---------------------------------------------------------------------------------------------------------
To debug a program using breakpoints, use the following procedure.
See Chapter 5, "Loading and Executing Programs" for more information. The register values are initialized automatically.
You can also set a breakpoint, then execute (for example, using the commands addr +bp and go) or perform other variations.
The Forth Source-level Debugger allows single-stepping and tracing of Forth programs. Each step represents the execution of one Forth word.
The debugger commands are shown in Table 51.
Table 51 Forth Source-level Debugger Commands
----------------------------------------------------------------------------------------------------------------
Command Description ----------------------------------------------------------------------------------------------------------------
c "Continue". Switch from stepping to tracing, thus tracing the remainder of the execution of the
word being debugged.
d "Down a level". Mark for debugging the word whose name was just displayed, then execute it.
u "Up a level". Un-mark the word being debugged, mark its caller for debugging, and finish
executing the word that was previously being debugged.
f Start a subordinate Forth interpreter with which Forth commands can be executed normally.
When that interpreter is terminated (with resume), control returns to the debugger at the place
where the f command was executed.
g "Go." Turn off the debugger and continue execution.
q "Quit". Abort the execution of the word being debugged and all its callers and return to the
command interpreter.
s "see". Decompile the word being debugged.
$ Display the address,len on top of the stack as a text string.
h "Help". Display symbolic debugger documentation.
? "Short Help". Display brief symbolic debugger documentation.
debug name Mark the specified Forth word for debugging. Enter the Forth Source-level Debugger on all
subsequent attempts to execute name. After executing debug, the execution speed of the
system may decrease until debugging is turned off with debug-off. (Do not debug basic
Forth words such as ".".)
(debug Like debug except that (debug takes an execution token from the stack instead of a name from
the input stream.
debug-off Turn off the Forth Source-level Debugger so that no word is being debugged.
resume Exit from a subordinate interpreter, and go back to the stepper (See the f command in this
table).
stepping Set "step mode" for the Forth Source-level Debugger, allowing the interactive, step-by-step
execution of the word being debugged. Step mode is the default.
tracing Set "trace mode" for the Forth Source-level Debugger. Tracing enables the execution of the
word being debugged, while showing the name and stack contents for each word called by
that word.
<space- Execute the word just displayed and proceed to the next word.
bar'>
----------------------------------------------------------------------------------------------------------------
Every Forth word is defined as a series of one or more words that could be called "component" words. While debugging a specified word, the debugger displays information about the contents of the stack while executing each of the word's "component" words. Immediately before executing each component word, the debugger displays the contents of the stack and the name of the component word that is about to be executed.
In trace mode, that component word is then executed, and the process continues with the next component word.
In step mode (the default), the user controls the debugger's execution behavior. Before the execution of each component word, the user is prompted for one of the keystrokes specified in Table 51.
OpenBoot provides the ability to change the definition of a previously compiled Forth word using high-level Forth language. While the changes will typically be made in the appropriate source code, the patch facility provides a means of quickly correcting errors uncovered during debugging.
patch reads the input stream for the following information:
For example, consider the following example in which the word test is replaced with the number 555:
-------------------------------------------
ok : patch-me test 0 do i . cr loop ; ok patch 555 test patch-me ok see patch-me : patch-me h# 555 0 do i . cr loop ; -------------------------------------------
When using patch, some care must be taken to select the right word to replace. This is especially true if the word you are replacing is used several times within the target word and the occurrence of the word that you want to replace is not the first occurrence within the target word. In such a case, some subterfuge is required.
-----------------------------------------------------------------
ok : patch-me2 dup dup dup ( This third dup should be drop) ; ok : xx dup ; ok patch xx dup patch-me2 ok patch xx dup patch-me2 ok patch drop dup patch-me2 ok see patch-me2 : patch-me2 xx xx drop ; -----------------------------------------------------------------
Another use for patch is the case where the word to be patched contains some functionality that needs to be completely discarded. In this case, the word exit should be patched over the first word whose functionality is to be eliminated. For example, consider a word whose definition is:
-------------------------------
ok : foo good bad unneeded ; -------------------------------
In this example, the functionality of bad is incorrect and the functionality of unneeded should be discarded. A first attempt to patch foo might be:
------------------------------
ok : right this that exit ; ok patch right bad foo ------------------------------
on the expectation that the use of exit in the word right would prevent the execution of unneeded. Unfortunately, exit terminates the execution of the word which contains it, in this case right. The correct way to patch foo is:
--------------------------------
ok : right this that ; ok patch right bad foo ok patch exit unneeded foo --------------------------------
(patch) is similar to patch except that (patch) obtains its arguments from the stack. The stack diagram for (patch) is:
( new-n1 num1? old-n2 num2? xt -- )
where:
For example, consider the following example in which we reverse the affect of our first patch example by replacing the number 555 with test:
-------------------------------------------
ok see patch-me : patch-me h# 555 0 do i . cr loop ; ok ['] test false 555 true ['] patch-me (patch) ok see patch-me : patch-me test 0 do i . cr loop ; -------------------------------------------
The ftrace command shows the sequence of Forth words that were being executed at the time of the last exception. An example of ftrace follows.
---------------------------------------------------
ok : test1 1 ! ; ok : test2 1 test1 ; ok test2 Memory address not aligned ok ftrace ! Called from test1 at ffeacc5c test1 Called from test2 at ffeacc6a (ffe8b574) Called from (interpret at ffe8b6f8 execute Called from catch at ffe8a8ba ffefeff0 0 ffefebdc catch Called from (fload) at ffe8ced8 0 (fload) Called from interact at ffe8cf74 execute Called from catch at ffe8a8ba ffefefd4 0 ffefebdc catch Called from (quit at ffe8cf98 ---------------------------------------------------
In this example, test2 calls test1, which tries to store a value to an unaligned address. This results in the exception: Memory address not aligned.
The first line of ftrace's output shows the last command that caused the exception to occur. The next lines show locations from which the subsequent commands were being called.
The last few lines are usually the same in any ftrace output, because that is the calling sequence in effect when the Forth interpreter interprets a word from the input stream.
