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

2013-01-04 18:18:21 +0000

[diff] [blame]

155

<code><pre><tt><b>(lldb)</b> target create --no-dependents --arch x86_64 /tmp/a.out <b>--symfile /tmp/a.out.dSYM</b>

156

<b>(lldb)</b> target modules add /usr/lib/system/libsystem_c.dylib <b>--symfile /build/server/a/libsystem_c.dylib.dSYM</b>

157

<b>(lldb)</b> target modules add /usr/lib/system/libsystem_dnssd.dylib <b>--symfile /build/server/b/libsystem_dnssd.dylib.dSYM</b>

158

<b>(lldb)</b> target modules add /usr/lib/system/libsystem_kernel.dylib <b>--symfile /build/server/c/libsystem_kernel.dylib.dSYM</b>

159

</tt></pre></code>

Jason Molenda

2013-01-04 22:37:21 +0000

[diff] [blame]

160

<p>Then we set the load addresses for each __TEXT section (note the colors of the load addresses above and below) using the first address from the Binary Images section for each image:</p>

Greg Clayton

2013-01-04 18:18:21 +0000

[diff] [blame]

161

<code><pre><tt><b>(lldb)</b> target modules load --file a.out <font color=blue>0x100000000</font>

162

<b>(lldb)</b> target modules load --file libsystem_c.dylib <font color=green>0x7fff83f32000</font>

163

<b>(lldb)</b> target modules load --file libsystem_dnssd.dylib <font color=red>0x7fff883db000</font>

164

<b>(lldb)</b> target modules load --file libsystem_kernel.dylib <font color=purple>0x7fff8c0dc000</font>

165

</tt></pre></code>

166

<p>Now any stack backtraces that haven't been symbolicated can be symbolicated using "image lookup"

167

with the raw backtrace addresses.</p>

168

<p>Given the following raw backtrace:</p>

169

<code><pre><tt>Thread 0 Crashed:: Dispatch queue: com.apple.main-thread

170

0 libsystem_kernel.dylib 0x00007fff8a1e6d46 __kill + 10

171

1 libsystem_c.dylib 0x00007fff84597df0 abort + 177

172

2 libsystem_c.dylib 0x00007fff84598e2a __assert_rtn + 146

173

3 a.out 0x0000000100000f46 main + 70

174

4 libdyld.dylib 0x00007fff8c4197e1 start + 1

175

</tt></pre></code>

176

<p>We can now symbolicate the <b>load</b> addresses:<p>

177

<code><pre><tt><b>(lldb)</b> image lookup -a 0x00007fff8a1e6d46

178

<b>(lldb)</b> image lookup -a 0x00007fff84597df0

179

<b>(lldb)</b> image lookup -a 0x00007fff84598e2a

180

<b>(lldb)</b> image lookup -a 0x0000000100000f46

</tt></pre></code>

</div>

</div>

<h1 class="postheader">Getting Variable Information</h1>

187

188

<p>If you add the --verbose flag to the "image lookup --address" command,

189

you can get verbose information which can often include the locations

190

of some of your local variables:

191

<code><pre><tt>><b>(lldb)</b> image lookup --address 0x100123aa3 --verbose

192

Address: a.out[0x0000000100000aa3] (a.out.__TEXT.__text + 110)

193

Summary: a.out`main + 50 at main.c:13

194

Module: file = "/tmp/a.out", arch = "x86_64"

195

CompileUnit: id = {0x00000000}, file = "/tmp/main.c", language = "ISO C:1999"

196

Function: id = {0x0000004f}, name = "main", range = [0x0000000100000bc0-0x0000000100000dc9)

197

FuncType: id = {0x0000004f}, decl = main.c:9, clang_type = "int (int, const char **, const char **, const char **)"

198

Blocks: id = {0x0000004f}, range = [0x100000bc0-0x100000dc9)

199

id = {0x000000ae}, range = [0x100000bf2-0x100000dc4)

200

LineEntry: [0x0000000100000bf2-0x0000000100000bfa): /tmp/main.c:13:23

201

Symbol: id = {0x00000004}, range = [0x0000000100000bc0-0x0000000100000dc9), name="main"

202

Variable: id = {0x000000bf}, name = "path", type= "char [1024]", location = DW_OP_fbreg(-1072), decl = main.c:28

203

Variable: id = {0x00000072}, name = "argc", type= "int", <b>location = r13</b>, decl = main.c:8

204

Variable: id = {0x00000081}, name = "argv", type= "const char **", <b>location = r12</b>, decl = main.c:8

205

Variable: id = {0x00000090}, name = "envp", type= "const char **", <b>location = r15</b>, decl = main.c:8

206

Variable: id = {0x0000009f}, name = "aapl", type= "const char **", <b>location = rbx</b>, decl = main.c:8

207

</tt></pre></code>

208

<p>The interesting part is the variables that are listed. The variables are

209

the parameters and local variables that are in scope for the address that

210

was specified. These variable entries have locations which are shown in bold

211

above. Crash logs often have register information for the first frame in each

212

stack, and being able to reconstruct one or more local variables can often

213

help you decipher more information from a crash log than you normally would be

214

able to. Note that this is really only useful for the first frame, and only if

215

your crash logs have register information for your threads.

</div>

</div>

<h1 class="postheader">Using Python API to Symbolicate</h1>

221

222

<p>All of the commands above can be done through the python script bridge. The code below

223

will recreate the target and add the three shared libraries that we added in the darwin

224

crash log example above:

225

<code><pre><tt>triple = "x86_64-apple-macosx"

226

platform_name = None

227

add_dependents = False

228

target = lldb.debugger.CreateTarget("/tmp/a.out", triple, platform_name, add_dependents, lldb.SBError())

229

if target:

230

<font color=green># Get the executable module</font>

231

module = target.GetModuleAtIndex(0)

232

target.SetSectionLoadAddress(module.FindSection("__TEXT"), 0x100000000)

233

module = target.AddModule ("/usr/lib/system/libsystem_c.dylib", triple, None, "/build/server/a/libsystem_c.dylib.dSYM")

234

target.SetSectionLoadAddress(module.FindSection("__TEXT"), 0x7fff83f32000)

235

module = target.AddModule ("/usr/lib/system/libsystem_dnssd.dylib", triple, None, "/build/server/b/libsystem_dnssd.dylib.dSYM")

236

target.SetSectionLoadAddress(module.FindSection("__TEXT"), 0x7fff883db000)

237

module = target.AddModule ("/usr/lib/system/libsystem_kernel.dylib", triple, None, "/build/server/c/libsystem_kernel.dylib.dSYM")

238

target.SetSectionLoadAddress(module.FindSection("__TEXT"), 0x7fff8c0dc000)

239

240

load_addr = 0x00007fff8a1e6d46

241

<font color=green># so_addr is a section offset address, or a lldb.SBAddress object</font>

242

so_addr = target.ResolveLoadAddress (load_addr)

243

<font color=green># Get a symbol context for the section offset address which includes

244

# a module, compile unit, function, block, line entry, and symbol</font>

245

sym_ctx = so_addr.GetSymbolContext (lldb.eSymbolContextEverything)

print sym_ctx

</tt></pre></code>

</div>

</div>

<h1 class="postheader">Use Builtin Python module to Symbolicate</h1>

254

Greg Clayton

2013-01-04 19:01:39 +0000

[diff] [blame]

255

<p>LLDB includes a module in the <b>lldb</b> package named <b>lldb.utils.symbolication</b>.

256

This module contains a lot of symbolication functions that simplify the symbolication

257

process by allowing you to create objects that represent symbolication class objects such as:

Greg Clayton

2013-01-04 18:18:21 +0000

[diff] [blame]

258

<ul>

259

<li>lldb.utils.symbolication.Address</li>

260

<li>lldb.utils.symbolication.Section</li>

261

<li>lldb.utils.symbolication.Image</li>

262

<li>lldb.utils.symbolication.Symbolicator</li>

263

</ul>

Greg Clayton

2013-01-04 19:01:39 +0000

[diff] [blame]

264

<h2>lldb.utils.symbolication.Address</h2>

265

<p>This class represents an address that will be symbolicated. It will cache any information

266

that has been looked up: module, compile unit, function, block, line entry, symbol.

267

It does this by having a lldb.SBSymbolContext as a member variable.

268

</p>

269

<h2>lldb.utils.symbolication.Section</h2>

270

<p>This class represents a section that might get loaded in a <b>lldb.utils.symbolication.Image</b>.

271

It has helper functions that allow you to set it from text that might have been extracted from

272

a crash log file.

273

</p>

274

<h2>lldb.utils.symbolication.Image</h2>

275

<p>This class represents a module that might get loaded into the target we use for symbolication.

276

This class contains the executable path, optional symbol file path, the triple, and the list of sections that will need to be loaded

277

if we choose the ask the target to load this image. Many of these objects will never be loaded

278

into the target unless they are needed by symbolication. You often have a crash log that has

279

100 to 200 different shared libraries loaded, but your crash log stack backtraces only use a few

280

of these shared libraries. Only the images that contain stack backtrace addresses need to be loaded

281

in the target in order to symbolicate.

282

</p>

283

<p>Subclasses of this class will want to override the <b>locate_module_and_debug_symbols</b> method:

284

<code><pre><tt>class CustomImage(lldb.utils.symbolication.Image):

285

def locate_module_and_debug_symbols (self):

286

<font color=green># Locate the module and symbol given the info found in the crash log</font>

287

</tt></pre></code>

288

<p>Overriding this function allows clients to find the correct executable module and symbol files as they might reside on a build server.<p>

289

<h2>lldb.utils.symbolication.Symbolicator</h2>

290

<p>This class coordinates the symbolication process by loading only the <b>lldb.utils.symbolication.Image</b>

291

instances that need to be loaded in order to symbolicate an supplied address.

292

</p>

293

<h2>lldb.macosx.crashlog</h2>

Jason Molenda

2013-01-04 22:37:21 +0000

[diff] [blame]

294

<p><b>lldb.macosx.crashlog</b> is a package that is distributed on Mac OS X builds that subclasses the above classes.

295

This module parses the information in the Darwin crash logs and creates symbolication objects that

Greg Clayton

2013-01-04 19:01:39 +0000

[diff] [blame]

296

represent the images, the sections and the thread frames for the backtraces. It then uses the functions

297

in the lldb.utils.symbolication to symbolicate the crash logs.</p>

298

<p>

299

This module installs a new "crashlog" command into the lldb command interpreter so that you can use

Jason Molenda

2013-01-04 22:37:21 +0000

[diff] [blame]

300

it to parse and symbolicate Mac OS X crash logs:</p>

Enrico Granata

03e1677

2013-05-08 21:39:19 +0000

[diff] [blame]

301

<code><pre><tt><b>(lldb)</b> command script import lldb.macosx.crashlog

Greg Clayton

2013-01-04 18:18:21 +0000

[diff] [blame]

302

"crashlog" and "save_crashlog" command installed, use the "--help" option for detailed help

Greg Clayton

2013-01-04 19:01:39 +0000

[diff] [blame]

303

<b>(lldb)</b> crashlog /tmp/crash.log

304

...

305

</tt></pre></code>

Jason Molenda

2013-01-04 22:37:21 +0000

[diff] [blame]

306

<p>The command that is installed has built in help that shows the

307

options that can be used when symbolicating:

Greg Clayton

2013-01-04 19:01:39 +0000

[diff] [blame]

308

<code><pre><tt><b>(lldb)</b> crashlog --help

Greg Clayton

2013-01-04 18:18:21 +0000

[diff] [blame]

309

Usage: crashlog [options] <FILE> [FILE ...]

310

311

Symbolicate one or more darwin crash log files to provide source file and line

312

information, inlined stack frames back to the concrete functions, and

313

disassemble the location of the crash for the first frame of the crashed

314

thread. If this script is imported into the LLDB command interpreter, a

315

"crashlog" command will be added to the interpreter for use at the LLDB

316

command line. After a crash log has been parsed and symbolicated, a target

317

will have been created that has all of the shared libraries loaded at the load

318

addresses found in the crash log file. This allows you to explore the program

319

as if it were stopped at the locations described in the crash log and

320

functions can be disassembled and lookups can be performed using the

321

addresses found in the crash log.

322

323

Options:

324

-h, --help show this help message and exit

325

-v, --verbose display verbose debug info

326

-g, --debug display verbose debug logging

327

-a, --load-all load all executable images, not just the images found

328

in the crashed stack frames

329

--images show image list

330

--debug-delay=NSEC pause for NSEC seconds for debugger

331

-c, --crashed-only only symbolicate the crashed thread

332

-d DISASSEMBLE_DEPTH, --disasm-depth=DISASSEMBLE_DEPTH

333

set the depth in stack frames that should be

334

disassembled (default is 1)

335

-D, --disasm-all enabled disassembly of frames on all threads (not just

336

the crashed thread)

337

-B DISASSEMBLE_BEFORE, --disasm-before=DISASSEMBLE_BEFORE

338

the number of instructions to disassemble before the

339

frame PC

340

-A DISASSEMBLE_AFTER, --disasm-after=DISASSEMBLE_AFTER

341

the number of instructions to disassemble after the

342

frame PC

343

-C NLINES, --source-context=NLINES

344

show NLINES source lines of source context (default =

345

4)

346

--source-frames=NFRAMES

347

show source for NFRAMES (default = 4)

348

--source-all show source for all threads, not just the crashed

349

thread

350

-i, --interactive parse all crash logs and enter interactive mode

351

352

</tt></pre></code>

Greg Clayton

2013-01-04 19:01:39 +0000

[diff] [blame]

353

<p>The source for the "symbolication" and "crashlog" modules are available in SVN:</p>

354

<ul>

355

<li><a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/symbolication.py">symbolication.py</a></li>

356

<li><a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/crashlog.py">crashlog.py</a></li>

357

</ul>

Greg Clayton

2013-01-04 18:18:21 +0000

[diff] [blame]

358

</div>

359

360

</div>

Greg Clayton