[PDB] read/dump fixups from PDB dbi stream

[jackoalan]

Summary

Binaries linked with /DEBUGTYPE:CV,FIXUP have a fixup substream present in the generated PDB's dbi.
This is essentially the equivalent of GCC's --emit-relocs. The fixup stream contains a list of all static
relocations performed by the linker. Each fixup entry uses the XFIXUP_DATA structure found in the cvdump
reference implementation.

Changes to llvm-pdbutil's dump tool can dump this information with -fixups or -all. The DbiStream public
API provides access to this stream array for tools that may be interested in cross-referencing symbols with
their usages.

[jackoalan]

I'd like some input on whether or not to include fixup dumping in the -all option. Relocations can quickly become numerous in a moderately complex binary.

On the other hand, fixups aren't included in binaries with default linker options, so it's reasonable to assume if the PDB includes these, the developer is interested in accessing them.

llvm/docs/PDB/DbiStream.rst

 **FPO Data** - ``DbgStreamArray[0]``.  The data in the referenced stream is an
 array of ``FPO_DATA`` structures.  This contains the relocated contents of
 any ``.debug$F`` section from any of the linker inputs.
 
 **Exception Data** - ``DbgStreamArray[1]``.  The data in the referenced stream
 is a debug data directory of type ``IMAGE_DEBUG_TYPE_EXCEPTION``.
 
 **Fixup Data** - ``DbgStreamArray[2]``.  The data in the referenced stream is a
-debug data directory of type ``IMAGE_DEBUG_TYPE_FIXUP``.
+debug data directory of type ``IMAGE_DEBUG_TYPE_FIXUP``.  This stream is present
+when linked with ``/DEBUGTYPE:FIXUP``.  It contains records of all relocations
+performed by the linker.
 
 **Omap To Src Data** - ``DbgStreamArray[3]``.  The data in the referenced stream
 is a debug data directory of type ``IMAGE_DEBUG_TYPE_OMAP_TO_SRC``.  This 
 is used for mapping addresses between instrumented and uninstrumented code.
 
 **Omap From Src Data** - ``DbgStreamArray[4]``.  The data in the referenced stream
 is a debug data directory of type ``IMAGE_DEBUG_TYPE_OMAP_FROM_SRC``.  This 
 is used for mapping addresses between instrumented and uninstrumented code.

llvm/include/llvm/DebugInfo/PDB/Native/DbiStream.h

public:
 
   FixedStreamArray<object::coff_section> getSectionHeaders() const;
 
   bool hasOldFpoRecords() const;
   FixedStreamArray<object::FpoData> getOldFpoRecords() const;
   bool hasNewFpoRecords() const;
   const codeview::DebugFrameDataSubsectionRef &getNewFpoRecords() const;
 
+  bool hasFixupRecords() const;
+  FixedStreamArray<FixupEntry> getFixupRecords() const;
+
   FixedStreamArray<SecMapEntry> getSectionMap() const;
   void visitSectionContributions(ISectionContribVisitor &Visitor) const;
 
   Expected<StringRef> getECName(uint32_t NI) const;
 
 private:
   Error initializeSectionContributionData();
   Error initializeSectionHeadersData(PDBFile *Pdb);
   Error initializeSectionMapData();
   Error initializeOldFpoRecords(PDBFile *Pdb);
   Error initializeNewFpoRecords(PDBFile *Pdb);
+  Error initializeFixupRecords(PDBFile *Pdb);
 
   Expected<std::unique_ptr<msf::MappedBlockStream>>
   createIndexedStreamForHeaderType(PDBFile *Pdb, DbgHeaderType Type) const;
 
   std::unique_ptr<BinaryStream> Stream;
 
   PDBStringTable ECNames;
 
private:
   FixedStreamArray<object::coff_section> SectionHeaders;
 
   std::unique_ptr<msf::MappedBlockStream> OldFpoStream;
   FixedStreamArray<object::FpoData> OldFpoRecords;
   
   std::unique_ptr<msf::MappedBlockStream> NewFpoStream;
   codeview::DebugFrameDataSubsectionRef NewFpoRecords;
 
+  std::unique_ptr<msf::MappedBlockStream> FixupStream;
+  FixedStreamArray<FixupEntry> FixupRecords;
+
   const DbiStreamHeader *Header;
 };
 }
 }
 
 #endif

llvm/include/llvm/DebugInfo/PDB/Native/RawTypes.h

struct SrcHeaderBlockEntry {
   support::ulittle32_t VFileNI;  // String table index of virtual file name.
   uint8_t Compression;           // PDB_SourceCompression enumeration.
   uint8_t IsVirtual;             // Is this a virtual file (injected)?
   short Padding;                 // Pad to 4 bytes.
   char Reserved[8];
 };
 static_assert(sizeof(SrcHeaderBlockEntry) == 40, "Incorrect struct size!");
 
+/// A relocation entry within the Fixup substream of the DBI stream.
+/// Corresponds to XFIXUP_DATA in the reference implementation.
+struct FixupEntry {
+  support::ulittle16_t Type;
+  support::ulittle16_t Extra;
+  support::ulittle32_t RVA;
+  support::ulittle32_t RVATarget;
+};
+static_assert(sizeof(FixupEntry) == 12, "Incorrect struct size!");
+
 } // namespace pdb
 } // namespace llvm
 
 #endif

llvm/include/llvm/Object/COFF.h

const coff_load_configuration32 *getLoadConfig32() const {
     assert(!is64());
     return reinterpret_cast<const coff_load_configuration32 *>(LoadConfig);
   }
 
   const coff_load_configuration64 *getLoadConfig64() const {
     assert(is64());
     return reinterpret_cast<const coff_load_configuration64 *>(LoadConfig);
   }
-  StringRef getRelocationTypeName(uint16_t Type) const;
+  static StringRef getRelocationTypeName(uint16_t Type, uint16_t Machine);
+  StringRef getRelocationTypeName(uint16_t Type) const {
+    return getRelocationTypeName(Type, getMachine());
+  }
 
 protected:
   void moveSymbolNext(DataRefImpl &Symb) const override;
   Expected<StringRef> getSymbolName(DataRefImpl Symb) const override;
   Expected<uint64_t> getSymbolAddress(DataRefImpl Symb) const override;
   uint32_t getSymbolAlignment(DataRefImpl Symb) const override;
   uint64_t getSymbolValueImpl(DataRefImpl Symb) const override;
   uint64_t getCommonSymbolSizeImpl(DataRefImpl Symb) const override;

llvm/lib/DebugInfo/PDB/Native/DbiStream.cpp

if (auto EC = initializeSectionContributionData())
     return EC;
   if (auto EC = initializeSectionHeadersData(Pdb))
     return EC;
   if (auto EC = initializeSectionMapData())
     return EC;
   if (auto EC = initializeOldFpoRecords(Pdb))
     return EC;
   if (auto EC = initializeNewFpoRecords(Pdb))
-     return EC;
+  if (auto EC = initializeFixupRecords(Pdb))
+    return EC;
 
   if (Reader.bytesRemaining() > 0)
     return make_error<RawError>(raw_error_code::corrupt_file,
                                 "Found unexpected bytes in DBI Stream.");
 
   if (!ECSubstream.empty()) {
     BinaryStreamReader ECReader(ECSubstream.StreamData);
     if (auto EC = ECNames.reload(ECReader))

 }
 
 bool DbiStream::hasNewFpoRecords() const { return NewFpoStream != nullptr; }
 
 const DebugFrameDataSubsectionRef &DbiStream::getNewFpoRecords() const {
   return NewFpoRecords;
 }
 
+bool DbiStream::hasFixupRecords() const { return FixupStream != nullptr; }
+
+FixedStreamArray<FixupEntry> DbiStream::getFixupRecords() const {
+  return FixupRecords;
+}
+
 const DbiModuleList &DbiStream::modules() const { return Modules; }
 
 FixedStreamArray<SecMapEntry> DbiStream::getSectionMap() const {
   return SectionMap;
 }
 
 void DbiStream::visitSectionContributions(
     ISectionContribVisitor &Visitor) const {
Error DbiStream::initializeNewFpoRecords(PDBFile *Pdb) {
 
   if (auto EC = NewFpoRecords.initialize(*FS))
     return EC;
 
   NewFpoStream = std::move(FS);
   return Error::success();
 }
 
+Error DbiStream::initializeFixupRecords(PDBFile *Pdb) {
+  Expected<std::unique_ptr<msf::MappedBlockStream>> ExpectedStream =
+      createIndexedStreamForHeaderType(Pdb, DbgHeaderType::Fixup);
+  if (auto EC = ExpectedStream.takeError())
+    return EC;
+
+  auto &FS = *ExpectedStream;
+  if (!FS)
+    return Error::success();
+
+  size_t StreamLen = FS->getLength();
+  if (StreamLen % sizeof(FixupEntry))
+    return make_error<RawError>(raw_error_code::corrupt_file,
+                                "Corrupted Fixup stream.");
+
+  size_t NumRecords = StreamLen / sizeof(FixupEntry);
+  BinaryStreamReader Reader(*FS);
+  if (auto EC = Reader.readArray(FixupRecords, NumRecords))
+    return make_error<RawError>(raw_error_code::corrupt_file,
+                                "Corrupted Fixup stream.");
+  FixupStream = std::move(FS);
+  return Error::success();
+}
+
 Expected<std::unique_ptr<msf::MappedBlockStream>>
 DbiStream::createIndexedStreamForHeaderType(PDBFile *Pdb,
                                             DbgHeaderType Type) const {
   if (!Pdb)
     return nullptr;
 
   if (DbgStreams.empty())
     return nullptr;

llvm/lib/Object/COFFObjectFile.cpp

COFFObjectFile::getRelocations(const coff_section *Sec) const {
   return {getFirstReloc(Sec, Data, base()),
           getNumberOfRelocations(Sec, Data, base())};
 }
 
 #define LLVM_COFF_SWITCH_RELOC_TYPE_NAME(reloc_type)                           \
   case COFF::reloc_type:                                                       \
     return #reloc_type;
 
-StringRef COFFObjectFile::getRelocationTypeName(uint16_t Type) const {
-  switch (getMachine()) {
+StringRef COFFObjectFile::getRelocationTypeName(uint16_t Type,
+                                                uint16_t Machine) {
+  switch (Machine) {
   case COFF::IMAGE_FILE_MACHINE_AMD64:
     switch (Type) {
     LLVM_COFF_SWITCH_RELOC_TYPE_NAME(IMAGE_REL_AMD64_ABSOLUTE);
     LLVM_COFF_SWITCH_RELOC_TYPE_NAME(IMAGE_REL_AMD64_ADDR64);
     LLVM_COFF_SWITCH_RELOC_TYPE_NAME(IMAGE_REL_AMD64_ADDR32);
     LLVM_COFF_SWITCH_RELOC_TYPE_NAME(IMAGE_REL_AMD64_ADDR32NB);
     LLVM_COFF_SWITCH_RELOC_TYPE_NAME(IMAGE_REL_AMD64_REL32);
     LLVM_COFF_SWITCH_RELOC_TYPE_NAME(IMAGE_REL_AMD64_REL32_1);

llvm/test/tools/llvm-pdbutil/Inputs/FixupsTest.cpp

+// Compile with "cl /c /Zi /GR- FixupsTest.cpp" on amd64
+// Link with "link FixupsTest.obj /debug /debugtype:cv,fixup /nodefaultlib /entry:main"
+
+int IntGlobalVar;
+
+// IMAGE_REL_AMD64_ADDR64         |    0x0 |     0x3000 |     0x3008
+int *PtrToGlobal = &IntGlobalVar;
+
+int Func(int IntParam) {
+  return IntParam;
+}
+
+int main(int argc, char **argv) {
+  // IMAGE_REL_AMD64_REL32          |    0x0 |     0x101F |     0x3008
+  // IMAGE_REL_AMD64_REL32          | 0x8000 |     0x1024 |     0x1000
+  Func(IntGlobalVar);
+  // IMAGE_REL_AMD64_REL32          |    0x0 |     0x102B |     0x3000
+  // IMAGE_REL_AMD64_REL32          | 0x8000 |     0x1032 |     0x1000
+  Func(*PtrToGlobal);
+  return 0;
+}

llvm/test/tools/llvm-pdbutil/fixups.test

+; RUN: llvm-pdbutil dump -fixups %p/Inputs/FixupsTest.pdb \
+; RUN:     | FileCheck %s
+
+CHECK:                            Fixups
+CHECK-NEXT: ============================================================
+CHECK-NEXT:              Type              | Extra  |    RVA     | RVATarget
+CHECK-NEXT: IMAGE_REL_AMD64_ADDR64         |    0x0 |     0x3000 |     0x3008
+CHECK-NEXT: IMAGE_REL_AMD64_REL32          |    0x0 |     0x101F |     0x3008
+CHECK-NEXT: IMAGE_REL_AMD64_REL32          | 0x8000 |     0x1024 |     0x1000
+CHECK-NEXT: IMAGE_REL_AMD64_REL32          |    0x0 |     0x102B |     0x3000
+CHECK-NEXT: IMAGE_REL_AMD64_REL32          | 0x8000 |     0x1032 |     0x1000

llvm/test/tools/llvm-pdbutil/stripped.test

 ; CHECK-NEXT: ============================================================
 
 ; CHECK: Old FPO Data
 ; CHECK-NEXT: ============================================================
 
 ; CHECK: New FPO Data
 ; CHECK-NEXT: ============================================================
 
+; CHECK: Fixups
+; CHECK-NEXT: ============================================================
+
 ; CHECK: Types (TPI Stream)
 ; CHECK-NEXT: ============================================================
 
 ; CHECK: Types (IPI Stream)
 ; CHECK-NEXT: ============================================================
 
 ; CHECK: Global Symbols
 ; CHECK-NEXT: ============================================================

llvm/test/tools/llvm-pdbutil/type-server-no-dbi.test

 NO-DBI:                     Cross Module Imports
 NO-DBI-NEXT: ============================================================
 NO-DBI-NEXT:     DBI stream not present
 
 NO-DBI:                     Cross Module Exports
 NO-DBI-NEXT: ============================================================
 NO-DBI-NEXT:     DBI stream not present
 
+NO-DBI:                            Fixups
+NO-DBI-NEXT: ============================================================
+NO-DBI-NEXT:     DBI stream not present
+
 
 NO-DBI-YAML-NOT: Native PDB Error: The specified stream could not be loaded.
 
 NO-DBI-YAML: TpiStream:
 NO-DBI-YAML-NEXT:  Version:         VC80
 NO-DBI-YAML-NEXT:  Records:
 NO-DBI-YAML-NEXT:    - Kind:            LF_ARGLIST

llvm/tools/llvm-pdbutil/DumpOutputStyle.h

private:
   Error dumpStringTableFromObj();
   Error dumpLines();
   Error dumpInlineeLines();
   Error dumpXmi();
   Error dumpXme();
   Error dumpFpo();
   Error dumpOldFpo(PDBFile &File);
   Error dumpNewFpo(PDBFile &File);
+  Error dumpFixups();
   Error dumpTpiStream(uint32_t StreamIdx);
   Error dumpTypesFromObjectFile();
   Error dumpTypeRefStats();
   Error dumpModules();
   Error dumpModuleFiles();
   Error dumpModuleSymsForPdb();
   Error dumpModuleSymsForObj();
   Error dumpGSIRecords();

llvm/tools/llvm-pdbutil/DumpOutputStyle.cpp

if (auto EC = dumpXme())
       return EC;
   }
 
   if (opts::dump::DumpFpo) {
     if (auto EC = dumpFpo())
       return EC;
   }
 
+  if (opts::dump::DumpFixups) {
+    if (auto EC = dumpFixups())
+      return EC;
+  }
+
   if (File.isObj()) {
     if (opts::dump::DumpTypes || !opts::dump::DumpTypeIndex.empty() ||
         opts::dump::DumpTypeExtras)
       if (auto EC = dumpTypesFromObjectFile())
         return EC;
   } else {
     if (opts::dump::DumpTypes || !opts::dump::DumpTypeIndex.empty() ||
         opts::dump::DumpTypeExtras) {
Error DumpOutputStyle::dumpFpo() {
 
   if (auto EC = dumpOldFpo(File))
     return EC;
   if (auto EC = dumpNewFpo(File))
     return EC;
   return Error::success();
 }
 
+Error DumpOutputStyle::dumpFixups() {
+  printHeader(P, "Fixups");
+
+  if (File.isObj()) {
+    printStreamNotValidForObj();
+    return Error::success();
+  }
+
+  if (!getPdb().hasPDBDbiStream()) {
+    printStreamNotPresent("DBI");
+    return Error::success();
+  }
+
+  auto &Dbi = cantFail(getPdb().getPDBDbiStream());
+
+  if (!Dbi.hasFixupRecords()) {
+    P.printLine(
+        "PDB does not contain fixup stream (link with /DEBUGTYPE:CV,FIXUP)");
+    return Error::success();
+  }
+
+  P.printLine(
+      "             Type              | Extra  |    RVA     | RVATarget");
+
+  for (const auto &F : Dbi.getFixupRecords()) {
+    StringRef RelocationType = object::COFFObjectFile::getRelocationTypeName(
+        F.Type, static_cast<uint16_t>(Dbi.getMachineType()));
+    if (RelocationType != "Unknown") {
+      P.formatLine("{0,-30} | {1,6:X} | {2,10:X} | {3,10:X}", RelocationType,
+                   fmtle(F.Extra), fmtle(F.RVA), fmtle(F.RVATarget));
+    } else {
+      P.formatLine("{0,30:X} | {1,6:X} | {2,10:X} | {3,10:X}", fmtle(F.Type),
+                   fmtle(F.Extra), fmtle(F.RVA), fmtle(F.RVATarget));
+    }
+  }
+
+  return Error::success();
+}
+
 Error DumpOutputStyle::dumpStringTableFromPdb() {
   AutoIndent Indent(P);
   auto IS = getPdb().getStringTable();
   if (!IS) {
     P.formatLine("Not present in file");
     consumeError(IS.takeError());
     return Error::success();
   }

llvm/tools/llvm-pdbutil/llvm-pdbutil.h

 extern llvm::cl::opt<bool> DumpGlobalExtras;
 extern llvm::cl::opt<bool> DumpPublics;
 extern llvm::cl::opt<bool> DumpPublicExtras;
 extern llvm::cl::opt<bool> DumpSectionContribs;
 extern llvm::cl::opt<bool> DumpSectionMap;
 extern llvm::cl::opt<bool> DumpModules;
 extern llvm::cl::opt<bool> DumpModuleFiles;
 extern llvm::cl::opt<bool> DumpFpo;
+extern llvm::cl::opt<bool> DumpFixups;
 extern llvm::cl::opt<bool> RawAll;
 }
 
 namespace pdb2yaml {
 extern llvm::cl::opt<bool> All;
 extern llvm::cl::opt<bool> NoFileHeaders;
 extern llvm::cl::opt<bool> Minimal;
 extern llvm::cl::opt<bool> StreamMetadata;

llvm/tools/llvm-pdbutil/llvm-pdbutil.cpp

 cl::opt<bool>
     DumpSymRecordBytes("sym-data",
                        cl::desc("dump CodeView symbol record raw bytes"),
                        cl::cat(SymbolOptions), cl::sub(DumpSubcommand));
 
 cl::opt<bool> DumpFpo("fpo", cl::desc("dump FPO records"),
                       cl::cat(SymbolOptions), cl::sub(DumpSubcommand));
 
+cl::opt<bool> DumpFixups("fixups", cl::desc("dump fixups"),
+                         cl::cat(SymbolOptions), cl::sub(DumpSubcommand));
+
 // MODULE & FILE OPTIONS
 cl::opt<bool> DumpModules("modules", cl::desc("dump compiland information"),
                           cl::cat(FileOptions), cl::sub(DumpSubcommand));
 cl::opt<bool> DumpModuleFiles(
     "files",
     cl::desc("Dump the source files that contribute to each module's."),
     cl::cat(FileOptions), cl::sub(DumpSubcommand));
 cl::opt<bool> DumpLines(
if (!parseRange(opts::bytes::DumpByteRangeOpt,
       exit(1);
     }
   }
 
   if (opts::DumpSubcommand) {
     if (opts::dump::RawAll) {
       opts::dump::DumpGlobals = true;
       opts::dump::DumpFpo = true;
+      opts::dump::DumpFixups = true;
       opts::dump::DumpInlineeLines = true;
       opts::dump::DumpIds = true;
       opts::dump::DumpIdExtras = true;
       opts::dump::DumpLines = true;
       opts::dump::DumpModules = true;
       opts::dump::DumpModuleFiles = true;
       opts::dump::DumpPublics = true;
       opts::dump::DumpSectionContribs = true;