xref: /freebsd/contrib/llvm-project/llvm/tools/llvm-pdbutil/ExplainOutputStyle.cpp (revision 7ef62cebc2f965b0f640263e179276928885e33d) 
1 //===- ExplainOutputStyle.cpp --------------------------------- *- C++ --*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #include "ExplainOutputStyle.h"
10 
11 #include "StreamUtil.h"
12 #include "llvm-pdbutil.h"
13 
14 #include "llvm/DebugInfo/CodeView/Formatters.h"
15 #include "llvm/DebugInfo/CodeView/LazyRandomTypeCollection.h"
16 #include "llvm/DebugInfo/MSF/MappedBlockStream.h"
17 #include "llvm/DebugInfo/PDB/Native/DbiStream.h"
18 #include "llvm/DebugInfo/PDB/Native/FormatUtil.h"
19 #include "llvm/DebugInfo/PDB/Native/InfoStream.h"
20 #include "llvm/DebugInfo/PDB/Native/InputFile.h"
21 #include "llvm/DebugInfo/PDB/Native/NativeSession.h"
22 #include "llvm/DebugInfo/PDB/Native/PDBFile.h"
23 #include "llvm/DebugInfo/PDB/Native/RawTypes.h"
24 #include "llvm/Object/COFF.h"
25 #include "llvm/Support/BinaryByteStream.h"
26 #include "llvm/Support/BinaryStreamArray.h"
27 #include "llvm/Support/Error.h"
28 
29 using namespace llvm;
30 using namespace llvm::codeview;
31 using namespace llvm::msf;
32 using namespace llvm::pdb;
33 
34 ExplainOutputStyle::ExplainOutputStyle(InputFile &File, uint64_t FileOffset)
35     : File(File), FileOffset(FileOffset), P(2, false, outs(), opts::Filters) {}
36 
37 Error ExplainOutputStyle::dump() {
38   P.formatLine("Explaining file offset {0} of file '{1}'.", FileOffset,
39                File.getFilePath());
40 
41   if (File.isPdb())
42     return explainPdbFile();
43 
44   return explainBinaryFile();
45 }
46 
47 Error ExplainOutputStyle::explainPdbFile() {
48   bool IsAllocated = explainPdbBlockStatus();
49   if (!IsAllocated)
50     return Error::success();
51 
52   AutoIndent Indent(P);
53   if (isPdbSuperBlock())
54     explainPdbSuperBlockOffset();
55   else if (isPdbFpmBlock())
56     explainPdbFpmBlockOffset();
57   else if (isPdbBlockMapBlock())
58     explainPdbBlockMapOffset();
59   else if (isPdbStreamDirectoryBlock())
60     explainPdbStreamDirectoryOffset();
61   else if (auto Index = getPdbBlockStreamIndex())
62     explainPdbStreamOffset(*Index);
63   else
64     explainPdbUnknownBlock();
65   return Error::success();
66 }
67 
68 Error ExplainOutputStyle::explainBinaryFile() {
69   std::unique_ptr<BinaryByteStream> Stream =
70       std::make_unique<BinaryByteStream>(File.unknown().getBuffer(),
71                                           llvm::support::little);
72   switch (opts::explain::InputType) {
73   case opts::explain::InputFileType::DBIStream: {
74     DbiStream Dbi(std::move(Stream));
75     if (auto EC = Dbi.reload(nullptr))
76       return EC;
77     explainStreamOffset(Dbi, FileOffset);
78     break;
79   }
80   case opts::explain::InputFileType::PDBStream: {
81     InfoStream Info(std::move(Stream));
82     if (auto EC = Info.reload())
83       return EC;
84     explainStreamOffset(Info, FileOffset);
85     break;
86   }
87   default:
88     llvm_unreachable("Invalid input file type!");
89   }
90   return Error::success();
91 }
92 
93 uint32_t ExplainOutputStyle::pdbBlockIndex() const {
94   return FileOffset / File.pdb().getBlockSize();
95 }
96 
97 uint32_t ExplainOutputStyle::pdbBlockOffset() const {
98   uint64_t BlockStart = pdbBlockIndex() * File.pdb().getBlockSize();
99   assert(FileOffset >= BlockStart);
100   return FileOffset - BlockStart;
101 }
102 
103 bool ExplainOutputStyle::isPdbSuperBlock() const {
104   return pdbBlockIndex() == 0;
105 }
106 
107 bool ExplainOutputStyle::isPdbFpm1() const {
108   return ((pdbBlockIndex() - 1) % File.pdb().getBlockSize() == 0);
109 }
110 bool ExplainOutputStyle::isPdbFpm2() const {
111   return ((pdbBlockIndex() - 2) % File.pdb().getBlockSize() == 0);
112 }
113 
114 bool ExplainOutputStyle::isPdbFpmBlock() const {
115   return isPdbFpm1() || isPdbFpm2();
116 }
117 
118 bool ExplainOutputStyle::isPdbBlockMapBlock() const {
119   return pdbBlockIndex() == File.pdb().getBlockMapIndex();
120 }
121 
122 bool ExplainOutputStyle::isPdbStreamDirectoryBlock() const {
123   const auto &Layout = File.pdb().getMsfLayout();
124   return llvm::is_contained(Layout.DirectoryBlocks, pdbBlockIndex());
125 }
126 
127 std::optional<uint32_t> ExplainOutputStyle::getPdbBlockStreamIndex() const {
128   const auto &Layout = File.pdb().getMsfLayout();
129   for (const auto &Entry : enumerate(Layout.StreamMap)) {
130     if (!llvm::is_contained(Entry.value(), pdbBlockIndex()))
131       continue;
132     return Entry.index();
133   }
134   return std::nullopt;
135 }
136 
137 bool ExplainOutputStyle::explainPdbBlockStatus() {
138   if (FileOffset >= File.pdb().getFileSize()) {
139     P.formatLine("Address {0} is not in the file (file size = {1}).",
140                  FileOffset, File.pdb().getFileSize());
141     return false;
142   }
143   P.formatLine("Block:Offset = {2:X-}:{1:X-4}.", FileOffset, pdbBlockOffset(),
144                pdbBlockIndex());
145 
146   bool IsFree = File.pdb().getMsfLayout().FreePageMap[pdbBlockIndex()];
147   P.formatLine("Address is in block {0} ({1}allocated).", pdbBlockIndex(),
148                IsFree ? "un" : "");
149   return !IsFree;
150 }
151 
152 #define endof(Class, Field) (offsetof(Class, Field) + sizeof(Class::Field))
153 
154 void ExplainOutputStyle::explainPdbSuperBlockOffset() {
155   P.formatLine("This corresponds to offset {0} of the MSF super block, ",
156                pdbBlockOffset());
157   if (pdbBlockOffset() < endof(SuperBlock, MagicBytes))
158     P.printLine("which is part of the MSF file magic.");
159   else if (pdbBlockOffset() < endof(SuperBlock, BlockSize)) {
160     P.printLine("which contains the block size of the file.");
161     P.formatLine("The current value is {0}.",
162                  uint32_t(File.pdb().getMsfLayout().SB->BlockSize));
163   } else if (pdbBlockOffset() < endof(SuperBlock, FreeBlockMapBlock)) {
164     P.printLine("which contains the index of the FPM block (e.g. 1 or 2).");
165     P.formatLine("The current value is {0}.",
166                  uint32_t(File.pdb().getMsfLayout().SB->FreeBlockMapBlock));
167   } else if (pdbBlockOffset() < endof(SuperBlock, NumBlocks)) {
168     P.printLine("which contains the number of blocks in the file.");
169     P.formatLine("The current value is {0}.",
170                  uint32_t(File.pdb().getMsfLayout().SB->NumBlocks));
171   } else if (pdbBlockOffset() < endof(SuperBlock, NumDirectoryBytes)) {
172     P.printLine("which contains the number of bytes in the stream directory.");
173     P.formatLine("The current value is {0}.",
174                  uint32_t(File.pdb().getMsfLayout().SB->NumDirectoryBytes));
175   } else if (pdbBlockOffset() < endof(SuperBlock, Unknown1)) {
176     P.printLine("whose purpose is unknown.");
177     P.formatLine("The current value is {0}.",
178                  uint32_t(File.pdb().getMsfLayout().SB->Unknown1));
179   } else if (pdbBlockOffset() < endof(SuperBlock, BlockMapAddr)) {
180     P.printLine("which contains the file offset of the block map.");
181     P.formatLine("The current value is {0}.",
182                  uint32_t(File.pdb().getMsfLayout().SB->BlockMapAddr));
183   } else {
184     assert(pdbBlockOffset() > sizeof(SuperBlock));
185     P.printLine(
186         "which is outside the range of valid data for the super block.");
187   }
188 }
189 
190 static std::string toBinaryString(uint8_t Byte) {
191   char Result[9] = {0};
192   for (int I = 0; I < 8; ++I) {
193     char C = (Byte & 1) ? '1' : '0';
194     Result[I] = C;
195     Byte >>= 1;
196   }
197   return std::string(Result);
198 }
199 
200 void ExplainOutputStyle::explainPdbFpmBlockOffset() {
201   const MSFLayout &Layout = File.pdb().getMsfLayout();
202   uint32_t MainFpm = Layout.mainFpmBlock();
203   uint32_t AltFpm = Layout.alternateFpmBlock();
204 
205   assert(isPdbFpmBlock());
206   uint32_t Fpm = isPdbFpm1() ? 1 : 2;
207   uint32_t FpmChunk = pdbBlockIndex() / File.pdb().getBlockSize();
208   assert((Fpm == MainFpm) || (Fpm == AltFpm));
209   (void)AltFpm;
210   bool IsMain = (Fpm == MainFpm);
211   P.formatLine("Address is in FPM{0} ({1} FPM)", Fpm, IsMain ? "Main" : "Alt");
212   uint32_t DescribedBlockStart =
213       8 * (FpmChunk * File.pdb().getBlockSize() + pdbBlockOffset());
214   if (DescribedBlockStart > File.pdb().getBlockCount()) {
215     P.printLine("Address is in extraneous FPM space.");
216     return;
217   }
218 
219   P.formatLine("Address describes the allocation status of blocks [{0},{1})",
220                DescribedBlockStart, DescribedBlockStart + 8);
221   ArrayRef<uint8_t> Bytes;
222   cantFail(File.pdb().getMsfBuffer().readBytes(FileOffset, 1, Bytes));
223   P.formatLine("Status = {0} (Note: 0 = allocated, 1 = free)",
224                toBinaryString(Bytes[0]));
225 }
226 
227 void ExplainOutputStyle::explainPdbBlockMapOffset() {
228   uint64_t BlockMapOffset = File.pdb().getBlockMapOffset();
229   uint32_t OffsetInBlock = FileOffset - BlockMapOffset;
230   P.formatLine("Address is at offset {0} of the directory block list",
231                OffsetInBlock);
232 }
233 
234 static uint32_t getOffsetInStream(ArrayRef<support::ulittle32_t> StreamBlocks,
235                                   uint64_t FileOffset, uint32_t BlockSize) {
236   uint32_t BlockIndex = FileOffset / BlockSize;
237   uint32_t OffsetInBlock = FileOffset - BlockIndex * BlockSize;
238 
239   auto Iter = llvm::find(StreamBlocks, BlockIndex);
240   assert(Iter != StreamBlocks.end());
241   uint32_t StreamBlockIndex = std::distance(StreamBlocks.begin(), Iter);
242   return StreamBlockIndex * BlockSize + OffsetInBlock;
243 }
244 
245 void ExplainOutputStyle::explainPdbStreamOffset(uint32_t Stream) {
246   SmallVector<StreamInfo, 12> Streams;
247   discoverStreamPurposes(File.pdb(), Streams);
248 
249   assert(Stream <= Streams.size());
250   const StreamInfo &S = Streams[Stream];
251   const auto &Layout = File.pdb().getStreamLayout(Stream);
252   uint32_t StreamOff =
253       getOffsetInStream(Layout.Blocks, FileOffset, File.pdb().getBlockSize());
254   P.formatLine("Address is at offset {0}/{1} of Stream {2} ({3}){4}.",
255                StreamOff, Layout.Length, Stream, S.getLongName(),
256                (StreamOff > Layout.Length) ? " in unused space" : "");
257   switch (S.getPurpose()) {
258   case StreamPurpose::DBI: {
259     DbiStream &Dbi = cantFail(File.pdb().getPDBDbiStream());
260     explainStreamOffset(Dbi, StreamOff);
261     break;
262   }
263   case StreamPurpose::PDB: {
264     InfoStream &Info = cantFail(File.pdb().getPDBInfoStream());
265     explainStreamOffset(Info, StreamOff);
266     break;
267   }
268   case StreamPurpose::IPI:
269   case StreamPurpose::TPI:
270   case StreamPurpose::ModuleStream:
271   case StreamPurpose::NamedStream:
272   default:
273     break;
274   }
275 }
276 
277 void ExplainOutputStyle::explainPdbStreamDirectoryOffset() {
278   auto DirectoryBlocks = File.pdb().getDirectoryBlockArray();
279   const auto &Layout = File.pdb().getMsfLayout();
280   uint32_t StreamOff =
281       getOffsetInStream(DirectoryBlocks, FileOffset, File.pdb().getBlockSize());
282   P.formatLine("Address is at offset {0}/{1} of Stream Directory{2}.",
283                StreamOff, uint32_t(Layout.SB->NumDirectoryBytes),
284                uint32_t(StreamOff > Layout.SB->NumDirectoryBytes)
285                    ? " in unused space"
286                    : "");
287 }
288 
289 void ExplainOutputStyle::explainPdbUnknownBlock() {
290   P.formatLine("Address has unknown purpose.");
291 }
292 
293 template <typename T>
294 static void printStructField(LinePrinter &P, StringRef Label, T Value) {
295   P.formatLine("which contains {0}.", Label);
296   P.formatLine("The current value is {0}.", Value);
297 }
298 
299 static void explainDbiHeaderOffset(LinePrinter &P, DbiStream &Dbi,
300                                    uint32_t Offset) {
301   const DbiStreamHeader *Header = Dbi.getHeader();
302   assert(Header != nullptr);
303 
304   if (Offset < endof(DbiStreamHeader, VersionSignature))
305     printStructField(P, "the DBI Stream Version Signature",
306                      int32_t(Header->VersionSignature));
307   else if (Offset < endof(DbiStreamHeader, VersionHeader))
308     printStructField(P, "the DBI Stream Version Header",
309                      uint32_t(Header->VersionHeader));
310   else if (Offset < endof(DbiStreamHeader, Age))
311     printStructField(P, "the age of the DBI Stream", uint32_t(Header->Age));
312   else if (Offset < endof(DbiStreamHeader, GlobalSymbolStreamIndex))
313     printStructField(P, "the index of the Global Symbol Stream",
314                      uint16_t(Header->GlobalSymbolStreamIndex));
315   else if (Offset < endof(DbiStreamHeader, BuildNumber))
316     printStructField(P, "the build number", uint16_t(Header->BuildNumber));
317   else if (Offset < endof(DbiStreamHeader, PublicSymbolStreamIndex))
318     printStructField(P, "the index of the Public Symbol Stream",
319                      uint16_t(Header->PublicSymbolStreamIndex));
320   else if (Offset < endof(DbiStreamHeader, PdbDllVersion))
321     printStructField(P, "the version of mspdb.dll",
322                      uint16_t(Header->PdbDllVersion));
323   else if (Offset < endof(DbiStreamHeader, SymRecordStreamIndex))
324     printStructField(P, "the index of the Symbol Record Stream",
325                      uint16_t(Header->SymRecordStreamIndex));
326   else if (Offset < endof(DbiStreamHeader, PdbDllRbld))
327     printStructField(P, "the rbld of mspdb.dll", uint16_t(Header->PdbDllRbld));
328   else if (Offset < endof(DbiStreamHeader, ModiSubstreamSize))
329     printStructField(P, "the size of the Module Info Substream",
330                      int32_t(Header->ModiSubstreamSize));
331   else if (Offset < endof(DbiStreamHeader, SecContrSubstreamSize))
332     printStructField(P, "the size of the Section Contribution Substream",
333                      int32_t(Header->SecContrSubstreamSize));
334   else if (Offset < endof(DbiStreamHeader, SectionMapSize))
335     printStructField(P, "the size of the Section Map Substream",
336                      int32_t(Header->SectionMapSize));
337   else if (Offset < endof(DbiStreamHeader, FileInfoSize))
338     printStructField(P, "the size of the File Info Substream",
339                      int32_t(Header->FileInfoSize));
340   else if (Offset < endof(DbiStreamHeader, TypeServerSize))
341     printStructField(P, "the size of the Type Server Map",
342                      int32_t(Header->TypeServerSize));
343   else if (Offset < endof(DbiStreamHeader, MFCTypeServerIndex))
344     printStructField(P, "the index of the MFC Type Server stream",
345                      uint32_t(Header->MFCTypeServerIndex));
346   else if (Offset < endof(DbiStreamHeader, OptionalDbgHdrSize))
347     printStructField(P, "the size of the Optional Debug Stream array",
348                      int32_t(Header->OptionalDbgHdrSize));
349   else if (Offset < endof(DbiStreamHeader, ECSubstreamSize))
350     printStructField(P, "the size of the Edit & Continue Substream",
351                      int32_t(Header->ECSubstreamSize));
352   else if (Offset < endof(DbiStreamHeader, Flags))
353     printStructField(P, "the DBI Stream flags", uint16_t(Header->Flags));
354   else if (Offset < endof(DbiStreamHeader, MachineType))
355     printStructField(P, "the machine type", uint16_t(Header->MachineType));
356   else if (Offset < endof(DbiStreamHeader, Reserved))
357     printStructField(P, "reserved data", uint32_t(Header->Reserved));
358 }
359 
360 static void explainDbiModiSubstreamOffset(LinePrinter &P, DbiStream &Dbi,
361                                           uint32_t Offset) {
362   VarStreamArray<DbiModuleDescriptor> ModuleDescriptors;
363   BinaryStreamRef ModiSubstreamData = Dbi.getModiSubstreamData().StreamData;
364   BinaryStreamReader Reader(ModiSubstreamData);
365 
366   cantFail(Reader.readArray(ModuleDescriptors, ModiSubstreamData.getLength()));
367   auto Prev = ModuleDescriptors.begin();
368   assert(Prev.offset() == 0);
369   auto Current = Prev;
370   uint32_t Index = 0;
371   while (true) {
372     Prev = Current;
373     ++Current;
374     if (Current == ModuleDescriptors.end() || Offset < Current.offset())
375       break;
376     ++Index;
377   }
378 
379   const DbiModuleDescriptor &Descriptor = *Prev;
380   P.formatLine("which contains the descriptor for module {0} ({1}).", Index,
381                Descriptor.getModuleName());
382 }
383 
384 template <typename T>
385 static void dontExplain(LinePrinter &Printer, T &Stream, uint32_t Offset) {}
386 
387 template <typename T, typename SubstreamRangeT>
388 static void explainSubstreamOffset(LinePrinter &P, uint32_t OffsetInStream,
389                                    T &Stream,
390                                    const SubstreamRangeT &Substreams) {
391   uint32_t SubOffset = OffsetInStream;
392   for (const auto &Entry : Substreams) {
393     if (Entry.Size <= 0)
394       continue;
395     uint32_t S = static_cast<uint32_t>(Entry.Size);
396     if (SubOffset < S) {
397       P.formatLine("address is at offset {0}/{1} of the {2}.", SubOffset, S,
398                    Entry.Label);
399       Entry.Explain(P, Stream, SubOffset);
400       return;
401     }
402     SubOffset -= S;
403   }
404 }
405 
406 void ExplainOutputStyle::explainStreamOffset(DbiStream &Dbi,
407                                              uint32_t OffsetInStream) {
408   P.printLine("Within the DBI stream:");
409   AutoIndent Indent(P);
410   const DbiStreamHeader *Header = Dbi.getHeader();
411   assert(Header != nullptr);
412 
413   struct SubstreamInfo {
414     int32_t Size;
415     StringRef Label;
416     void (*Explain)(LinePrinter &, DbiStream &, uint32_t);
417   } Substreams[] = {
418       {sizeof(DbiStreamHeader), "DBI Stream Header", explainDbiHeaderOffset},
419       {int32_t(Header->ModiSubstreamSize), "Module Info Substream",
420        explainDbiModiSubstreamOffset},
421       {int32_t(Header->SecContrSubstreamSize), "Section Contribution Substream",
422        dontExplain<DbiStream>},
423       {int32_t(Header->SectionMapSize), "Section Map", dontExplain<DbiStream>},
424       {int32_t(Header->FileInfoSize), "File Info Substream",
425        dontExplain<DbiStream>},
426       {int32_t(Header->TypeServerSize), "Type Server Map Substream",
427        dontExplain<DbiStream>},
428       {int32_t(Header->ECSubstreamSize), "Edit & Continue Substream",
429        dontExplain<DbiStream>},
430       {int32_t(Header->OptionalDbgHdrSize), "Optional Debug Stream Array",
431        dontExplain<DbiStream>},
432   };
433 
434   explainSubstreamOffset(P, OffsetInStream, Dbi, Substreams);
435 }
436 
437 static void explainPdbStreamHeaderOffset(LinePrinter &P, InfoStream &Info,
438                                          uint32_t Offset) {
439   const InfoStreamHeader *Header = Info.getHeader();
440   assert(Header != nullptr);
441 
442   if (Offset < endof(InfoStreamHeader, Version))
443     printStructField(P, "the PDB Stream Version Signature",
444                      uint32_t(Header->Version));
445   else if (Offset < endof(InfoStreamHeader, Signature))
446     printStructField(P, "the signature of the PDB Stream",
447                      uint32_t(Header->Signature));
448   else if (Offset < endof(InfoStreamHeader, Age))
449     printStructField(P, "the age of the PDB", uint32_t(Header->Age));
450   else if (Offset < endof(InfoStreamHeader, Guid))
451     printStructField(P, "the guid of the PDB", fmt_guid(Header->Guid.Guid));
452 }
453 
454 void ExplainOutputStyle::explainStreamOffset(InfoStream &Info,
455                                              uint32_t OffsetInStream) {
456   P.printLine("Within the PDB stream:");
457   AutoIndent Indent(P);
458 
459   struct SubstreamInfo {
460     uint32_t Size;
461     StringRef Label;
462     void (*Explain)(LinePrinter &, InfoStream &, uint32_t);
463   } Substreams[] = {{sizeof(InfoStreamHeader), "PDB Stream Header",
464                      explainPdbStreamHeaderOffset},
465                     {Info.getNamedStreamMapByteSize(), "Named Stream Map",
466                      dontExplain<InfoStream>},
467                     {Info.getStreamSize(), "PDB Feature Signatures",
468                      dontExplain<InfoStream>}};
469 
470   explainSubstreamOffset(P, OffsetInStream, Info, Substreams);
471 }
472