From be98e1ae3decabdd852fbe6496166aaa9acfbf9e Mon Sep 17 00:00:00 2001 From: "Pedro F. Giffuni" Date: Tue, 12 May 2015 02:36:33 +0000 Subject: Bring ficl to the vendor area. We currently use ficl3 in ~sys/boot/ficl but it has a bunch of local changes. WWW: http://ficl.sourceforge.net/ Discussed with: dteske, mr --- doc/ficl_debug.html | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 doc/ficl_debug.html (limited to 'doc/ficl_debug.html') diff --git a/doc/ficl_debug.html b/doc/ficl_debug.html new file mode 100644 index 000000000000..647b7b27a8d0 --- /dev/null +++ b/doc/ficl_debug.html @@ -0,0 +1,111 @@ + + + + + Ficl Debugger + + + +

Ficl Debugger

+ + + + + + + +
+

Ficl release 2.05 includes a simple step debugger for colon definitions +and does> words. If you use it and can suggest improvements (or better +yet if you write some), please let me know.

+

Using the debugger

+To debug a word, set up the stack with any parameters the word requires, +then type: + +
debug <your word here>
 + +

If the word is unnamed, or all you have is an xt, you can instead use:

+debug-xt ( xt -- ) +

The debugger invokes see on the word, printing a crude source +listing, then stops at the first instruction of the definition. There are +four (case insensitive) commands you can use from here onwards:

+ +
+
I (step in)
+
If the next instruction is a colon defintion or does> word, steps into +that word's code. If the word is a primitive, simply executes the word.
+ +
O (step over)
+
Executes the next instruction in its entirety
+ +
G (go)
+
Run the word to completion and exit the debugger
+ +
L (list)
+
Lists the source code of the word presently being stepped
+ +
Q (quit)
+
Abort the word and exit the debugger, clearing the stack
+ +
X (eXecute)
+
Interpret the remainder of the line as ficl words for their side effects. +Any errors will abort the debug session and reset the VM. Usage example: +
+x drop 3 \ fix argument on stack
+
+
+ +
Anything else
+
Prints a list of available debugger commands
+
+ +

The on-step event

+

If there is a defined word named on-step when the debugger starts, that +word will be executed before every step. As a guideline, this word should +have no side effects. Its intended use is to display the stacks and any other +VM state you're interested in, but you +may have some better ideas. If so, please let me know. The default on-step is:

+: on-step ." S: " .s cr ; + +

Other useful words for debugging and on-step

+
+
r.s ( -- )
+
Prints a represention of the state of the return stack non-destructively. You have to have +a good understanding of the return stack side-effects of control words to make sense of it, +but it does give an accurate representation of what's there. Example: DO .. LOOPs stack +three parameters on the return stack: the loop count and limit, and the LEAVE target +address.
+
.s ( -- )
+
Prints the parameter stack non-destructively
+
f.s ( -- )
+
Prints the float stack non-destructively (only available if FICL_WANT_FLOAT is enabled)
+
+

Debugger internals

+

+The debugger words are mostly located in source file tools.c. There are +supporting words (debug and on-step) in softcore.fr as well. +There are two main words that make the debugger go: debug-xt and step-break. +Debug-xt takes the xt of a word to debug (as returned by ', for example) +checks to see if it is debuggable (not a primitive), sets a breakpoint at its +first instruction, and runs see on it. To set a breakpoint, +debug-xt +replaces the instruction at the breakpoint with the xt of step-break, and +stores the original instruction and its address in a static breakpoint +record. To clear the breakpoint, step-break simply replaces the original +instruction and adjusts the target virtual machine's instruction pointer +to run it. +

+

Step-break is responsible for processing debugger commands and setting +breakpoints at subsequent instructions.

+

To Do

+ +
  • The debugger needs to exit automatically when it encounters the end of the word +it was asked to debug. Perhaps this could be a special kind of breakpoint? +
    • +
  • Add user-set breakpoints
    • +
  • Add "step out" command
    • +     +
    + + + -- cgit v1.2.3