-
Notifications
You must be signed in to change notification settings - Fork 5.8k
/
DebuggerWatchesPlugin.html
172 lines (131 loc) · 9.54 KB
/
DebuggerWatchesPlugin.html
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
168
169
170
171
172
<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">
<HTML>
<HEAD>
<META name="generator" content=
"HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">
<TITLE>Debugger: Watches</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
<LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
</HEAD>
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Watches</H1>
<DIV class="image">
<IMG alt="" src="images/DebuggerWatchesPlugin.png">
</DIV>
<P>Watches refer to expressions which are evaluated each pause in order to monitor the value of
variables in the target machine state. The watch variables are expressed in Sleigh and
evaluated in the current thread's context at the current point in time. If the current trace is
live and at the present, then the necessary target state is retrieved and recorded. The watch
can be assigned a data type so that the raw data is rendered in a meaningful way. When
applicable, that data type can optionally be applied to the trace database. Some metadata about
the watch is also given, e.g., the address of the value.</P>
<P>The watch window uses colors to hint about changes in and freshness of displayed values. By
default, changed values are displayed in red, and stale values are displayed in dark grey. A
<EM>stale</EM> value is one which depends on any register or memory whose contents are not
known. The value displayed is that computed from the last recorded contents, defaulting to 0
when never recorded. A <EM>changed</EM> watch is one whose value has just changed. For example,
if a value changes as result of stepping, then that watch is changed. However, given the
possibility of rewinding, changing thread focus, etc., "changed" is actually subtly more
flexible. The watch remembers the evaluation from the user's last coordinates (time, thread,
frame, etc.) as well as the current coordinates. So, "changed" more precisely refers to a watch
whose value differs between those two coordinates. This permits the user to switch focus
between different coordinates and quickly identify what is different.</P>
<H2>Examples</H2>
<P>For those less familiar with Sleigh, here are some example expressions:</P>
<UL>
<LI><CODE>RSP</CODE>: Display the value of register RSP.</LI>
<LI><CODE>*:4 0x7fff0004:8</CODE>: Display 4 bytes starting at ram:7fff0004, e.g., to read
the <CODE>int</CODE> at address 7fff0004. The extraneous but required size specifier on the
constant 0x7fff0004 is a known issue. Just use the target's pointer size in bytes — 8
in the example.</LI>
<LI><CODE>*:4 my_global</CODE>: Display 4 bytes starting at the label "my_global", e.g., to
read the <CODE>int</CODE> value there. The label may be in the trace or in a program mapped
to the trace. Ambiguities are resolved arbitrarily.</LI>
<LI><CODE>*:8 RSP</CODE>: Display 8 bytes of [ram] starting at the offset given by register
RSP, e.g., to read a <CODE>long</CODE> on the stack.</LI>
<LI><CODE>*:4 (RSP+8)</CODE>: Display 4 bytes of [ram] starting 8 bytes after the offset
given by register RSP, e.g., to read a <CODE>int</CODE> on the stack.</LI>
<LI><CODE>*:4 ((*:8 RSP)+4)</CODE>: Display 4 bytes of [ram] starting 4 bytes after the
offset given by reading 8 bytes of [ram] starting at the offset given by register RSP. This
might be used to read the second <CODE>int</CODE> of an array whose base pointer is on the
stack.</LI>
</UL>
<H2>Table Columns</H2>
<P>The table displays and allows modification of each watch. It has the following columns:</P>
<UL>
<LI>Expression - the user-modifiable Sleigh expression defining this watch.</LI>
<LI>Address - when evaluation succeeds, the address of the watch's value. This field is
really only meaningful when the outermost operator of the expression is a memory dereference.
Double-clicking this cell will navigate the primary dynamic listing to this address, if
possible.</LI>
<LI>Symbol - the symbol best representing the address, if applicable. When the watch has an
address in memory, this will search the trace for a symbol at that address, preferring the
primary. If no such symbol exists, it will search in the mapped static program, if there is
one, again preferring the primary symbol. Finally, it will search for a containing function
in the mapped program.</LI>
<LI>Value - the raw bytes of the watched buffer. If the expression is a register, then this
is its hexadecimal value. This field is user modifiable when the <B>Enable Edits</B> toggle
is on, and the variable is modifiable. Edits may be directed toward a live target, the trace,
or the emulator. If the value has changed since the last navigation event, this cell is
rendered in <FONT color="red">red</FONT>.</LI>
<LI>Type - the user-modifiable type of the watch. Note the type is not marked up in the
trace. Clicking the <A href="#apply_data_type">Apply Data Type</A> action will apply it to
the current trace, if possible.</LI>
<LI>Representation - the value of the watch as interpreted by the selected data type. If the
value is an address, i.e., Type is a pointer, then double-clicking this cell will navigate
the primary dynamic listing, if possible. This field is user-modifiable whenever the Value
column is modifiable and the selected data type provides an encoder.</LI>
<LI>Error - if an error occurs during compilation or evaluation of the expression, that error
is rendered here. Double-clicking the row will display the stack trace. Note that errors
during evaluation can be a very common occurrence, especially as contexts change, and should
not necessarily cause alarm. An expression devised for one context may not have meaning under
another, even if it evaluates without error. E.g., <CODE>RIP</CODE> will disappear when
switching to a 32-bit trace, or <CODE>*:8 (*:8 (RSP+8))</CODE> may cause an invalid
dereference when the stack pointer moves.</LI>
</UL>
<H2>Actions</H2>
<P>The watches window provides the following actions:</P>
<H3><A name="apply_data_type"></A>Apply Data to Listing</H3>
<P>This action is available when there's an active trace, and at least one watch with an
address and data type is selected. If so, it applies that data type to the value in the
listing. That is, it attempts to apply the selected data type to the evaluated address, sizing
it to the value's size.</P>
<H3><A name="type_settings"></A>Watch Type Settings</H3>
<P>This action is available on the context menu when there is a single watch selected with a
data type assigned. It permits the adjustment of that data type's settings, e.g., to display
decimal vs. hexadecimal.</P>
<H3><A name="select_addresses"></A>Select Range</H3>
<P>This action is available when there's an active trace, and at least one watch with memory
addresses is selected. It selects the memory range comprising the resulting value. This only
works when the outermost operator of the expression is a memory dereference. It selects the
range at the address of that dereference having the size of the dereference. For example, the
expression <CODE>*:8 RSP</CODE> would cause 8 bytes of memory, starting at the offset given by
RSP, to be selected in the dynamic listing.</P>
<H3><A name="select_reads"></A>Select Reads</H3>
<P>This action is available when there's an active trace, and at least one watch with memory
reads is selected. It selects all memory ranges dereferenced in the course of expression
evaluation. This can be useful when examining a watch whose value seems unusual. For example,
the expression <CODE>*:8 RSP</CODE> would cause 8 bytes of memory, starting at the offset given
by RSP, to be selected in the dynamic listing -- the same result as Select Range. However, the
expression <CODE>*:4 (*:8 RSP)</CODE> would cause two ranges to be selected: 8 bytes starting
at RSP and 4 bytes starting at the offset given by <CODE>*:8 RSP</CODE>.</P>
<H3><A name="add"></A>Add</H3>
<P>This action is always available. It adds a blank watch to the table. Modify the expression
to make the entry useful.</P>
<H3><A name="watch"></A>Watch</H3>
<P>This action is available in context menus for addresses, selections, or registers. It adds
the selected item(s) to the watch table. If the context is derived from a static view, it first
attempts to map it to the current trace. For selections, it adds a typeless watch for each
range. For single-address locations derived from a listing, it adds a typed watch on the
current code unit. For other single-address locations, it adds a 1-byte typeless watch on the
address. For registers, it adds a watch on that register. Note that <CODE>contextreg</CODE> and
its children cannot be watched, due to a limitation in Sleigh.</P>
<H3><A name="remove"></A>Remove</H3>
<P>This action is available when at least one watch is selected. It removes those watches.</P>
<H3><A name="enable_edits"></A>Enable Edits</H3>
<P>This toggle is a write protector for machine state. To modify a watch's value, this toggle
must be enabled. Edits are directed according the to <A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">Control and Machine State
Plugin</A>.</P>
</BODY>
</HTML>