docs/CommandGuide/llvm-pdbutil.rst

   1 llvm-pdbutil - PDB File forensics and diagnostics
   2 =================================================
   3
   4 .. program:: llvm-pdbutil
   5
   6 .. contents::
   7    :local:
   8
   9 Synopsis
  10 --------
  11
  12 :program:`llvm-pdbutil` [*subcommand*] [*options*]
  13
  14 Description
  15 -----------
  16
  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.
  22
  23 Subcommands
  24 -----------
  25
  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.
  29
  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.
  43
  44 .. _pretty_subcommand:
  45
  46 pretty
  47 ~~~~~~
  48
  49 .. program:: llvm-pdbutil pretty
  50
  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.
  54
  55 USAGE: :program:`llvm-pdbutil` pretty [*options*] <input PDB file>
  56
  57 Summary
  58 ^^^^^^^^^^^
  59
  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.
  65
  66 Options
  67 ^^^^^^^
  68
  69 Filtering and Sorting Options
  70 +++++++++++++++++++++++++++++
  71
  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.
  75
  76 .. option:: -exclude-compilands=<string>
  77
  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.
  81
  82 .. option:: -exclude-symbols=<string>
  83
  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.
  87
  88 .. option:: -exclude-types=<string>
  89
  90  When dumping types, this option instructs **llvm-pdbutil** to omit any types\r
  91  that match the specified regular expression.
  92
  93 .. option:: -include-compilands=<string>
  94
  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.
  98
  99 .. option:: -include-symbols=<string>
 100
 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.
 103
 104 .. option:: -include-types=<string>
 105
 106  When dumping types, limit the initial search to only those types that match\r
 107  the specified regular expression.
 108
 109 .. option:: -min-class-padding=<uint>
 110
 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.
 113
 114 .. option:: -min-class-padding-imm=<uint>
 115
 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.
 118
 119 .. option:: -min-type-size=<uint>
 120
 121  Only display types T where sizeof(T) is greater than or equal to the specified\r
 122  amount.
 123
 124 .. option:: -no-compiler-generated
 125
 126  Don't show compiler generated types and symbols
 127
 128 .. option:: -no-enum-definitions
 129
 130  When dumping an enum, don't show the full enum (e.g. the individual enumerator\r
 131  values).
 132
 133 .. option:: -no-system-libs
 134
 135  Don't show symbols from system libraries
 136
 137 Symbol Type Options
 138 +++++++++++++++++++
 139 .. option:: -all
 140
 141  Implies all other options in this category.
 142
 143 .. option:: -class-definitions=<format>
 144
 145  Displays class definitions in the specified format.
 146
 147  .. code-block:: text
 148
 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)
 152
 153 .. option:: -class-order
 154
 155  Displays classes in the specified order.
 156
 157  .. code-block:: text
 158
 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
 166
 167 .. option::  -class-recurse-depth=<uint>
 168
 169  When dumping class definitions, stop after recursing the specified number of times.  The
 170  default is 0, which is no limit.
 171
 172 .. option::  -classes
 173
 174  Display classes
 175
 176 .. option::  -compilands
 177
 178  Display compilands (e.g. object files)
 179
 180 .. option::  -enums
 181
 182  Display enums
 183
 184 .. option::  -externals
 185
 186  Dump external (e.g. exported) symbols
 187
 188 .. option::  -globals
 189
 190  Dump global symbols
 191
 192 .. option::  -lines
 193
 194  Dump the mappings between source lines and code addresses.
 195
 196 .. option::  -module-syms
 197
 198  Display symbols (variables, functions, etc) for each compiland
 199
 200 .. option::  -sym-types=<types>
 201
 202  Type of symbols to dump when -globals, -externals, or -module-syms is
 203  specified. (default all)
 204
 205  .. code-block:: text
 206
 207     =thunks - Display thunk symbols
 208     =data   - Display data symbols
 209     =funcs  - Display function symbols
 210     =all    - Display all symbols (default)
 211
 212 .. option::  -symbol-order=<order>
 213
 214  For symbols dumped via the -module-syms, -globals, or -externals options, sort
 215  the results in specified order.
 216
 217  .. code-block:: text
 218
 219     =none - Undefined / no particular sort order
 220     =name - Sort symbols by name
 221     =size - Sort symbols by size
 222
 223 .. option::  -typedefs
 224
 225  Display typedef types
 226
 227 .. option::  -types
 228
 229  Display all types (implies -classes, -enums, -typedefs)
 230
 231 Other Options
 232 +++++++++++++
 233
 234 .. option:: -color-output
 235
 236  Force color output on or off.  By default, color if used if outputting to a\r
 237  terminal.
 238
 239 .. option:: -load-address=<uint>
 240
 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.
 243
 244 .. _dump_subcommand:
 245
 246 dump
 247 ~~~~
 248
 249 USAGE: :program:`llvm-pdbutil` dump [*options*] <input PDB file>
 250
 251 .. program:: llvm-pdbutil dump
 252
 253 Summary
 254 ^^^^^^^^^^^
 255
 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
 260 \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.
 265
 266 Options
 267 ^^^^^^^
 268
 269 MSF Container Options
 270 +++++++++++++++++++++
 271
 272 .. option:: -streams
 273
 274  dump a summary of all of the streams in the PDB file.
 275
 276 .. option:: -stream-blocks
 277
 278  In conjunction with :option:`-streams`, add information to the output about
 279  what blocks the specified stream occupies.
 280
 281 .. option:: -summary
 282
 283  Dump MSF and PDB header information.
 284
 285 Module & File Options
 286 +++++++++++++++++++++
 287
 288 .. option:: -modi=<uint>
 289
 290  For all options that dump information from each module/compiland, limit to
 291  the specified module.
 292
 293 .. option:: -files
 294
 295  Dump the source files that contribute to each displayed module.
 296
 297 .. option:: -il
 298
 299  Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection)
 300
 301 .. option:: -l
 302
 303  Dump line information (DEBUG_S_LINES CodeView subsection)
 304
 305 .. option:: -modules
 306
 307  Dump compiland information
 308
 309 .. option:: -xme
 310
 311  Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection)
 312
 313 .. option:: -xmi
 314
 315  Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection)
 316
 317 Symbol Options
 318 ++++++++++++++
 319
 320 .. option:: -globals
 321
 322  dump global symbol records
 323
 324 .. option:: -global-extras
 325
 326  dump additional information about the globals, such as hash buckets and hash
 327  values.
 328
 329 .. option:: -publics
 330
 331  dump public symbol records
 332
 333 .. option:: -public-extras
 334
 335  dump additional information about the publics, such as hash buckets and hash
 336  values.
 337
 338 .. option:: -symbols
 339
 340  dump symbols (functions, variables, etc) for each module dumped.
 341
 342 .. option:: -sym-data
 343
 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.
 346
 347 Type Record Options
 348 +++++++++++++++++++
 349
 350 .. option:: -types
 351
 352  Dump CodeView type records from TPI stream
 353
 354 .. option:: -type-extras
 355
 356  Dump additional information from the TPI stream, such as hashes and the type
 357  index offsets array.
 358
 359 .. option:: -type-data
 360
 361  For each type record dumped, display the full bytes of the record in binary as
 362  well.
 363
 364 .. option:: -type-index=<uint>
 365
 366  Only dump types with the specified type index.
 367
 368 .. option:: -ids
 369
 370  Dump CodeView type records from IPI stream.
 371
 372 .. option:: -id-extras
 373
 374  Dump additional information from the IPI stream, such as hashes and the type
 375  index offsets array.
 376
 377 .. option:: -id-data
 378
 379  For each ID record dumped, display the full bytes of the record in binary as
 380  well.
 381
 382 .. option:: -id-index=<uint>
 383
 384  only dump ID records with the specified hexadecimal type index.
 385
 386 .. option:: -dependents
 387
 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).
 394
 395 Miscellaneous Options
 396 +++++++++++++++++++++
 397
 398 .. option:: -all
 399
 400  Implies most other options.
 401
 402 .. option:: -section-contribs
 403
 404  Dump section contributions.
 405
 406 .. option:: -section-headers
 407
 408  Dump image section headers.
 409
 410 .. option:: -section-map
 411
 412  Dump section map.
 413
 414 .. option:: -string-table
 415
 416  Dump PDB string table.
 417
 418 .. _bytes_subcommand:
 419
 420 bytes
 421 ~~~~~
 422
 423 USAGE: :program:`llvm-pdbutil` bytes [*options*] <input PDB file>
 424
 425 .. program:: llvm-pdbutil bytes
 426
 427 Summary
 428 ^^^^^^^
 429
 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.
 439
 440 Options
 441 ^^^^^^^
 442
 443 MSF File Options
 444 ++++++++++++++++
 445
 446 .. option:: -block-range=<start[-end]>
 447
 448  Dump binary data from specified range of MSF file blocks.
 449
 450 .. option:: -byte-range=<start[-end]>
 451
 452  Dump binary data from specified range of bytes in the file.
 453
 454 .. option:: -fpm
 455
 456  Dump the MSF free page map.
 457
 458 .. option:: -stream-data=<string>
 459
 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.
 463
 464 PDB Stream Options
 465 ++++++++++++++++++
 466
 467 .. option:: -name-map
 468
 469  Dump bytes of PDB Name Map
 470
 471 DBI Stream Options
 472 ++++++++++++++++++
 473
 474 .. option:: -ec
 475
 476  Dump the edit and continue map substream of the DBI stream.
 477
 478 .. option:: -files
 479
 480  Dump the file info substream of the DBI stream.
 481
 482 .. option:: -modi
 483
 484  Dump the modi substream of the DBI stream.
 485
 486 .. option:: -sc
 487
 488  Dump section contributions substream of the DBI stream.
 489
 490 .. option:: -sm
 491
 492  Dump the section map from the DBI stream.
 493
 494 .. option:: -type-server
 495
 496  Dump the type server map from the DBI stream.
 497
 498 Module Options
 499 ++++++++++++++
 500
 501 .. option:: -mod=<uint>
 502
 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.
 505
 506 .. option:: -chunks
 507
 508  Dump the bytes of each module's C13 debug subsection.
 509
 510 .. option:: -split-chunks
 511
 512  When specified with :option:`-chunks`, split the C13 debug subsection into a
 513  separate chunk for each subsection type, and dump them separately.
 514
 515 .. option:: -syms
 516
 517  Dump the symbol record substream from each module.
 518
 519 Type Record Options
 520 +++++++++++++++++++
 521
 522 .. option:: -id=<uint>
 523
 524  Dump the record from the IPI stream with the given type index.
 525
 526 .. option:: -type=<uint>
 527
 528  Dump the record from the TPI stream with the given type index.
 529
 530 .. _pdb2yaml_subcommand:
 531
 532 pdb2yaml
 533 ~~~~~~~~
 534
 535 USAGE: :program:`llvm-pdbutil` pdb2yaml [*options*] <input PDB file>
 536
 537 .. program:: llvm-pdbutil pdb2yaml
 538
 539 Summary
 540 ^^^^^^^
 541
 542 Options
 543 ^^^^^^^
 544
 545 .. _yaml2pdb_subcommand:
 546
 547 yaml2pdb
 548 ~~~~~~~~
 549
 550 USAGE: :program:`llvm-pdbutil` yaml2pdb [*options*] <input YAML file>
 551
 552 .. program:: llvm-pdbutil yaml2pdb
 553
 554 Summary
 555 ^^^^^^^
 556
 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.
 560
 561 Options
 562 ^^^^^^^
 563
 564 .. option:: -pdb=<file-name>
 565
 566 Write the resulting PDB to the specified file.
 567
 568 .. _merge_subcommand:
 569
 570 merge
 571 ~~~~~
 572
 573 USAGE: :program:`llvm-pdbutil` merge [*options*] <input PDB file 1> <input PDB file 2>
 574
 575 .. program:: llvm-pdbutil merge
 576
 577 Summary
 578 ^^^^^^^
 579
 580 Merge two PDB files into a single file.
 581
 582 Options
 583 ^^^^^^^
 584
 585 .. option:: -pdb=<file-name>
 586
 587 Write the resulting PDB to the specified file.