llvm.org GIT mirror llvm / 88fcc3a
Add documentation for llvm-pdbutil. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@310744 91177308-0d34-0410-b5e6-96231b3b80d8 Zachary Turner 2 years ago
2 changed file(s) with 586 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
5050 tblgen
5151 lit
5252 llvm-build
53 llvm-pdbutil
5354 llvm-readobj
0 llvm-pdbutil - PDB File forensics and diagnostics
1 =================================================
2
3 .. contents::
4 :local:
5
6 Synopsis
7 --------
8
9 :program:`llvm-pdbutil` [*subcommand*] [*options*]
10
11 Description
12 -----------
13
14 Display types, symbols, CodeView records, and other information from a
15 PDB file, as well as manipulate and create PDB files. :program:`llvm-pdbutil`
16 is normally used by FileCheck-based tests to test LLVM's PDB reading and
17 writing functionality, but can also be used for general PDB file investigation
18 and forensics, or as a replacement for cvdump.
19
20 Subcommands
21 -----------
22
23 :program:`llvm-pdbutil` is separated into several subcommands each tailored to
24 a different purpose. A brief summary of each command follows, with more detail
25 in the sections that follow.
26
27 * :ref:`pretty_subcommand` - Dump symbol and type information in a format that
28 tries to look as much like the original source code as possible.
29 * :ref:`dump_subcommand` - Dump low level types and structures from the PDB
30 file, including CodeView records, hash tables, PDB streams, etc.
31 * :ref:`bytes_subcommand` - Dump data from the PDB file's streams, records,
32 types, symbols, etc as raw bytes.
33 * :ref:`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce
34 a valid PDB file that matches that description.
35 * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML
36 description of some or all of the file in a way that the PDB can be
37 reconstructed.
38 * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the
39 result of merging the two input PDBs.
40
41 .. _pretty_subcommand:
42
43 pretty
44 ~~~~~~
45
46 .. program:: llvm-pdbutil pretty
47
48 .. important::
49 The **pretty** subcommand is built on the Windows DIA SDK, and as such is not
50 supported on non-Windows platforms.
51
52 USAGE: :program:`llvm-pdbutil` pretty [*options*]
53
54 Summary
55 ^^^^^^^^^^^
56
57 The *pretty* subcommand displays a very high level representation of your
58 program's debug info. Since it is built on the Windows DIA SDK which is the
59 standard API that Windows tools and debuggers query debug information, it
60 presents a more authoritative view of how a debugger is going to interpret your
61 debug information than a mode which displays low-level CodeView records.
62
63 Options
64 ^^^^^^^
65
66 Filtering and Sorting Options
67 +++++++++++++++++++++++++++++
68
69 .. note::
70 *exclude* filters take priority over *include* filters. So if a filter
71 matches both an include and an exclude rule, then it is excluded.
72
73 .. option:: -exclude-compilands=
74
75 When dumping compilands, compiland source-file contributions, or per-compiland
76 symbols, this option instructs **llvm-pdbutil** to omit any compilands that
77 match the specified regular expression.
78
79 .. option:: -exclude-symbols=
80
81 When dumping global, public, or per-compiland symbols, this option instructs
82 **llvm-pdbutil** to omit any symbols that match the specified regular
83 expression.
84
85 .. option:: -exclude-types=
86
87 When dumping types, this option instructs **llvm-pdbutil** to omit any types
88 that match the specified regular expression.
89
90 .. option:: -include-compilands=
91
92 When dumping compilands, compiland source-file contributions, or per-compiland
93 symbols, limit the initial search to only those compilands that match the
94 specified regular expression.
95
96 .. option:: -include-symbols=
97
98 When dumping global, public, or per-compiland symbols, limit the initial
99 search to only those symbols that match the specified regular expression.
100
101 .. option:: -include-types=
102
103 When dumping types, limit the initial search to only those types that match
104 the specified regular expression.
105
106 .. option:: -min-class-padding=
107
108 Only display types that have at least the specified amount of alignment
109 padding, accounting for padding in base classes and aggregate field members.
110
111 .. option:: -min-class-padding-imm=
112
113 Only display types that have at least the specified amount of alignment
114 padding, ignoring padding in base classes and aggregate field members.
115
116 .. option:: -min-type-size=
117
118 Only display types T where sizeof(T) is greater than or equal to the specified
119 amount.
120
121 .. option:: -no-compiler-generated
122
123 Don't show compiler generated types and symbols
124
125 .. option:: -no-enum-definitions
126
127 When dumping an enum, don't show the full enum (e.g. the individual enumerator
128 values).
129
130 .. option:: -no-system-libs
131
132 Don't show symbols from system libraries
133
134 Symbol Type Options
135 +++++++++++++++++++
136 .. option:: -all
137
138 Implies all other options in this category.
139
140 .. option:: -class-definitions=
141
142 Displays class definitions in the specified format.
143
144 .. code-block:: perl
145
146 =all - Display all class members including data, constants, typedefs, functions, etc (default)
147 =layout - Only display members that contribute to class size.
148 =none - Don't display class definitions (e.g. only display the name and base list)
149
150 .. option:: -class-order
151
152 Displays classes in the specified order.
153
154 .. code-block:: perl
155
156 =none - Undefined / no particular sort order (default)
157 =name - Sort classes by name
158 =size - Sort classes by size
159 =padding - Sort classes by amount of padding
160 =padding-pct - Sort classes by percentage of space consumed by padding
161 =padding-imm - Sort classes by amount of immediate padding
162 =padding-pct-imm - Sort classes by percentage of space consumed by immediate padding
163
164 .. option:: -class-recurse-depth=
165
166 When dumping class definitions, stop after recursing the specified number of times. The
167 default is 0, which is no limit.
168
169 .. option:: -classes
170
171 Display classes
172
173 .. option:: -compilands
174
175 Display compilands (e.g. object files)
176
177 .. option:: -enums
178
179 Display enums
180
181 .. option:: -externals
182
183 Dump external (e.g. exported) symbols
184
185 .. option:: -globals
186
187 Dump global symbols
188
189 .. option:: -lines
190
191 Dump the mappings between source lines and code addresses.
192
193 .. option:: -module-syms
194
195 Display symbols (variables, functions, etc) for each compiland
196
197 .. option:: -sym-types=
198
199 Type of symbols to dump when -globals, -externals, or -module-syms is
200 specified. (default all)
201
202 .. code-block:: perl
203
204 =thunks - Display thunk symbols
205 =data - Display data symbols
206 =funcs - Display function symbols
207 =all - Display all symbols (default)
208
209 .. option:: -symbol-order=
210
211 For symbols dumped via the -module-syms, -globals, or -externals options, sort
212 the results in specified order.
213
214 .. code-block:: perl
215
216 =none - Undefined / no particular sort order
217 =name - Sort symbols by name
218 =size - Sort symbols by size
219
220 .. option:: -typedefs
221
222 Display typedef types
223
224 .. option:: -types
225
226 Display all types (implies -classes, -enums, -typedefs)
227
228 Other Options
229 +++++++++++++
230
231 .. option:: -color-output
232
233 Force color output on or off. By default, color if used if outputting to a
234 terminal.
235
236 .. option:: -load-address=
237
238 When displaying relative virtual addresses, assume the process is loaded at the
239 given address and display what would be the absolute address.
240
241 .. _dump_subcommand:
242
243 dump
244 ~~~~
245
246 USAGE: :program:`llvm-pdbutil` dump [*options*]
247
248 .. program:: llvm-pdbutil dump
249
250 Summary
251 ^^^^^^^^^^^
252
253 The **dump** subcommand displays low level information about the structure of a
254 PDB file. It is used heavily by LLVM's testing infrastructure, but can also be
255 used for PDB forensics. It serves a role similar to that of Microsoft's
256 `cvdump` tool.
257
258 .. note::
259 The **dump** subcommand exposes internal details of the file format. As
260 such, the reader should be familiar with :doc:`/PDB/index` before using this
261 command.
262
263 Options
264 ^^^^^^^
265
266 MSF Container Options
267 +++++++++++++++++++++
268
269 .. option:: -streams
270
271 dump a summary of all of the streams in the PDB file.
272
273 .. option:: -stream-blocks
274
275 In conjunction with :option:`-streams`, add information to the output about
276 what blocks the specified stream occupies.
277
278 .. option:: -summary
279
280 Dump MSF and PDB header information.
281
282 Module & File Options
283 +++++++++++++++++++++
284
285 .. option:: -modi=
286
287 For all options that dump information from each module/compiland, limit to
288 the specified module.
289
290 .. option:: -files
291
292 Dump the source files that contribute to each displayed module.
293
294 .. option:: -il
295
296 Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection)
297
298 .. option:: -l
299
300 Dump line information (DEBUG_S_LINES CodeView subsection)
301
302 .. option:: -modules
303
304 Dump compiland information
305
306 .. option:: -xme
307
308 Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection)
309
310 .. option:: -xmi
311
312 Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection)
313
314 Symbol Options
315 ++++++++++++++
316
317 .. option:: -globals
318
319 dump global symbol records
320
321 .. option:: -global-extras
322
323 dump additional information about the globals, such as hash buckets and hash
324 values.
325
326 .. option:: -publics
327
328 dump public symbol records
329
330 .. option:: -public-extras
331
332 dump additional information about the publics, such as hash buckets and hash
333 values.
334
335 .. option:: -symbols
336
337 dump symbols (functions, variables, etc) for each module dumped.
338
339 .. option:: -sym-data
340
341 For each symbol record dumped as a result of the :option:`-symbols` option,
342 display the full bytes of the record in binary as well.
343
344 Type Record Options
345 +++++++++++++++++++
346
347 .. option:: -types
348
349 Dump CodeView type records from TPI stream
350
351 .. option:: -type-extras
352
353 Dump additional information from the TPI stream, such as hashes and the type
354 index offsets array.
355
356 .. option:: -type-data
357
358 For each type record dumped, display the full bytes of the record in binary as
359 well.
360
361 .. option:: -type-index=
362
363 Only dump types with the specified type index.
364
365 .. option:: -ids
366
367 Dump CodeView type records from IPI stream.
368
369 .. option:: -id-extras
370
371 Dump additional information from the IPI stream, such as hashes and the type
372 index offsets array.
373
374 .. option:: -id-data
375
376 For each ID record dumped, display the full bytes of the record in binary as
377 well.
378
379 .. option:: -id-index=
380
381 only dump ID records with the specified hexadecimal type index.
382
383 .. option:: -dependents
384
385 When used in conjunction with :option:`-type-index` or :option:`-id-index`,
386 dumps the entire dependency graph for the specified index instead of just the
387 single record with the specified index. For example, if type index 0x4000 is
388 a function whose return type has index 0x3000, and you specify
389 `-dependents=0x4000`, then this would dump both records (as well as any other
390 dependents in the tree).
391
392 Miscellaneous Options
393 +++++++++++++++++++++
394
395 .. option:: -all
396
397 Implies most other options.
398
399 .. option:: -section-contribs
400
401 Dump section contributions.
402
403 .. option:: -section-headers
404
405 Dump image section headers.
406
407 .. option:: -section-map
408
409 Dump section map.
410
411 .. option:: -string-table
412
413 Dump PDB string table.
414
415 .. _bytes_subcommand:
416
417 bytes
418 ~~~~~
419
420 USAGE: :program:`llvm-pdbutil` bytes [*options*]
421
422 .. program:: llvm-pdbutil bytes
423
424 Summary
425 ^^^^^^^
426
427 Like the **dump** subcommand, the **bytes** subcommand displays low level
428 information about the structure of a PDB file, but it is used for even deeper
429 forensics. The **bytes** subcommand finds various structures in a PDB file
430 based on the command line options specified, and dumps them in hex. Someone
431 working on support for emitting PDBs would use this heavily, for example, to
432 compare one PDB against another PDB to ensure byte-for-byte compatibility. It
433 is not enough to simply compare the bytes of an entire file, or an entire stream
434 because it's perfectly fine for the same structure to exist at different
435 locations in two different PDBs, and "finding" the structure is half the battle.
436
437 Options
438 ^^^^^^^
439
440 MSF File Options
441 ++++++++++++++++
442
443 .. option:: -block-range=
444
445 Dump binary data from specified range of MSF file blocks.
446
447 .. option:: -byte-range=
448
449 Dump binary data from specified range of bytes in the file.
450
451 .. option:: -fpm
452
453 Dump the MSF free page map.
454
455 .. option:: -stream-data=
456
457 Dump binary data from the specified streams. Format is SN[:Start][@Size].
458 For example, `-stream-data=7:3@12` dumps 12 bytes from stream 7, starting
459 at offset 3 in the stream.
460
461 PDB Stream Options
462 ++++++++++++++++++
463
464 .. option:: -name-map
465
466 Dump bytes of PDB Name Map
467
468 DBI Stream Options
469 ++++++++++++++++++
470
471 .. option:: -ec
472
473 Dump the edit and continue map substream of the DBI stream.
474
475 .. option:: -files
476
477 Dump the file info substream of the DBI stream.
478
479 .. option:: -modi
480
481 Dump the modi substream of the DBI stream.
482
483 .. option:: -sc
484
485 Dump section contributions substream of the DBI stream.
486
487 .. option:: -sm
488
489 Dump the section map from the DBI stream.
490
491 .. option:: -type-server
492
493 Dump the type server map from the DBI stream.
494
495 Module Options
496 ++++++++++++++
497
498 .. option:: -mod=
499
500 Limit all options in this category to the specified module index. By default,
501 options in this category will dump bytes from all modules.
502
503 .. option:: -chunks
504
505 Dump the bytes of each module's C13 debug subsection.
506
507 .. option:: -split-chunks
508
509 When specified with :option:`-chunks`, split the C13 debug subsection into a
510 separate chunk for each subsection type, and dump them separately.
511
512 .. option:: -syms
513
514 Dump the symbol record substream from each module.
515
516 Type Record Options
517 +++++++++++++++++++
518
519 .. option:: -id=
520
521 Dump the record from the IPI stream with the given type index.
522
523 .. option:: -type=
524
525 Dump the record from the TPI stream with the given type index.
526
527 .. _pdb2yaml_subcommand:
528
529 pdb2yaml
530 ~~~~~~~~
531
532 USAGE: :program:`llvm-pdbutil` pdb2yaml [*options*]
533
534 .. program:: llvm-pdbutil pdb2yaml
535
536 Summary
537 ^^^^^^^
538
539 Options
540 ^^^^^^^
541
542 .. _yaml2pdb_subcommand:
543
544 yaml2pdb
545 ~~~~~~~~
546
547 USAGE: :program:`llvm-pdbutil` yaml2pdb [*options*]
548
549 .. program:: llvm-pdbutil yaml2pdb
550
551 Summary
552 ^^^^^^^
553
554 Generate a PDB file from a YAML description. The YAML syntax is not described
555 here. Instead, use :ref:`llvm-pdbutil pdb2yaml ` and
556 examine the output for an example starting point.
557
558 Options
559 ^^^^^^^
560
561 .. option:: -pdb=
562
563 Write the resulting PDB to the specified file.
564
565 .. _merge_subcommand:
566
567 merge
568 ~~~~~
569
570 USAGE: :program:`llvm-pdbutil` merge [*options*]
571
572 .. program:: llvm-pdbutil merge
573
574 Summary
575 ^^^^^^^
576
577 Merge two PDB files into a single file.
578
579 Options
580 ^^^^^^^
581
582 .. option:: -pdb=
583
584 Write the resulting PDB to the specified file.