| <!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> |
