[ARM] Fixup pipeline test. NFC
[llvm-complete.git] / docs / CommandGuide / llvm-pdbutil.rst
blob955353187112c1b4ac00c9c79e426d8e595a65b8
1 llvm-pdbutil - PDB File forensics and diagnostics
2 =================================================
4 .. program:: llvm-pdbutil
6 .. contents::
7    :local:
9 Synopsis
10 --------
12 :program:`llvm-pdbutil` [*subcommand*] [*options*]
14 Description
15 -----------
17 Display types, symbols, CodeView records, and other information from a
18 PDB file, as well as manipulate and create PDB files.  :program:`llvm-pdbutil`
19 is normally used by FileCheck-based tests to test LLVM's PDB reading and
20 writing functionality, but can also be used for general PDB file investigation
21 and forensics, or as a replacement for cvdump.
23 Subcommands
24 -----------
26 :program:`llvm-pdbutil` is separated into several subcommands each tailored to
27 a different purpose.  A brief summary of each command follows, with more detail
28 in the sections that follow.
30   * :ref:`pretty_subcommand` - Dump symbol and type information in a format that\r
31     tries to look as much like the original source code as possible.
32   * :ref:`dump_subcommand` - Dump low level types and structures from the PDB\r
33     file, including CodeView records, hash tables, PDB streams, etc.
34   * :ref:`bytes_subcommand` - Dump data from the PDB file's streams, records,\r
35     types, symbols, etc as raw bytes.
36   * :ref:`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce\r
37     a valid PDB file that matches that description.
38   * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML\r
39     description of some or all of the file in a way that the PDB can be\r
40     reconstructed.
41   * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the\r
42     result of merging the two input PDBs.
44 .. _pretty_subcommand:
46 pretty
47 ~~~~~~
49 .. program:: llvm-pdbutil pretty
51 .. important::
52    The **pretty** subcommand is built on the Windows DIA SDK, and as such is not\r
53    supported on non-Windows platforms.
55 USAGE: :program:`llvm-pdbutil` pretty [*options*] <input PDB file>
57 Summary
58 ^^^^^^^^^^^
60 The *pretty* subcommand displays a very high level representation of your\r
61 program's debug info.  Since it is built on the Windows DIA SDK which is the\r
62 standard API that Windows tools and debuggers query debug information, it\r
63 presents a more authoritative view of how a debugger is going to interpret your\r
64 debug information than a mode which displays low-level CodeView records.
66 Options
67 ^^^^^^^
69 Filtering and Sorting Options
70 +++++++++++++++++++++++++++++
72 .. note::
73    *exclude* filters take priority over *include* filters.  So if a filter\r
74    matches both an include and an exclude rule, then it is excluded.
76 .. option:: -exclude-compilands=<string>
78  When dumping compilands, compiland source-file contributions, or per-compiland\r
79  symbols, this option instructs **llvm-pdbutil** to omit any compilands that\r
80  match the specified regular expression.
82 .. option:: -exclude-symbols=<string>
84  When dumping global, public, or per-compiland symbols, this option instructs\r
85  **llvm-pdbutil** to omit any symbols that match the specified regular\r
86  expression.
88 .. option:: -exclude-types=<string>
90  When dumping types, this option instructs **llvm-pdbutil** to omit any types\r
91  that match the specified regular expression.
93 .. option:: -include-compilands=<string>
95  When dumping compilands, compiland source-file contributions, or per-compiland\r
96  symbols, limit the initial search to only those compilands that match the\r
97  specified regular expression.
99 .. option:: -include-symbols=<string>
101  When dumping global, public, or per-compiland symbols, limit the initial\r
102  search to only those symbols that match the specified regular expression.
104 .. option:: -include-types=<string>
106  When dumping types, limit the initial search to only those types that match\r
107  the specified regular expression.
109 .. option:: -min-class-padding=<uint>
111  Only display types that have at least the specified amount of alignment\r
112  padding, accounting for padding in base classes and aggregate field members.
114 .. option:: -min-class-padding-imm=<uint>
116  Only display types that have at least the specified amount of alignment\r
117  padding, ignoring padding in base classes and aggregate field members.
119 .. option:: -min-type-size=<uint>
121  Only display types T where sizeof(T) is greater than or equal to the specified\r
122  amount.
124 .. option:: -no-compiler-generated
126  Don't show compiler generated types and symbols
128 .. option:: -no-enum-definitions
130  When dumping an enum, don't show the full enum (e.g. the individual enumerator\r
131  values).
133 .. option:: -no-system-libs
135  Don't show symbols from system libraries
137 Symbol Type Options
138 +++++++++++++++++++
139 .. option:: -all
141  Implies all other options in this category.
143 .. option:: -class-definitions=<format>
145  Displays class definitions in the specified format.
147  .. code-block:: text
149     =all      - Display all class members including data, constants, typedefs, functions, etc (default)
150     =layout   - Only display members that contribute to class size.
151     =none     - Don't display class definitions (e.g. only display the name and base list)
153 .. option:: -class-order
155  Displays classes in the specified order.
157  .. code-block:: text
159     =none            - Undefined / no particular sort order (default)
160     =name            - Sort classes by name
161     =size            - Sort classes by size
162     =padding         - Sort classes by amount of padding
163     =padding-pct     - Sort classes by percentage of space consumed by padding
164     =padding-imm     - Sort classes by amount of immediate padding
165     =padding-pct-imm - Sort classes by percentage of space consumed by immediate padding
167 .. option::  -class-recurse-depth=<uint>
169  When dumping class definitions, stop after recursing the specified number of times.  The
170  default is 0, which is no limit.
172 .. option::  -classes
174  Display classes
176 .. option::  -compilands
178  Display compilands (e.g. object files)
180 .. option::  -enums
182  Display enums
184 .. option::  -externals
186  Dump external (e.g. exported) symbols
188 .. option::  -globals
190  Dump global symbols
192 .. option::  -lines
194  Dump the mappings between source lines and code addresses.
196 .. option::  -module-syms
198  Display symbols (variables, functions, etc) for each compiland
200 .. option::  -sym-types=<types>
202  Type of symbols to dump when -globals, -externals, or -module-syms is
203  specified. (default all)
205  .. code-block:: text
207     =thunks - Display thunk symbols
208     =data   - Display data symbols
209     =funcs  - Display function symbols
210     =all    - Display all symbols (default)
212 .. option::  -symbol-order=<order>
214  For symbols dumped via the -module-syms, -globals, or -externals options, sort
215  the results in specified order.
217  .. code-block:: text
219     =none - Undefined / no particular sort order
220     =name - Sort symbols by name
221     =size - Sort symbols by size
223 .. option::  -typedefs
225  Display typedef types
227 .. option::  -types
229  Display all types (implies -classes, -enums, -typedefs)
231 Other Options
232 +++++++++++++
234 .. option:: -color-output
236  Force color output on or off.  By default, color if used if outputting to a\r
237  terminal.
239 .. option:: -load-address=<uint>
241  When displaying relative virtual addresses, assume the process is loaded at the\r
242  given address and display what would be the absolute address.
244 .. _dump_subcommand:
246 dump
247 ~~~~
249 USAGE: :program:`llvm-pdbutil` dump [*options*] <input PDB file>
251 .. program:: llvm-pdbutil dump
253 Summary
254 ^^^^^^^^^^^
256 The **dump** subcommand displays low level information about the structure of a\r
257 PDB file.  It is used heavily by LLVM's testing infrastructure, but can also be\r
258 used for PDB forensics.  It serves a role similar to that of Microsoft's\r
259 `cvdump` tool.\r
261 .. note::\r
262    The **dump** subcommand exposes internal details of the file format.  As\r
263    such, the reader should be familiar with :doc:`/PDB/index` before using this\r
264    command.
266 Options
267 ^^^^^^^
269 MSF Container Options
270 +++++++++++++++++++++
272 .. option:: -streams
274  dump a summary of all of the streams in the PDB file.
276 .. option:: -stream-blocks
278  In conjunction with :option:`-streams`, add information to the output about
279  what blocks the specified stream occupies.
281 .. option:: -summary
283  Dump MSF and PDB header information.
285 Module & File Options
286 +++++++++++++++++++++
288 .. option:: -modi=<uint>
290  For all options that dump information from each module/compiland, limit to
291  the specified module.
293 .. option:: -files
295  Dump the source files that contribute to each displayed module.
297 .. option:: -il
299  Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection)
301 .. option:: -l
303  Dump line information (DEBUG_S_LINES CodeView subsection)
305 .. option:: -modules
307  Dump compiland information
309 .. option:: -xme
311  Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection)
313 .. option:: -xmi
315  Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection)
317 Symbol Options
318 ++++++++++++++
320 .. option:: -globals
322  dump global symbol records
324 .. option:: -global-extras
326  dump additional information about the globals, such as hash buckets and hash
327  values.
329 .. option:: -publics
331  dump public symbol records
333 .. option:: -public-extras
335  dump additional information about the publics, such as hash buckets and hash
336  values.
338 .. option:: -symbols
340  dump symbols (functions, variables, etc) for each module dumped.
342 .. option:: -sym-data
344  For each symbol record dumped as a result of the :option:`-symbols` option,
345  display the full bytes of the record in binary as well.
347 Type Record Options
348 +++++++++++++++++++
350 .. option:: -types
352  Dump CodeView type records from TPI stream
354 .. option:: -type-extras
356  Dump additional information from the TPI stream, such as hashes and the type
357  index offsets array.
359 .. option:: -type-data
361  For each type record dumped, display the full bytes of the record in binary as
362  well.
364 .. option:: -type-index=<uint>
366  Only dump types with the specified type index.
368 .. option:: -ids
370  Dump CodeView type records from IPI stream.
372 .. option:: -id-extras
374  Dump additional information from the IPI stream, such as hashes and the type
375  index offsets array.
377 .. option:: -id-data
379  For each ID record dumped, display the full bytes of the record in binary as
380  well.
382 .. option:: -id-index=<uint>
384  only dump ID records with the specified hexadecimal type index.
386 .. option:: -dependents
388  When used in conjunction with :option:`-type-index` or :option:`-id-index`,
389  dumps the entire dependency graph for the specified index instead of just the
390  single record with the specified index.  For example, if type index 0x4000 is
391  a function whose return type has index 0x3000, and you specify\r
392  `-dependents=0x4000`, then this would dump both records (as well as any other\r
393  dependents in the tree).
395 Miscellaneous Options
396 +++++++++++++++++++++
398 .. option:: -all
400  Implies most other options.
402 .. option:: -section-contribs
404  Dump section contributions.
406 .. option:: -section-headers
408  Dump image section headers.
410 .. option:: -section-map
412  Dump section map.
414 .. option:: -string-table
416  Dump PDB string table.
418 .. _bytes_subcommand:
420 bytes
421 ~~~~~
423 USAGE: :program:`llvm-pdbutil` bytes [*options*] <input PDB file>
425 .. program:: llvm-pdbutil bytes
427 Summary
428 ^^^^^^^
430 Like the **dump** subcommand, the **bytes** subcommand displays low level
431 information about the structure of a PDB file, but it is used for even deeper
432 forensics.  The **bytes** subcommand finds various structures in a PDB file
433 based on the command line options specified, and dumps them in hex.  Someone
434 working on support for emitting PDBs would use this heavily, for example, to
435 compare one PDB against another PDB to ensure byte-for-byte compatibility.  It
436 is not enough to simply compare the bytes of an entire file, or an entire stream
437 because it's perfectly fine for the same structure to exist at different
438 locations in two different PDBs, and "finding" the structure is half the battle.
440 Options
441 ^^^^^^^
443 MSF File Options
444 ++++++++++++++++
446 .. option:: -block-range=<start[-end]>
448  Dump binary data from specified range of MSF file blocks.
450 .. option:: -byte-range=<start[-end]>
452  Dump binary data from specified range of bytes in the file.
454 .. option:: -fpm
456  Dump the MSF free page map.
458 .. option:: -stream-data=<string>
460  Dump binary data from the specified streams.  Format is SN[:Start][@Size].
461  For example, `-stream-data=7:3@12` dumps 12 bytes from stream 7, starting
462  at offset 3 in the stream.
464 PDB Stream Options
465 ++++++++++++++++++
467 .. option:: -name-map
469  Dump bytes of PDB Name Map
471 DBI Stream Options
472 ++++++++++++++++++
474 .. option:: -ec
476  Dump the edit and continue map substream of the DBI stream.
478 .. option:: -files
480  Dump the file info substream of the DBI stream.
482 .. option:: -modi
484  Dump the modi substream of the DBI stream.
486 .. option:: -sc
488  Dump section contributions substream of the DBI stream.
490 .. option:: -sm
492  Dump the section map from the DBI stream.
494 .. option:: -type-server
496  Dump the type server map from the DBI stream.
498 Module Options
499 ++++++++++++++
501 .. option:: -mod=<uint>
503  Limit all options in this category to the specified module index.  By default,
504  options in this category will dump bytes from all modules.
506 .. option:: -chunks
508  Dump the bytes of each module's C13 debug subsection.
510 .. option:: -split-chunks
512  When specified with :option:`-chunks`, split the C13 debug subsection into a
513  separate chunk for each subsection type, and dump them separately.
515 .. option:: -syms
517  Dump the symbol record substream from each module.
519 Type Record Options
520 +++++++++++++++++++
522 .. option:: -id=<uint>
524  Dump the record from the IPI stream with the given type index.
526 .. option:: -type=<uint>
528  Dump the record from the TPI stream with the given type index.
530 .. _pdb2yaml_subcommand:
532 pdb2yaml
533 ~~~~~~~~
535 USAGE: :program:`llvm-pdbutil` pdb2yaml [*options*] <input PDB file>
537 .. program:: llvm-pdbutil pdb2yaml
539 Summary
540 ^^^^^^^
542 Options
543 ^^^^^^^
545 .. _yaml2pdb_subcommand:
547 yaml2pdb
548 ~~~~~~~~
550 USAGE: :program:`llvm-pdbutil` yaml2pdb [*options*] <input YAML file>
552 .. program:: llvm-pdbutil yaml2pdb
554 Summary
555 ^^^^^^^
557 Generate a PDB file from a YAML description.  The YAML syntax is not described
558 here.  Instead, use :ref:`llvm-pdbutil pdb2yaml <pdb2yaml_subcommand>` and
559 examine the output for an example starting point.
561 Options
562 ^^^^^^^
564 .. option:: -pdb=<file-name>
566 Write the resulting PDB to the specified file.
568 .. _merge_subcommand:
570 merge
571 ~~~~~
573 USAGE: :program:`llvm-pdbutil` merge [*options*] <input PDB file 1> <input PDB file 2>
575 .. program:: llvm-pdbutil merge
577 Summary
578 ^^^^^^^
580 Merge two PDB files into a single file.
582 Options
583 ^^^^^^^
585 .. option:: -pdb=<file-name>
587 Write the resulting PDB to the specified file.