1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
@node Debugging, Additional documentation requirements, Using block files, Top
@chapter Debugging
@cindex Debugging
@menu
* Inspecting::
* Single Stepping::
@end menu
@node Inspecting, Single Stepping, Debugging, Debugging
@section Inspecting
ANS Forth defines some "Programming Tools", words to inspect the stack,
memory, compiled code and what words are defined.
@ftable @samp
@item .S ( -- )
displays the stacks. There are two stacks: integer and floating point.
@itemize @bullet
@item
If both stacks are empty @samp{.S} display the message
@samp{<stacks empty>}.
@item
If only the floating point stack is empty, @samp{.S} displays the
integer stack items in one column, one item per line, both in hex and in
decimal like this:
@example
12345 HEX 67890 ok
.S
424080 [00067890]
12345 [00003039] ok
@end example
the first line shows the topmost item.
@item
If both stacks are not empty, @samp{.S} displays both stacks, in two
columns, one item per line:
@example
HEX 123456.78E90 ok
DECIMAL 123456.78E90 ok
.S
291 [00000123] 1.234568E+95
1164414608 [45678E90] ok
@end example
Confusing example? Remember that floating point input only works when
the number base is decimal. The first number looks like a floating point
number but is a good hex double integer too. Number base is hex. Thus it
is accepted as hex number. Second try with decimal inputs the floating
point number.
@item
If only the integer stack is empty, @samp{.S} shows two columns: The
first column is just @samp{<stack empty>}, the second column is the
floating point stack, topmost item first:
@example
D. 1250999897744 ok
.S
<stack empty> 1.234568E+95 ok
@end example
@end itemize
@item ? ( addr -- )
Displays the integer at address @i{addr}, equivalent to @samp{@ .}, thus
sensitive to @samp{BASE}.
@item DUMP ( addr u -- )
Displays @i{u} bytes of memory starting at address @i{addr}. You can
easily cause a segmentation fault or something like that by accessing
memory that doesn't belong to the pfe-process.
@item SEE ( ``spaces name'' -- )
decompiles the following word trying to display a reasonable indented
source text. If you define your own control structures or use extended
control-flow patterns, the indentation may be suboptimal.
@item WORDS ( -- )
@end ftable
@node Single Stepping, , Inspecting, Debugging
@section Single stepping
@cindex single stepping
@b{pfe} includes a simple debugging and profiling facility: You can
single step though a definition after saying @samp{DEBUG definition}.
Next time the @samp{definition} gets executed the single stepper takes
control.
When this happens you see the top stack items displayed in one line. The
topmost stack item is the first in line, the second and following stack
items are displayed throughout the end of the line. This line is empty
if the stack is empty when the word in question executes.
On the next line you see the first word to become executed inside
@samp{definition}.
@menu
* Single Stepper keys::
@end menu
@node Single Stepper keys, , Single Stepping, Single Stepping
@subsection Single Stepper Keys
You see a prompt @samp{>} right of the first displayed word. At this
prompt you have several options. Choose one by typing one key:
@itemize @bullet
@item
@samp{Enter}, @samp{x}, @samp{k} or @samp{Arrow down}: The displayed
word will be executed without single stepping. Note that the execution
of the word is slowed down a little compared to execution outside the
single stepper. This is because the single stepper has to keep control
to detect when the word is finished.
After the actual word finished execution the resulting stack is printed
on the current line. The next line shows the next next word to become
executed.
Having repeated this step several times, you can see to the right of
every decompiled word what changes to the stack this word caused by
comparing with the stack display on the line above.
@item
@samp{d} or @samp{l} or @samp{Arrow right}: Begin single step execution
of the actual word. The first word to become executed inside the
definiton is displayed on the next line. The word's display is indented
by two spaces for each nesting level.
You can single step through colon-definitions and the children of
defining words. You can single step only loaded words, i.e. none of the
kernel words.
@item
@samp{s} or @samp{j} or @samp{Arrow left}: Leaves a nesting level. The
rest of the definition currently executed stepwise becomes executed
fast. If you leave the outmost level, the single stepper won't get
control again. Otherwise the debugger stops after the current word is
finished and offers the next word in the next lower nesting level.
@item
@samp{space}: The next word to be executed is decompiled. This helps you
to decide if you want to single step that word.
@item
@samp{q}: Quits from the debugger. The execution of the debugged word is
not continued. The stacks are not cleared or changed.
@item
@samp{h}: Displays a summary of the available keys.
@item
@samp{r}: Profiling: Resets the instruction counter. The debugger counts
how often the inner interpreter i.e. how many Forth-primitives become
executed. Using this option you can anytime reset this counter to 0 to
measure an arbitrary part of code.
@item
@samp{c} Profiling: Displays the instruction counter.
@end itemize
|
