From f4e75c6395310fa4b119d3eaa9a4a9f8913df200 Mon Sep 17 00:00:00 2001 From: "Pedro F. Giffuni" Date: Tue, 12 May 2015 03:27:06 +0000 Subject: Update to ficl 4.1.0 (latest release on sourceforge) --- doc/ficl_debug.html | 111 ---------------------------------------------------- 1 file changed, 111 deletions(-) delete mode 100644 doc/ficl_debug.html (limited to 'doc/ficl_debug.html') diff --git a/doc/ficl_debug.html b/doc/ficl_debug.html deleted file mode 100644 index 647b7b27a8d0..000000000000 --- a/doc/ficl_debug.html +++ /dev/null @@ -1,111 +0,0 @@ - - - - - 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.3