Blame - www/formats.html - fp2-dev/platform/external/lldb

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

Greg Clayton

688082e

2012-01-13 08:41:20 +0000

[diff] [blame]

82

<tr valign=top><td><b>function.name</b></td><td>The name of the current function or symbol.</td></tr>

83

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

Greg Clayton

198e8fe

2010-10-04 02:33:45 +0000

[diff] [blame]

84

<tr valign=top><td><b>function.pc-offset</b></td><td>The program counter offset within the current function or symbol</td></tr>

85

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

86

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

87

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

88

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

89

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

90

<tr valign=top><td><b>module.file.basename</b></td><td>The basename of the current module (shared library or executable)</td></tr>

91

<tr valign=top><td><b>module.file.fullpath</b></td><td>The basename of the current module (shared library or executable)</td></tr>

92

<tr valign=top><td><b>process.file.basename</b></td><td>The basename of the file for the process</td></tr>

93

<tr valign=top><td><b>process.file.fullpath</b></td><td>The fullname of the file for the process</td></tr>

94

<tr valign=top><td><b>process.id</b></td><td>The process ID native the the system on which the inferior runs.</td></tr>

95

<tr valign=top><td><b>process.name</b></td><td>The name of the process at runtime</td></tr>

96

<tr valign=top><td><b>thread.id</b></td><td>The thread identifier for the current thread</td></tr>

97

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

98

<tr valign=top><td><b>thread.name</b></td><td>The name of the thread if the target OS supports naming threads</td></tr>

99

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

100

<tr valign=top><td><b>thread.stop-reason</b></td><td>A textual reason each thread stopped</td></tr>

Jim Ingham

1586d97

2011-12-17 01:35:57 +0000

[diff] [blame]

101

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

Greg Clayton

198e8fe

2010-10-04 02:33:45 +0000

[diff] [blame]

102

<tr valign=top><td><b>target.arch</b></td><td>The architecture of the current target</td></tr>

Enrico Granata

f68ffcd

2013-07-12 20:46:02 +0000

[diff] [blame]

103

<tr valign=top><td><b>target.script:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr>

104

<tr valign=top><td><b>process.script:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr>

105

<tr valign=top><td><b>thread.script:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr>

106

<tr valign=top><td><b>frame.script:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr>

Greg Clayton

198e8fe

2010-10-04 02:33:45 +0000

[diff] [blame]

</table>

</div>

</div>

<h1 class ="postheader">Control Characters</h1>

115

116

117

<p>Control characters include <b><code>'{'</code></b>,

118

119

120

<p>The '{' and '}' are used for scoping blocks, and the '\' character

121

allows you to desensitize control characters and also emit non-printable

characters.

</div>

</div>

<h1 class ="postheader">Desensitizing Characters in the format string</h1>

130

131

<p>The backslash control character allows your to enter the typical

132

<b><code>"\a"</code></b>, <b><code>"\b"</code></b>, <b><code>"\f"</code></b>, <b><code>"\n"</code></b>,

133

<b><code>"\r"</code></b>, <b><code>"\t"</code></b>, <b><code>"\v"</code></b>, <b><code>"\\"</code></b>, characters

134

and along with the standard octal representation <b><code>"\0123"</code></b>

135

and hex <b><code>"\xAB"</code></b> characters. This allows you to enter

136

escape characters into your format strings and will

137

allow colorized output for terminals that support color.

</div>

</div>

<h1 class ="postheader">Scoping</h1>

145

146

<p>Many times the information that you might have in your prompt might not be

147

available and you won't want it to print out if it isn't valid. To take care

148

of this you can enclose everything that <b>must</b> resolve into a scope. A scope

149

is starts with <code><b>'{'</code></b> and ends with

150

<code><b>'}'</code></b>. For example in order to only display

151

the current frame line table entry basename and line number when the information

152

is available for the current frame:

153

154

<p><b><code>"{ at {$line.file.basename}:${line.number}}"</code></b></p>

155

156

<p>Broken down this is:

157

<ul>

158

<li>The start the scope <p><b><code>"{"</code></b></p></li>

159

<li> format whose content will only be displayed if all information is available:

160

<p><b><code>"at {$line.file.basename}:${line.number}"</code></b></p></li>

161

<li>end the scope: <p><b><code>"}"</code></b></p></li>

</ul>

</div>

</div>

<h1 class ="postheader">Making the Frame Format</h1>

170

171

<p>The information that we see when stopped in a frame:

172

173

<p><b><code>frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19</code></b></p>

174

175

<p>can be displayed with the following format:</p>

176

177

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

178

179

<p>This breaks down to:

180

181

<ul>

182

<li>Always print the frame index and frame PC:

183

184

<p><b><code>"frame #${frame.index}: ${frame.pc}"</code></b></p>

185

186

<li>only print the module followed by a tick if there is a valid

187

module for the current frame:

188

189

<p><b><code>"{ ${module.file.basename}`}"</code></b></p>

190

191

<li>print the function name with optional offset:</p>

192

<p><b><code>"{${function.name}{${function.pc-offset}}}"</code></b></p>

193

194

<li>print the line info if it is available:</p>

195

196

<p><b><code>"{ at ${line.file.basename}:${line.number}}"</code></b></p>

197

198

<li>then finish off with a newline:</p>

</ul>

</div>

</div>

<h1 class ="postheader">Making Your Own Formats</h1>

209

210

211

<p>When modifying your own format strings, it is useful

212

to start with the default values for the frame and

213

thread format strings. These can be accessed with the

214

<b><code>"settings show"</code></b> command:

215

216

<p><b><code>(lldb)</b> settings show thread-format

217

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

218

<br><b>(lldb)</b> settings show frame-format

219

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

Greg Clayton

2010-10-04 03:06:05 +0000

[diff] [blame]

223

<p>When making thread formats, you will need surround any

224

of the information that comes from a stack frame with scopes (<b>{</b> <i>frame-content</i> <b>}</b>)

225

as the thread format doesn't always want to show frame information.

226

When displaying the backtrace for a thread, we don't need to duplicate

227

the information for frame zero in the thread information:

228

229

<p><code><b>(lldb)</b> thread backtrace

230

<br>thread #1: tid = 0x2e03, stop reason = breakpoint 1.1 2.1

231

<br>  frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19

232

<br>  frame #1: 0x0000000100000e40 a.out`start + 52

</code>

</p>

<p>The frame related variables are:

237

<ul>

238

239

<li><code><b>${frame.*}</b></code></li>

240

<li><code><b>${function.*}</b></code></li>

241

242

<li><code><b>${module.*}</b></code></li>

</ul>

</p>

<p>Looking at the default format for the thread, and underlining

247

the frame information:

248

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

249

</code></p>

250

<p>We can see that all frame information is contained in scopes so

251

that when the thread information is displayed in a context where

252

we only want to show thread information, we can do so.

253

Enrico Granata

f68ffcd

2013-07-12 20:46:02 +0000

[diff] [blame]

254

<p>For both thread and frame formats, you can use ${target.script:<i>python_func</i>}, ${process.script:<i>python_func</i>} and ${thread.script:<i>python_func</i>}

255

(and of course ${frame.script:<i>python_func</i>} for frame formats)<br/>

256

In all cases, the signature of <i>python_func</i> is expected to be:<br/>

257

258

def <i>python_func</i>(<i>object</i>,unused):<br/>

259

    ...<br/>

260

    return <i>string</i><br/></code>

261