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