From 8bd4ea05c8fcc05c91565b65f3caf8ff511edfcb Mon Sep 17 00:00:00 2001
From: Blue Swirl <blauwirbel@gmail.com>
Date: Sun, 15 Nov 2009 21:19:59 +0000
Subject: [PATCH] Document the debugger

Add a description of the debug syntax and run-time use, with an
example of a debugging session.

Signed-off-by: Blue Swirl <blauwirbel@gmail.com>

git-svn-id: svn://coreboot.org/openbios/trunk/openbios-devel@612 f158a5a8-5612-0410-a976-696ce0be7e32
---
 Documentation/README.debugger | 50 +++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 Documentation/README.debugger

diff --git a/Documentation/README.debugger b/Documentation/README.debugger
new file mode 100644
index 0000000..a44f5a8
--- /dev/null
+++ b/Documentation/README.debugger
@@ -0,0 +1,50 @@
+The following Forth words can be used for debugging:
+
+   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
+
+An example session:
+0 > see boot 
+: boot
+  linefeed parse cr " platform-boot" $find if
+  execute then
+  2drop cr " Booting " type type cr "   ... not supported on this system." type cr
+  ;
+ ok
+0 > debug boot 
+Stepper keys: <space>/<enter> Up Down Trace Rstack Forth
+ ok
+0 > boot 
+: boot  ( Empty ) 
+00000000ffe26b08: linefeed  ( a ) 
+00000000ffe26b10: parse  ( ffec6e24 0 ) 
+00000000ffe26b18: cr 
+ ( ffec6e24 0 ) 
+00000000ffe26b20: (")  ( ffec6e24 0 ffe26b30 d ) 
+00000000ffe26b40: $find  ( ffec6e24 0 ffe31710 ffffffffffffffff ) 
+00000000ffe26b48: do?branch  ( ffec6e24 0 ffe31710 ) 
+00000000ffe26b58: execute [sparc64] Booting file 'cdrom' with parameters ''
+Not a bootable ELF image
+Not a Linux kernel image
+Not a bootable a.out image
+Loading FCode image...
+Loaded 5936 bytes
+entry point is 0x4000
+Evaluating FCode...
+open isn't unique.
+Boot load failed.
+ ( Empty ) 
+00000000ffe26b60: dobranch  ( Empty ) 
+00000000ffe26bf8: (semis) 
+[ Finished boot ]  ok
+0 >