Added documentation for the new frame and thread format strings.
git-svn-id: https://llvm.org/svn/llvm-project/llvdb/trunk@115488 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/www/formats.html b/www/formats.html
new file mode 100755
index 0000000..c8c9ad2
--- /dev/null
+++ b/www/formats.html
@@ -0,0 +1,225 @@
+<!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 Homepage</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 was recently modified 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 a line that describes why
+ your thread stopped:</p>
+
+ <p><b><code>* thread #1: tid = 0x2e03, 0x0000000100000e85 a.out`main + 4, stop reason = breakpoint 1.1</code></b></p>
+
+ <p>Stack backtraces frames also have a similar information line:</p>
+
+ <p><code><b>(lldb)</b> thread backtrace
+ <br><b>thread #1: tid = 0x2e03, 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 can currently be set using the <b>settings set</b> command:</p>
+ <p><code><b>(lldb)</b> settings set frame-prompt STRING
+ <br><b>(lldb)</b> settings set thread-prompt 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>frame.index</b></td><td>The frame index (0, 1, 2, 3...)</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.pc-offset</b></td><td>The program counter offset within the current function or symbol</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 the 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>target.arch</b></td><td>The architecture of the current target</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 (string) = 'thread #${thread.index}: tid = ${thread.id}{, ${frame.pc}}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{, stop reason = ${thread.stop-reason}}{, name = ${thread.name}}{, queue = ${thread.queue}}\n'
+ <br><b>(lldb)</b> settings show frame-format
+ <br>frame-format (string) = 'frame #${frame.index}: ${frame.pc}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{ at ${line.file.basename}:${line.number}}\n'
+ </code></p>
+
+
+ </div>
+ <div class="postfooter"></div>
+ </div>
+
+ </div>
+ </div>
+</div>
+</body>
+</html>
\ No newline at end of file
diff --git a/www/sidebar.incl b/www/sidebar.incl
index 63ebf5f..041afde 100644
--- a/www/sidebar.incl
+++ b/www/sidebar.incl
@@ -13,9 +13,10 @@
<div class="urbangreymenu">
<h1 class="headerbar">Use and Extension</h1>
<ul>
- <li><a href="faq.html">FAQ</a></li>
- <li><a href="docs.html">Documentation</a></li>
<li><a href="architecture.html">Architecture</a></li>
+ <li><a href="docs.html">Documentation</a></li>
+ <li><a href="faq.html">FAQ</a></li>
+ <li><a href="formats.html">Frame and Thread Formatting</a></li>
</ul>
</div>
</div>