PATCH: Reworked version of Forth Source debugger

[Mark Cave-Ayland]

Hi everyone,

Please find attached the latest version of my Forth source debugger 
patch which I believe is ready for commit review. This patch implements 
the following Forth words:

debug <xt> - Mark word for debugging
     debug-off  - Unmark all words for debugging
     resume     - Return from subordinate Forth interpreter

The source debugger also implements the following commands when it has 
been activated:

Up - Unmark current word for debugging, mark parent and continue
     Down - Mark next word for debugging
     Trace - Continue execution until end of word displaying
             debug information
     Rstack - Display contents of the Rstack
     Forth - Launch subordinate Forth interpreter

The patch has been reworked in its current form to minimise the impact 
the debugger has on the performance of the Forth kernel by changing the 
"runforth" flag to an "interruptforth" bitmask. If interruptforth is 0 
then execution continues as normal; if interruptforth is non-zero then 
we should behave accordingly.

Currently two interruptforth bitmasks are defined:

FORTH_INTSTAT_STOP - The interpreter should stop immediately
    FORTH_INTSTAT_DBG - The debugger should be enabled/disabled
                             depending upon the contents of the global
                             debug xt list.

The main loop of enterforth() has now been changed to be a nested while 
loop which either launches next() or next_dbg() depending upon whether 
any breakpoints have been set. Since the majority of the execution time 
is spent within the inner loop, then the only change is a small penalty 
incurred whilst calling enterforth().

The reason the patch has been designed to work by intercepting the PC 
within next() is because several Forth words within OpenBIOS will pop 
items from the rstack before pushing a new one. Hence a debugger which 
uses the Rstack to determine whether or debug should be enabled will 
always fail on these words since any extra debugging context would be lost.

I've measured the performance on my laptop here, and interestingly 
enough I now get better performance with the patch rather than without, 
which I guess is due to some compiler optimisation that the new nested 
loops can invoke.

Current SVN benchmark (40th Fibonacci number):

build@zeno:~/src/openbios/openbios-devel$ time echo "28 fib-rec u. bye" 
| ./obj-x86/openbios-unix ./obj-x86/openbios-x86.dict
Welcome to OpenBIOS v1.0 built on Nov 14 2009 12:37
   Type 'help' for detailed information

[unix] Booting default not supported.

0 > 28 fib-rec u. bye 6197ecb
Farewell!

ok

real    0m52.724s
user    0m52.395s
sys     0m0.316s

Current SVN + source debugger patch (40th Fibonacci number):

build@zeno:~/src/openbios/openbios-devel.tst$ time echo "28 fib-rec u. 
bye" | ./obj-x86/openbios-unix ./obj-x86/openbios-x86.dict
Welcome to OpenBIOS v1.0 built on Nov 14 2009 12:39
   Type 'help' for detailed information

[unix] Booting default not supported.

0 > 28 fib-rec u. bye 6197ecb
Farewell!

ok

real    0m48.880s
user    0m48.519s
sys     0m0.188s

Since the last version, I've also included the code tested by 
myself/Laurent to ensure that the debugger works on a graphical display 
and tidied up all outstanding compilation warnings.

ATB,

Mark.

[Blue Swirl]

On Sat, Nov 14, 2009 at 3:16 PM, Mark Cave-Ayland
 wrote:
> Hi everyone,
>
> Please find attached the latest version of my Forth source debugger patch
> which I believe is ready for commit review. This patch implements the
> following Forth words:
>
> debug <xt> - Mark word for debugging
>    debug-off  - Unmark all words for debugging
>    resume     - Return from subordinate Forth interpreter
>
> The source debugger also implements the following commands when it has been
> activated:
>
> Up - Unmark current word for debugging, mark parent and continue
>    Down - Mark next word for debugging
>    Trace - Continue execution until end of word displaying
>            debug information
>    Rstack - Display contents of the Rstack
>    Forth - Launch subordinate Forth interpreter

Nice work! This passes my tests and I didn't see any performance problems.

I know we don't have much user documentation, but I think the debugger
deserves something (for example your description above). Otherwise the
users won't find this. The documentation can be added later, though.