forked from llvm/llvm-project
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathformats.html
executable file
·303 lines (249 loc) · 20 KB
/
formats.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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link href="style.css" rel="stylesheet" type="text/css" />
<title>LLDB Stack and Frame Formats</title>
</head>
<body>
<div class="www_title">
The <strong>LLDB</strong> Debugger
</div>
<div id="container">
<div id="content">
<!--#include virtual="sidebar.incl"-->
<div id="middle">
<div class="post">
<h1 class ="postheader">Stack Frame and Thread Format</h1>
<div class="postcontent">
<p>LLDB has a facility to allow users to define the
format of the information that generates the descriptions
for threads and stack frames. Typically when your program stops
at a breakpoint you will get two lines that describes why
your thread stopped and where:</p>
<p><b><code>* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
<br>   frame #0: test`main at test.c:5
</b></p>
<p>Stack backtraces frames also have a similar information line:</p>
<p><code><b>(lldb)</b> thread backtrace
<br><b>* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
<br> frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
<br> frame #1: 0x0000000100000e40 a.out`start + 52
</code></b></p>
<p>The two format strings that govern the printing in these output forms can currently be set using the <b>settings set</b> command:</p>
<p><code><b>(lldb)</b> settings set thread-stop-format STRING
<br><b>(lldb)</b> settings set frame-format STRING
</p></code>
<p>The first of these is an abbreviated thread output, that just contains data about
the thread, and not the stop frame. It will always get used in situations where the
frame output follows immediately, so that information would be redundant. The second
is the frame printing.
</p>
<p>
There is another thread format used for commands like <code>thread list</code> where
the thread information isn't followed by frame info. In that case, it is convenient to have
frame zero information in the thread output. That format is set by:</p>
</p>
<p><code><b>(lldb)</b> settings set thread-format STRING
</p></code>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class ="postheader">Format Strings</h1>
<div class="postcontent">
<p>So what is the format of the format strings? Format strings can
contain plain text, control characters and variables that have access
to the current program state.</p>
<p>Normal characters are any text that doesn't contain a <code><b>'{'</b></code>, <code><b>'}'</b></code>, <code><b>'$'</b></code>,
or <code><b>'\'</b></code> character.</p>
<p>Variable names are found in between a <code><b>"${"</b></code> prefix, and
end with a <code><b>"}"</b></code> suffix. In other words, a variable looks like
<code>"<b>${frame.pc}</b>"</code>.</p>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class ="postheader">Variables</h1>
<div class="postcontent">
<p>A complete list of currently supported format string variables is listed below:</p>
<table border="1">
<tr valign=top><td><b>Variable Name</b></td><td><b>Description</b></td></tr>
<tr valign=top><td><b>file.basename</b></td><td>The current compile unit file basename for the current frame.</td></tr>
<tr valign=top><td><b>file.fullpath</b></td><td>The current compile unit file fullpath for the current frame.</td></tr>
<tr valign=top><td><b>language</b></td><td>The current compile unit language for the current frame.</td></tr>
<tr valign=top><td><b>frame.index</b></td><td>The frame index (0, 1, 2, 3...)</td></tr>
<tr valign=top><td><b>frame.no-debug</b></td><td>Evaluates to true if the frame has no debug info.</td></tr>
<tr valign=top><td><b>frame.pc</b></td><td>The generic frame register for the program counter.</td></tr>
<tr valign=top><td><b>frame.sp</b></td><td>The generic frame register for the stack pointer.</td></tr>
<tr valign=top><td><b>frame.fp</b></td><td>The generic frame register for the frame pointer.</td></tr>
<tr valign=top><td><b>frame.flags</b></td><td>The generic frame register for the flags register.</td></tr>
<tr valign=top><td><b>frame.reg.NAME</b></td><td>Access to any platform specific register by name (replace <b>NAME</b> with the name of the desired register).</td></tr>
<tr valign=top><td><b>function.name</b></td><td>The name of the current function or symbol.</td></tr>
<tr valign=top><td><b>function.name-with-args</b></td><td>The name of the current function with arguments and values or the symbol name.</td></tr>
<tr valign=top><td><b>function.name-without-args</b></td><td>The name of the current function without arguments and values (used to include a function name in-line in the <tt>disassembly-format</tt>)</td></tr>
<tr valign=top><td><b>function.pc-offset</b></td><td>The program counter offset within the current function or symbol</td></tr>
<tr valign=top><td><b>function.addr-offset</b></td><td>The offset in bytes of the current function, formatted as " + dddd"</td></tr>
<tr valign=top><td><b>function.concrete-only-addr-offset-no-padding</b></td><td>Similar to <b>function.addr-offset</b> except that there are no spaces in the output (e.g. "+dddd") and the offset is computed from the nearest concrete function -- inlined functions are not included</td></tr>
<tr valign=top><td><b>function.changed</b></td><td>Will evaluate to true when the line being formatted is a different symbol context from the previous line (may be used in <tt>disassembly-format</tt> to print the new function name on a line by itself at the start of a new function). Inlined functions are not considered for this variable</td></tr>
<tr valign=top><td><b>function.initial-function</b></td><td>Will evaluate to true if this is the start of the first function, as opposed to a change of functions (may be used in <tt>disassembly-format</tt> to print the function name for the first function being disassembled)</td></tr>
<tr valign=top><td><b>line.file.basename</b></td><td>The line table entry basename to the file for the current line entry in the current frame.</td></tr>
<tr valign=top><td><b>line.file.fullpath</b></td><td>The line table entry fullpath to the file for the current line entry in the current frame.</td></tr>
<tr valign=top><td><b>line.number</b></td><td>The line table entry line number for the current line entry in the current frame.</td></tr>
<tr valign=top><td><b>line.start-addr</b></td><td>The line table entry start address for the current line entry in the current frame.</td></tr>
<tr valign=top><td><b>line.end-addr</b></td><td>The line table entry end address for the current line entry in the current frame.</td></tr>
<tr valign=top><td><b>module.file.basename</b></td><td>The basename of the current module (shared library or executable)</td></tr>
<tr valign=top><td><b>module.file.fullpath</b></td><td>The basename of the current module (shared library or executable)</td></tr>
<tr valign=top><td><b>process.file.basename</b></td><td>The basename of the file for the process</td></tr>
<tr valign=top><td><b>process.file.fullpath</b></td><td>The fullname of the file for the process</td></tr>
<tr valign=top><td><b>process.id</b></td><td>The process ID native to the system on which the inferior runs.</td></tr>
<tr valign=top><td><b>process.name</b></td><td>The name of the process at runtime</td></tr>
<tr valign=top><td><b>thread.id</b></td><td>The thread identifier for the current thread</td></tr>
<tr valign=top><td><b>thread.index</b></td><td>The unique one based thread index ID which is guaranteed to be unique as threads come and go.</td></tr>
<tr valign=top><td><b>thread.name</b></td><td>The name of the thread if the target OS supports naming threads</td></tr>
<tr valign=top><td><b>thread.queue</b></td><td>The queue name of the thread if the target OS supports dispatch queues</td></tr>
<tr valign=top><td><b>thread.stop-reason</b></td><td>A textual reason each thread stopped</td></tr>
<tr valign=top><td><b>thread.return-value</b></td><td>The return value of the latest step operation (currently only for step-out.)</td></tr>
<tr valign=top><td><b>thread.completed-expression</b></td><td>The expression result for a thread that just finished an interrupted expression evaluation.</td></tr>
<tr valign=top><td><b>target.arch</b></td><td>The architecture of the current target</td></tr>
<tr valign=top><td><b>script.target:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr>
<tr valign=top><td><b>script.process:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr>
<tr valign=top><td><b>script.thread:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr>
<tr valign=top><td><b>script.frame:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr>
<tr valign=top><td><b>current-pc-arrow</b></td><td>Prints either '<tt>-> </tt>' or '<tt> </tt>' if the current pc value is matched (used in <tt>disassembly-format</tt>)</td></tr>
<tr valign=top><td><b>addr-file-or-load</b></td><td>Formats an address either as a load address, or if process has not yet been launched, as a load address (used in <tt>disassembly-format</tt>)</td></tr>
</table>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class ="postheader">Control Characters</h1>
<div class="postcontent">
<p>Control characters include <b><code>'{'</code></b>,
<b><code>'}'</code></b>, and <b><code>'\'</code></b>.</p>
<p>The '{' and '}' are used for scoping blocks, and the '\' character
allows you to desensitize control characters and also emit non-printable
characters.
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class ="postheader">Desensitizing Characters in the format string</h1>
<div class="postcontent">
<p>The backslash control character allows your to enter the typical
<b><code>"\a"</code></b>, <b><code>"\b"</code></b>, <b><code>"\f"</code></b>, <b><code>"\n"</code></b>,
<b><code>"\r"</code></b>, <b><code>"\t"</code></b>, <b><code>"\v"</code></b>, <b><code>"\\"</code></b>, characters
and along with the standard octal representation <b><code>"\0123"</code></b>
and hex <b><code>"\xAB"</code></b> characters. This allows you to enter
escape characters into your format strings and will
allow colorized output for terminals that support color.
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class ="postheader">Scoping</h1>
<div class="postcontent">
<p>Many times the information that you might have in your prompt might not be
available and you won't want it to print out if it isn't valid. To take care
of this you can enclose everything that <b>must</b> resolve into a scope. A scope
is starts with <code><b>'{'</code></b> and ends with
<code><b>'}'</code></b>. For example in order to only display
the current frame line table entry basename and line number when the information
is available for the current frame:
<p><b><code>"{ at {$line.file.basename}:${line.number}}"</code></b></p>
<p>Broken down this is:
<ul>
<li>The start the scope <p><b><code>"{"</code></b></p></li>
<li> format whose content will only be displayed if all information is available:
<p><b><code>"at {$line.file.basename}:${line.number}"</code></b></p></li>
<li>end the scope: <p><b><code>"}"</code></b></p></li>
</ul>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class ="postheader">Making the Frame Format</h1>
<div class="postcontent">
<p>The information that we see when stopped in a frame:
<p><b><code>frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19</code></b></p>
<p>can be displayed with the following format:</p>
<p><b><code>"frame #${frame.index}: ${frame.pc}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{ at ${line.file.basename}:${line.number}}\n"</code></b></p>
<p>This breaks down to:
<ul>
<li>Always print the frame index and frame PC:
<p><b><code>"frame #${frame.index}: ${frame.pc}"</code></b></p>
<li>only print the module followed by a tick if there is a valid
module for the current frame:
<p><b><code>"{ ${module.file.basename}`}"</code></b></p>
<li>print the function name with optional offset:</p>
<p><b><code>"{${function.name}{${function.pc-offset}}}"</code></b></p>
<li>print the line info if it is available:</p>
<p><b><code>"{ at ${line.file.basename}:${line.number}}"</code></b></p>
<li>then finish off with a newline:</p>
<p><b><code>"\n"</code></b></p>
</ul>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class ="postheader">Making Your Own Formats</h1>
<div class="postcontent">
<p>When modifying your own format strings, it is useful
to start with the default values for the frame and
thread format strings. These can be accessed with the
<b><code>"settings show"</code></b> command:
<p><b><code>(lldb)</b> settings show thread-format
<br>thread-format (format-string) = "thread #${thread.index}: tid = ${thread.id%tid}{, ${frame.pc}}{ ${module.file.basename}{`${function.name-with-args}{${frame.no-debug}${function.pc-offset}}}}{ at ${line.file.basename}:${line.number}}{, name = '${thread.name}'}{, queue = '${thread.queue}'}{, activity = '${thread.info.activity.name}'}{, ${thread.info.trace_messages} messages}{, stop reason = ${thread.stop-reason}}{\nReturn value: ${thread.return-value}}{\nCompleted expression: ${thread.completed-expression}}\n"
<br><b>(lldb)</b> settings show frame-format
<br>frame-format (format-string) = "frame #${frame.index}:{ ${frame.no-debug}${frame.pc}}{ ${module.file.basename}{`${function.name-with-args}{${frame.no-debug}${function.pc-offset}}}}{ at ${line.file.basename}:${line.number}}{${function.is-optimized} [opt]}\n"
</code></p>
<p>When making thread formats, you will need surround any
of the information that comes from a stack frame with scopes (<b>{</b> <i>frame-content</i> <b>}</b>)
as the thread format doesn't always want to show frame information.
When displaying the backtrace for a thread, we don't need to duplicate
the information for frame zero in the thread information:
<p><code><b>(lldb)</b> thread backtrace
<br>thread #1: tid = 0x2e03, stop reason = breakpoint 1.1 2.1
<br> frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
<br> frame #1: 0x0000000100000e40 a.out`start + 52
</code>
</p>
<p>The frame related variables are:
<ul>
<li><code><b>${file.*}</b></code></li>
<li><code><b>${frame.*}</b></code></li>
<li><code><b>${function.*}</b></code></li>
<li><code><b>${line.*}</b></code></li>
<li><code><b>${module.*}</b></code></li>
</ul>
</p>
<p>Looking at the default format for the thread, and underlining
the frame information:
<p><code>'thread #${thread.index}: tid = ${thread.id}<u><b>{</b>, ${frame.pc}<b>}{</b> ${module.file.basename}`${function.name}{${function.pc-offset}}<b>}</b></u>{, stop reason = ${thread.stop-reason}}{, name = ${thread.name}}{, queue = ${thread.queue}}\n'
</code></p>
<p>We can see that all frame information is contained in scopes so
that when the thread information is displayed in a context where
we only want to show thread information, we can do so.
<p>For both thread and frame formats, you can use ${script.target:<i>python_func</i>}, ${script.process:<i>python_func</i>} and ${script.thread:<i>python_func</i>}
(and of course ${script.frame:<i>python_func</i>} for frame formats)<br/>
In all cases, the signature of <i>python_func</i> is expected to be:<br/>
<p><code>
def <i>python_func</i>(<i>object</i>,unused):<br/>
...<br/>
return <i>string</i><br/></code>
<p>Where <i>object</i> is an instance of the SB class associated to the keyword you are using.
<p>e.g. Assuming your function looks like<br/><code><p>
def thread_printer_func (thread,unused):<br/>
return "Thread %s has %d frames\n" % (thread.name, thread.num_frames)<br/></code><p>
And you set it up with <code><br/><b>(lldb)</b> settings set thread-format "${script.thread:thread_printer_func}"<br/></code>
you would see output like:
</p>
<code>* Thread main has 21 frames</code>
</div>
<div class="postfooter"></div>
</div>
</div>
</div>
</div>
</body>
</html>