[llvm-pdbutil] Add options to only dump symbol record at specified offset and its parents or children with spcified depth.

[zequanwu]

Summary

Right now, if we want to dump symbol at specified offset, we need to use grep.
And it can only show surrounding symbols in layout (not in lexical scope sense).

This adds similar options to dump command as llvm-dwarfdump to allow users
to dump symbol record at specified offset and its parents or children with
spcified depth.

--symbol-offset= must be used with --modi to dump only one symbol at given
offset.

--show-parents/--show-children must be used with --symbol-offset to
dump all symbols that are parents/children of the symbol at given offset.

--parent-recurse-depth/--children-recurse-depth must be used with
--show-parents/--show-children to specify the max up/down depth.

[rnk]

llvm/include/llvm/DebugInfo/CodeView/CVSymbolVisitor.h

33

Rather than having these fields, I think it might make more sense to have a new method, visitSymbolStreamFiltered(Syms, FilterOptions), which implements this new behavior. It would be slightly more functional and less stateful. WDYT?

I'm imagining a simple struct combining all the options, in case we want to add more later:

struct FilterOptions {
  Optional<uint32_t> SymbolOffset;
  Optional<uint32_t> ParentRecursiveDepth;
  Optional<uint32_t> ChildRecursiveDepth;
};

llvm/lib/DebugInfo/CodeView/CVSymbolVisitor.cpp

104

I think you need to "pop off" a parent record every time you see a closing scope. Consider this sequence of records, where ( is open, ) is close, * is the desired record: (()(*))

In your existing test case, this would correspond with the output of a second inline call site that isn't part of the first.

145

I don't think these scope end offsets are available in the typical object file. Try running llvm-pdbutil dump with these filtration options on a single object file instead of a PDB, I think you'll find that the end offset is zero.

146

This would crash if the PDB file is corrupt, please make it handle this case gracefully. I think in dumping code, we should be as defensive as possible because dumpers are often used on new or non-conforming inputs that trigger linker bugs.

152

To try to simplify things and avoid OOB error checking, I would try to restructure this into a single loop. Always maintain a stack of open parent record offsets. Pop them off when you reach closing scopes. When you reach the record you are looking for, print the open scopes.

llvm/test/tools/llvm-pdbutil/symbol-offset.test

37

Please include the C++ source used to produce the input YAML file to help illustrate the expected structure.

[zequanwu]

Address comments.

[zequanwu]

llvm/lib/DebugInfo/CodeView/CVSymbolVisitor.cpp

104

An opening scope is only added in to ParentSymbols when the scope range [begin, end] encompass the desired offset.
In the case of (()(*)), the first inner scope`() will not be added into ParentSymbols`.

Added a test case for (()(*)).

145

Yes, all offsets and parent/end are 0. So, the filter options are only used in DumpOutputStyle::dumpModuleSymsForPdb, and silently ignored when dumping obj file.

146

Add VarStreamArray::isOffsetValid to check if an offset is valid, and use it to check offset before dereference.

llvm/test/tools/llvm-pdbutil/symbol-offset.test

37

I deleted the cpp file, so I rewrote new one.

[rnk]

Looks good to me, just one style comment.

llvm/lib/DebugInfo/CodeView/CVSymbolVisitor.cpp

117

Can you reorder the else if with the folllowing else, so that the conditions appear in the same order that they are executed? Something like:

if (BeginOffset < SymbolOffset) {
  ... // accumulate parent offsets
} else if (BeginOffset == SymbolOffset) {
  ... // print all parent and desired records
} else if (BeginOffset <= SymEndOffset) {
  ... // handle child recs
} else {
  ... // Handle parents' ends.
}

[MForster]

I've reverted this because symbol-offset.test fails under MSAN:

[ 1] ; RUN: llvm-pdbutil yaml2pdb %p/Inputs/symbol-offset.yaml --pdb=%t.pdb [FAIL]
llvm-pdbutil yaml2pdb <REDACTED>/llvm/test/tools/llvm-pdbutil/Inputs/symbol-offset.yaml --pdb=<REDACTED>/tmp/symbol-offset.test/symbol-offset.test.tmp.pdb
==9283==WARNING: MemorySanitizer: use-of-uninitialized-value
    #0 0x55f975e5eb91 in __libcpp_tls_set <REDACTED>/include/c++/v1/__threading_support:428:12
    #1 0x55f975e5eb91 in set_pointer <REDACTED>/include/c++/v1/thread:196:5
    #2 0x55f975e5eb91 in void* std::__msan::__thread_proxy<std::__msan::tuple<std::__msan::unique_ptr<std::__msan::__thread_struct, std::__msan::default_delete<std::__msan::__thread_struct> >, llvm::parallel::detail::(anonymous namespace)::ThreadPoolExecutor::ThreadPoolExecutor(llvm::ThreadPoolStrategy)::'lambda'()::operator()() const::'lambda'()> >(void*) <REDACTED>/include/c++/v1/thread:285:27
    #3 0x7f74a1e55b54 in start_thread (<REDACTED>/libpthread.so.0+0xbb54) (BuildId: 64752de50ebd1a108f4b3f8d0d7e1a13)
    #4 0x7f74a1dc9f7e in clone (<REDACTED>/libc.so.6+0x13cf7e) (BuildId: 7cfed7708e5ab7fcb286b373de21ee76)

[zequanwu]

In D124317#3479671, @MForster wrote:

I've reverted this because symbol-offset.test fails under MSAN:

[ 1] ; RUN: llvm-pdbutil yaml2pdb %p/Inputs/symbol-offset.yaml --pdb=%t.pdb [FAIL]
llvm-pdbutil yaml2pdb <REDACTED>/llvm/test/tools/llvm-pdbutil/Inputs/symbol-offset.yaml --pdb=<REDACTED>/tmp/symbol-offset.test/symbol-offset.test.tmp.pdb
==9283==WARNING: MemorySanitizer: use-of-uninitialized-value
    #0 0x55f975e5eb91 in __libcpp_tls_set <REDACTED>/include/c++/v1/__threading_support:428:12
    #1 0x55f975e5eb91 in set_pointer <REDACTED>/include/c++/v1/thread:196:5
    #2 0x55f975e5eb91 in void* std::__msan::__thread_proxy<std::__msan::tuple<std::__msan::unique_ptr<std::__msan::__thread_struct, std::__msan::default_delete<std::__msan::__thread_struct> >, llvm::parallel::detail::(anonymous namespace)::ThreadPoolExecutor::ThreadPoolExecutor(llvm::ThreadPoolStrategy)::'lambda'()::operator()() const::'lambda'()> >(void*) <REDACTED>/include/c++/v1/thread:285:27
    #3 0x7f74a1e55b54 in start_thread (<REDACTED>/libpthread.so.0+0xbb54) (BuildId: 64752de50ebd1a108f4b3f8d0d7e1a13)
    #4 0x7f74a1dc9f7e in clone (<REDACTED>/libc.so.6+0x13cf7e) (BuildId: 7cfed7708e5ab7fcb286b373de21ee76)

This stack doesn't show files changed in this patch. How do I interpret it?

[MForster]

Sorry, I haven't investigated.

llvm/include/llvm/DebugInfo/CodeView/CVSymbolVisitor.h

 #include "llvm/Support/Error.h"
 
 namespace llvm {
 namespace codeview {
 class SymbolVisitorCallbacks;
 
 class CVSymbolVisitor {
 public:
+  struct FilterOptions {
+    llvm::Optional<uint32_t> SymbolOffset;
+    llvm::Optional<uint32_t> ParentRecursiveDepth;
+    llvm::Optional<uint32_t> ChildRecursiveDepth;
+  };
+
   CVSymbolVisitor(SymbolVisitorCallbacks &Callbacks);
 
   Error visitSymbolRecord(CVSymbol &Record);
   Error visitSymbolRecord(CVSymbol &Record, uint32_t Offset);
   Error visitSymbolStream(const CVSymbolArray &Symbols);
   Error visitSymbolStream(const CVSymbolArray &Symbols, uint32_t InitialOffset);
+  Error visitSymbolStreamFiltered(const CVSymbolArray &Symbols,
+                                  const FilterOptions &Filter);
 
 private:
   SymbolVisitorCallbacks &Callbacks;
 };
 
 } // end namespace codeview
 } // end namespace llvm
 
 #endif // LLVM_DEBUGINFO_CODEVIEW_CVSYMBOLVISITOR_H

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

 }
 
 template <typename CallbackT>
 Error iterateSymbolGroups(InputFile &Input, const PrintScope &HeaderScope,
                           CallbackT Callback) {
   AutoIndent Indent(HeaderScope);
 
   FilterOptions Filters = HeaderScope.P.getFilters();
-  if (Filters.NumOccurrences) {
-    uint32_t Modi = Filters.DumpModi;
+  if (Filters.DumpModi) {
+    uint32_t Modi = Filters.DumpModi.getValue();
     SymbolGroup SG(&Input, Modi);
     return iterateOneModule(Input, withLabelWidth(HeaderScope, NumDigits(Modi)),
                             SG, Modi, Callback);
   }
 
   uint32_t I = 0;
 
   for (const auto &SG : Input.symbol_groups()) {

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

struct FilterOptions {
   std::list<std::string> ExcludeTypes;
   std::list<std::string> ExcludeSymbols;
   std::list<std::string> ExcludeCompilands;
   std::list<std::string> IncludeTypes;
   std::list<std::string> IncludeSymbols;
   std::list<std::string> IncludeCompilands;
   uint32_t PaddingThreshold;
   uint32_t SizeThreshold;
-  uint32_t DumpModi;
-  uint32_t NumOccurrences;
+  llvm::Optional<uint32_t> DumpModi;
+  llvm::Optional<uint32_t> ParentRecurseDepth;
+  llvm::Optional<uint32_t> ChildrenRecurseDepth;
+  llvm::Optional<uint32_t> SymbolOffset;
   bool JustMyCode;
 };
 
 namespace llvm {
 namespace msf {
 class MSFStreamLayout;
 } // namespace msf
 namespace pdb {

llvm/include/llvm/Support/BinaryStreamArray.h

VarStreamArray(BinaryStreamRef Stream, const Extractor &E, uint32_t Skew = 0)
       : Stream(Stream), E(E), Skew(Skew) {}
 
   Iterator begin(bool *HadError = nullptr) const {
     return Iterator(*this, E, Skew, nullptr);
   }
 
   bool valid() const { return Stream.valid(); }
 
+  bool isOffsetValid(uint32_t Offset) const { return at(Offset) != end(); }
+
   uint32_t skew() const { return Skew; }
   Iterator end() const { return Iterator(E); }
 
   bool empty() const { return Stream.getLength() == 0; }
 
   VarStreamArray<ValueType, Extractor> substream(uint32_t Begin,
                                                  uint32_t End) const {
     assert(Begin >= Skew);

llvm/lib/DebugInfo/CodeView/CVSymbolVisitor.cpp

 //===- CVSymbolVisitor.cpp --------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "llvm/DebugInfo/CodeView/CVSymbolVisitor.h"
 
 #include "llvm/DebugInfo/CodeView/CodeView.h"
 #include "llvm/DebugInfo/CodeView/SymbolRecord.h"
+#include "llvm/DebugInfo/CodeView/SymbolRecordHelpers.h"
 #include "llvm/DebugInfo/CodeView/SymbolVisitorCallbacks.h"
 #include "llvm/Support/BinaryStreamArray.h"
 #include "llvm/Support/ErrorHandling.h"
 
 using namespace llvm;
 using namespace llvm::codeview;
 
 CVSymbolVisitor::CVSymbolVisitor(SymbolVisitorCallbacks &Callbacks)
Error CVSymbolVisitor::visitSymbolStream(const CVSymbolArray &Symbols,
                                          uint32_t InitialOffset) {
   for (auto I : Symbols) {
     if (auto EC = visitSymbolRecord(I, InitialOffset + Symbols.skew()))
       return EC;
     InitialOffset += I.length();
   }
   return Error::success();
 }
+
+Error CVSymbolVisitor::visitSymbolStreamFiltered(const CVSymbolArray &Symbols,
+                                                 const FilterOptions &Filter) {
+  if (!Filter.SymbolOffset)
+    return visitSymbolStream(Symbols);
+  uint32_t SymbolOffset = *Filter.SymbolOffset;
+  uint32_t ParentRecurseDepth =
+      Filter.ParentRecursiveDepth ? *Filter.ParentRecursiveDepth : 0;
+  uint32_t ChildrenRecurseDepth =
+      Filter.ChildRecursiveDepth ? *Filter.ChildRecursiveDepth : 0;
+  if (!Symbols.isOffsetValid(SymbolOffset))
+    return createStringError(inconvertibleErrorCode(), "Invalid symbol offset");
+  CVSymbol Sym = *Symbols.at(SymbolOffset);
+  uint32_t SymEndOffset =
+      symbolOpensScope(Sym.kind()) ? getScopeEndOffset(Sym) : 0;
+
+  std::vector<uint32_t> ParentOffsets;
+  std::vector<uint32_t> ParentEndOffsets;
+  uint32_t ChildrenDepth = 0;
+  for (auto Begin = Symbols.begin(), End = Symbols.end(); Begin != End;
+       ++Begin) {
+    uint32_t BeginOffset = Begin.offset();
+    CVSymbol BeginSym = *Begin;
+    if (BeginOffset < SymbolOffset) {
+      if (symbolOpensScope(Begin->kind())) {
+        uint32_t EndOffset = getScopeEndOffset(BeginSym);
+        if (SymbolOffset < EndOffset) {
+          ParentOffsets.push_back(BeginOffset);
+          ParentEndOffsets.push_back(EndOffset);
+        }
+      }
+    } else if (BeginOffset == SymbolOffset) {
+      // Found symbol at offset. Visit its parent up to ParentRecurseDepth.
+      if (ParentRecurseDepth >= ParentOffsets.size())
+        ParentRecurseDepth = ParentOffsets.size();
+      uint32_t StartIndex = ParentOffsets.size() - ParentRecurseDepth;
+      while (StartIndex < ParentOffsets.size()) {
+        if (!Symbols.isOffsetValid(ParentOffsets[StartIndex]))
+          break;
+        CVSymbol Parent = *Symbols.at(ParentOffsets[StartIndex]);
+        if (auto EC = visitSymbolRecord(Parent, ParentOffsets[StartIndex]))
+          return EC;
+        ++StartIndex;
+      }
+      if (auto EC = visitSymbolRecord(Sym, SymbolOffset))
+        return EC;
+    } else if (BeginOffset <= SymEndOffset) {
+      if (ChildrenRecurseDepth) {
+        // Visit children.
+        if (symbolEndsScope(Begin->kind()))
+          --ChildrenDepth;
+        if (ChildrenDepth < ChildrenRecurseDepth ||
+            BeginOffset == SymEndOffset) {
+          if (auto EC = visitSymbolRecord(BeginSym, BeginOffset))
+            return EC;
+        }
+        if (symbolOpensScope(Begin->kind()))
+          ++ChildrenDepth;
+      }
+    } else {
+      // Visit parents' ends.
+      if (ParentRecurseDepth && BeginOffset == ParentEndOffsets.back()) {
+        if (auto EC = visitSymbolRecord(BeginSym, BeginOffset))
+          return EC;
+        ParentEndOffsets.pop_back();
+        --ParentRecurseDepth;
+      }
+    }
+  }
+  return Error::success();
+}

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

 }
 
 bool llvm::pdb::shouldDumpSymbolGroup(uint32_t Idx, const SymbolGroup &Group,
                                       const FilterOptions &Filters) {
   if (Filters.JustMyCode && !isMyCode(Group))
     return false;
 
   // If the arg was not specified on the command line, always dump all modules.
-  if (Filters.NumOccurrences == 0)
+  if (!Filters.DumpModi)
     return true;
 
   // Otherwise, only dump if this is the same module specified.
   return (Filters.DumpModi == Idx);
 }

llvm/test/tools/llvm-pdbutil/Inputs/symbol-offset.yaml

+---
+DbiStream:
+  VerHeader:       V70
+  Age:             1
+  BuildNumber:     36363
+  PdbDllVersion:   0
+  PdbDllRbld:      0
+  Flags:           0
+  MachineType:     Amd64
+  Modules:
+    - Module:          '/tmp/test.obj'
+      Modi:
+        Signature:       4
+        Records:
+          - Kind:            S_GPROC32
+            ProcSym:
+              PtrParent:       0
+              PtrEnd:          468
+              PtrNext:         0
+              CodeSize:        137
+              DbgStart:        0
+              DbgEnd:          0
+              FunctionType:    4104
+              Offset:          176
+              Segment:         1
+              Flags:           [  ]
+              DisplayName:     main
+          - Kind:            S_FRAMEPROC
+            FrameProcSym:
+              TotalFrameBytes: 56
+              PaddingFrameBytes: 0
+              OffsetToPadding: 0
+              BytesOfCalleeSavedRegisters: 0
+              OffsetOfExceptionHandler: 0
+              SectionIdOfExceptionHandler: 0
+              Flags:           [  ]
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            116
+              Flags:           [ IsParameter ]
+              VarName:         argc
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          4
+              Range:
+                OffsetStart:     197
+                ISectStart:      1
+                Range:           116
+              Gaps:            []
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            4102
+              Flags:           [ IsParameter ]
+              VarName:         argv
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          8
+              Range:
+                OffsetStart:     197
+                ISectStart:      1
+                Range:           116
+              Gaps:            []
+          - Kind:            S_INLINESITE
+            InlineSiteSym:
+              PtrParent:       4
+              PtrEnd:          464
+              Inlinee:         4098
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            116
+              Flags:           [ IsParameter ]
+              VarName:         x
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          24
+              Range:
+                OffsetStart:     221
+                ISectStart:      1
+                Range:           87
+              Gaps:            []
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            116
+              Flags:           [ IsParameter ]
+              VarName:         y
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          28
+              Range:
+                OffsetStart:     221
+                ISectStart:      1
+                Range:           87
+              Gaps:            []
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            116
+              Flags:           [ IsParameter ]
+              VarName:         z
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          32
+              Range:
+                OffsetStart:     221
+                ISectStart:      1
+                Range:           87
+              Gaps:            []
+          - Kind:            S_INLINESITE
+            InlineSiteSym:
+              PtrParent:       144
+              PtrEnd:          288
+              Inlinee:         4096
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            116
+              Flags:           [ IsParameter ]
+              VarName:         x
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          40
+              Range:
+                OffsetStart:     229
+                ISectStart:      1
+                Range:           7
+              Gaps:            []
+          - Kind:            S_INLINESITE_END
+            ScopeEndSym:     {}
+          - Kind:            S_INLINESITE
+            InlineSiteSym:
+              PtrParent:       144
+              PtrEnd:          412
+              Inlinee:         4097
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            116
+              Flags:           [ IsParameter ]
+              VarName:         x
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          44
+              Range:
+                OffsetStart:     260
+                ISectStart:      1
+                Range:           19
+              Gaps:            []
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            116
+              Flags:           [ IsParameter ]
+              VarName:         y
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          48
+              Range:
+                OffsetStart:     260
+                ISectStart:      1
+                Range:           19
+              Gaps:            []
+          - Kind:            S_INLINESITE
+            InlineSiteSym:
+              PtrParent:       292
+              PtrEnd:          408
+              Inlinee:         4096
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            116
+              Flags:           [ IsParameter ]
+              VarName:         x
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          52
+              Range:
+                OffsetStart:     272
+                ISectStart:      1
+                Range:           7
+              Gaps:            []
+          - Kind:            S_INLINESITE_END
+            ScopeEndSym:     {}
+          - Kind:            S_INLINESITE_END
+            ScopeEndSym:     {}
+          - Kind:            S_INLINESITE
+            InlineSiteSym:
+              PtrParent:       144
+              PtrEnd:          460
+              Inlinee:         4096
+          - Kind:            S_LOCAL
+            LocalSym:
+              Type:            116
+              Flags:           [ IsParameter ]
+              VarName:         x
+          - Kind:            S_DEFRANGE_FRAMEPOINTER_REL
+            DefRangeFramePointerRelSym:
+              Offset:          36
+              Range:
+                OffsetStart:     299
+                ISectStart:      1
+                Range:           7
+              Gaps:            []
+          - Kind:            S_INLINESITE_END
+            ScopeEndSym:     {}
+          - Kind:            S_INLINESITE_END
+            ScopeEndSym:     {}
+          - Kind:            S_END
+            ScopeEndSym:     {}
+...

llvm/test/tools/llvm-pdbutil/symbol-offset.test

+; RUN: llvm-pdbutil yaml2pdb %p/Inputs/symbol-offset.yaml --pdb=%t.pdb
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=80 %t.pdb \
+; RUN:    | FileCheck --check-prefix=OFFSET %s
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=4 --show-parents \
+; RUN: %t.pdb  | FileCheck --check-prefix=SHOW-PARENT1 %s
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=80 --show-parents \
+; RUN: %t.pdb  | FileCheck --check-prefix=SHOW-PARENT2 %s
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=308 --show-parents \
+; RUN: %t.pdb  | FileCheck --check-prefix=SHOW-PARENT3 %s
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=260 --show-parents \
+; RUN: --parent-recurse-depth=1 %t.pdb \
+; RUN: | FileCheck --check-prefix=SHOW-PARENT-DEPTH1 %s
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=260 --show-parents \
+; RUN: --parent-recurse-depth=2 %t.pdb \
+; RUN: | FileCheck --check-prefix=SHOW-PARENT-DEPTH2 %s
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=416 --show-children\
+; RUN: %t.pdb  | FileCheck --check-prefix=SHOW-CHILDREN1 %s
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=292 --show-children\
+; RUN: %t.pdb  | FileCheck --check-prefix=SHOW-CHILDREN2 %s
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=4 --show-children \
+; RUN: --children-recurse-depth=1 %t.pdb \
+; RUN: | FileCheck --check-prefix=SHOW-CHILDREN-DEPTH1 %s
+
+; RUN: llvm-pdbutil dump --symbols --modi=0 --symbol-offset=292 --show-children\
+; RUN: --children-recurse-depth=2 %t.pdb \
+; RUN: | FileCheck --check-prefix=SHOW-CHILDREN-DEPTH2 %s
+
+The pdb file is generate from following cpp file and use llvm-pdbutil's pdb2yaml
+functionality to convert pdb to yaml. Unrelated information was removed from the
+yaml test file.
+; [[clang::always_inline]] int func1(int x) {
+;     return x * 2;
+; }
+;
+; [[clang::always_inline]] int func2(int x, int y) {
+;     return func1(x + y);
+; }
+;
+; [[clang::always_inline]] int func3(int x, int y, int z) {
+;     y += func1(x);
+;     x += func2(y, z);
+;     return x + func1(x);
+; }
+;
+; int main(int argc, char** argv) {
+;     return func3(argc, 1, 2);
+; }
+
+
+OFFSET:      80 | S_LOCAL [size = 16] `argc`
+OFFSET-NEXT:      type=0x0074 (int), flags = param
+
+SHOW-PARENT1:      4 | S_GPROC32 [size = 44] `main`
+SHOW-PARENT1-NEXT:     parent = 0, end = 468, addr = 0001:0176, code size = 137
+SHOW-PARENT1-NEXT:     type = `0x1008 (<unknown UDT>)`, debug start = 0, debug end = 0, flags = none
+
+SHOW-PARENT2:        4 | S_GPROC32 [size = 44] `main`
+SHOW-PARENT2-NEXT:       parent = 0, end = 468, addr = 0001:0176, code size = 137
+SHOW-PARENT2-NEXT:       type = `0x1008 (<unknown UDT>)`, debug start = 0, debug end = 0, flags = none
+SHOW-PARENT2-NEXT:  80 | S_LOCAL [size = 16] `argc`
+SHOW-PARENT2-NEXT:       type=0x0074 (int), flags = param
+SHOW-PARENT2-NEXT: 468 | S_END [size = 4]
+
+SHOW-PARENT3:        4 | S_GPROC32 [size = 44] `main`
+SHOW-PARENT3-NEXT:       parent = 0, end = 468, addr = 0001:0176, code size = 137
+SHOW-PARENT3-NEXT:       type = `0x1008 (<unknown UDT>)`, debug start = 0, debug end = 0, flags = none
+SHOW-PARENT3-NEXT: 144 | S_INLINESITE [size = 16]
+SHOW-PARENT3-NEXT:       inlinee = 0x1002 (<unknown UDT>), parent = 4, end = 464
+SHOW-PARENT3-NEXT: 292 | S_INLINESITE [size = 16]
+SHOW-PARENT3-NEXT:       inlinee = 0x1001 (<unknown UDT>), parent = 144, end = 412
+SHOW-PARENT3-NEXT: 308 | S_LOCAL [size = 12] `x`
+SHOW-PARENT3-NEXT:       type=0x0074 (int), flags = param
+SHOW-PARENT3-NEXT: 412 | S_INLINESITE_END [size = 4]
+SHOW-PARENT3-NEXT: 464 | S_INLINESITE_END [size = 4]
+SHOW-PARENT3-NEXT: 468 | S_END [size = 4]
+
+
+SHOW-PARENT-DEPTH1:      244 | S_INLINESITE [size = 16]
+SHOW-PARENT-DEPTH1-NEXT:       inlinee = 0x1000 (<unknown UDT>), parent = 144, end = 288
+SHOW-PARENT-DEPTH1-NEXT: 260 | S_LOCAL [size = 12] `x`
+SHOW-PARENT-DEPTH1-NEXT:       type=0x0074 (int), flags = param
+SHOW-PARENT-DEPTH1-NEXT: 288 | S_INLINESITE_END [size = 4]
+
+SHOW-PARENT-DEPTH2:      144 | S_INLINESITE [size = 16]
+SHOW-PARENT-DEPTH2-NEXT:       inlinee = 0x1002 (<unknown UDT>), parent = 4, end = 464
+SHOW-PARENT-DEPTH2-NEXT: 244 | S_INLINESITE [size = 16]
+SHOW-PARENT-DEPTH2-NEXT:       inlinee = 0x1000 (<unknown UDT>), parent = 144, end = 288
+SHOW-PARENT-DEPTH2-NEXT: 260 | S_LOCAL [size = 12] `x`
+SHOW-PARENT-DEPTH2-NEXT:       type=0x0074 (int), flags = param
+SHOW-PARENT-DEPTH2-NEXT: 288 | S_INLINESITE_END [size = 4]
+SHOW-PARENT-DEPTH2-NEXT: 464 | S_INLINESITE_END [size = 4]
+
+SHOW-CHILDREN1:      416 | S_INLINESITE [size = 16]
+SHOW-CHILDREN1-NEXT:       inlinee = 0x1000 (<unknown UDT>), parent = 144, end = 460
+SHOW-CHILDREN1-NEXT: 432 | S_LOCAL [size = 12] `x`
+SHOW-CHILDREN1-NEXT:       type=0x0074 (int), flags = param
+SHOW-CHILDREN1-NEXT: 444 | S_DEFRANGE_FRAMEPOINTER_REL [size = 16]
+SHOW-CHILDREN1-NEXT:       offset = 36, range = [0001:0299,+7)
+SHOW-CHILDREN1-NEXT:       gaps = []
+SHOW-CHILDREN1-NEXT: 460 | S_INLINESITE_END [size = 4]
+
+SHOW-CHILDREN2:      292 | S_INLINESITE [size = 16]
+SHOW-CHILDREN2-NEXT:       inlinee = 0x1001 (<unknown UDT>), parent = 144, end = 412
+SHOW-CHILDREN2-NEXT: 308 | S_LOCAL [size = 12] `x`
+SHOW-CHILDREN2-NEXT:       type=0x0074 (int), flags = param
+SHOW-CHILDREN2-NEXT: 320 | S_DEFRANGE_FRAMEPOINTER_REL [size = 16]
+SHOW-CHILDREN2-NEXT:       offset = 44, range = [0001:0260,+19)
+SHOW-CHILDREN2-NEXT:       gaps = []
+SHOW-CHILDREN2-NEXT: 336 | S_LOCAL [size = 12] `y`
+SHOW-CHILDREN2-NEXT:       type=0x0074 (int), flags = param
+SHOW-CHILDREN2-NEXT: 348 | S_DEFRANGE_FRAMEPOINTER_REL [size = 16]
+SHOW-CHILDREN2-NEXT:       offset = 48, range = [0001:0260,+19)
+SHOW-CHILDREN2-NEXT:       gaps = []
+SHOW-CHILDREN2-NEXT: 364 | S_INLINESITE [size = 16]
+SHOW-CHILDREN2-NEXT:       inlinee = 0x1000 (<unknown UDT>), parent = 292, end = 408
+SHOW-CHILDREN2-NEXT: 380 | S_LOCAL [size = 12] `x`
+SHOW-CHILDREN2-NEXT:       type=0x0074 (int), flags = param
+SHOW-CHILDREN2-NEXT: 392 | S_DEFRANGE_FRAMEPOINTER_REL [size = 16]
+SHOW-CHILDREN2-NEXT:       offset = 52, range = [0001:0272,+7)
+SHOW-CHILDREN2-NEXT:       gaps = []
+SHOW-CHILDREN2-NEXT: 408 | S_INLINESITE_END [size = 4]
+SHOW-CHILDREN2-NEXT: 412 | S_INLINESITE_END [size = 4]
+
+SHOW-CHILDREN-DEPTH1:        4 | S_GPROC32 [size = 44] `main`
+SHOW-CHILDREN-DEPTH1-NEXT:       parent = 0, end = 468, addr = 0001:0176, code size = 137
+SHOW-CHILDREN-DEPTH1-NEXT:       type = `0x1008 (<unknown UDT>)`, debug start = 0, debug end = 0, flags = none
+SHOW-CHILDREN-DEPTH1-NEXT:  48 | S_FRAMEPROC [size = 32]
+SHOW-CHILDREN-DEPTH1-NEXT:       size = 56, padding size = 0, offset to padding = 0
+SHOW-CHILDREN-DEPTH1-NEXT:       bytes of callee saved registers = 0, exception handler addr = 0000:0000
+SHOW-CHILDREN-DEPTH1-NEXT:       local fp reg = NONE, param fp reg = NONE
+SHOW-CHILDREN-DEPTH1-NEXT:       flags = none
+SHOW-CHILDREN-DEPTH1-NEXT:  80 | S_LOCAL [size = 16] `argc`
+SHOW-CHILDREN-DEPTH1-NEXT:       type=0x0074 (int), flags = param
+SHOW-CHILDREN-DEPTH1-NEXT:  96 | S_DEFRANGE_FRAMEPOINTER_REL [size = 16]
+SHOW-CHILDREN-DEPTH1-NEXT:       offset = 4, range = [0001:0197,+116)
+SHOW-CHILDREN-DEPTH1-NEXT:       gaps = []
+SHOW-CHILDREN-DEPTH1-NEXT: 112 | S_LOCAL [size = 16] `argv`
+SHOW-CHILDREN-DEPTH1-NEXT:       type=0x1006 (<unknown UDT>), flags = param
+SHOW-CHILDREN-DEPTH1-NEXT: 128 | S_DEFRANGE_FRAMEPOINTER_REL [size = 16]
+SHOW-CHILDREN-DEPTH1-NEXT:       offset = 8, range = [0001:0197,+116)
+SHOW-CHILDREN-DEPTH1-NEXT:       gaps = []
+SHOW-CHILDREN-DEPTH1-NEXT: 144 | S_INLINESITE [size = 16]
+SHOW-CHILDREN-DEPTH1-NEXT:       inlinee = 0x1002 (<unknown UDT>), parent = 4, end = 464
+SHOW-CHILDREN-DEPTH1-NEXT: 464 | S_INLINESITE_END [size = 4]
+SHOW-CHILDREN-DEPTH1-NEXT: 468 | S_END [size = 4]
+
+SHOW-CHILDREN-DEPTH2:      292 | S_INLINESITE [size = 16]
+SHOW-CHILDREN-DEPTH2-NEXT:       inlinee = 0x1001 (<unknown UDT>), parent = 144, end = 412
+SHOW-CHILDREN-DEPTH2-NEXT: 308 | S_LOCAL [size = 12] `x`
+SHOW-CHILDREN-DEPTH2-NEXT:       type=0x0074 (int), flags = param
+SHOW-CHILDREN-DEPTH2-NEXT: 320 | S_DEFRANGE_FRAMEPOINTER_REL [size = 16]
+SHOW-CHILDREN-DEPTH2-NEXT:       offset = 44, range = [0001:0260,+19)
+SHOW-CHILDREN-DEPTH2-NEXT:       gaps = []
+SHOW-CHILDREN-DEPTH2-NEXT: 336 | S_LOCAL [size = 12] `y`
+SHOW-CHILDREN-DEPTH2-NEXT:       type=0x0074 (int), flags = param
+SHOW-CHILDREN-DEPTH2-NEXT: 348 | S_DEFRANGE_FRAMEPOINTER_REL [size = 16]
+SHOW-CHILDREN-DEPTH2-NEXT:       offset = 48, range = [0001:0260,+19)
+SHOW-CHILDREN-DEPTH2-NEXT:       gaps = []
+SHOW-CHILDREN-DEPTH2-NEXT: 364 | S_INLINESITE [size = 16]
+SHOW-CHILDREN-DEPTH2-NEXT:       inlinee = 0x1000 (<unknown UDT>), parent = 292, end = 408
+SHOW-CHILDREN-DEPTH2-NEXT: 380 | S_LOCAL [size = 12] `x`
+SHOW-CHILDREN-DEPTH2-NEXT:       type=0x0074 (int), flags = param
+SHOW-CHILDREN-DEPTH2-NEXT: 392 | S_DEFRANGE_FRAMEPOINTER_REL [size = 16]
+SHOW-CHILDREN-DEPTH2-NEXT:       offset = 52, range = [0001:0272,+7)
+SHOW-CHILDREN-DEPTH2-NEXT:       gaps = []
+SHOW-CHILDREN-DEPTH2-NEXT: 408 | S_INLINESITE_END [size = 4]
+SHOW-CHILDREN-DEPTH2-NEXT: 412 | S_INLINESITE_END [size = 4]
 No newline at end of file

llvm/tools/llvm-pdbutil/DumpOutputStyle.cpp

return iterateSymbolGroups(
         SymbolDeserializer Deserializer(nullptr, CodeViewContainer::Pdb);
         MinimalSymbolDumper Dumper(P, opts::dump::DumpSymRecordBytes, Strings,
                                    Ids, Types);
 
         Pipeline.addCallbackToPipeline(Deserializer);
         Pipeline.addCallbackToPipeline(Dumper);
         CVSymbolVisitor Visitor(Pipeline);
         auto SS = ModS.getSymbolsSubstream();
-        if (auto EC =
-                Visitor.visitSymbolStream(ModS.getSymbolArray(), SS.Offset)) {
+        if (opts::Filters.SymbolOffset) {
+          CVSymbolVisitor::FilterOptions Filter;
+          Filter.SymbolOffset = opts::Filters.SymbolOffset;
+          Filter.ParentRecursiveDepth = opts::Filters.ParentRecurseDepth;
+          Filter.ChildRecursiveDepth = opts::Filters.ChildrenRecurseDepth;
+          if (auto EC = Visitor.visitSymbolStreamFiltered(ModS.getSymbolArray(),
+                                                          Filter)) {
+            P.formatLine("Error while processing symbol records.  {0}",
+                         toString(std::move(EC)));
+            return EC;
+          }
+        } else if (auto EC = Visitor.visitSymbolStream(ModS.getSymbolArray(),
+                                                       SS.Offset)) {
           P.formatLine("Error while processing symbol records.  {0}",
                        toString(std::move(EC)));
           return EC;
         }
         return Error::success();
       });
 }
 

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<uint32_t> DumpSymbolOffset(
+    "symbol-offset", cl::Optional,
+    cl::desc("only dump symbol record with the specified symbol offset"),
+    cl::cat(SymbolOptions), cl::sub(DumpSubcommand));
+cl::opt<bool> DumpParents("show-parents",
+                          cl::desc("dump the symbols record's all parents."),
+                          cl::cat(SymbolOptions), cl::sub(DumpSubcommand));
+cl::opt<uint32_t>
+    DumpParentDepth("parent-recurse-depth", cl::Optional, cl::init(-1U),
+                    cl::desc("only recurse to a depth of N when displaying "
+                             "parents of a symbol record."),
+                    cl::cat(SymbolOptions), cl::sub(DumpSubcommand));
+cl::opt<bool> DumpChildren("show-children",
+                           cl::desc("dump the symbols record's all children."),
+                           cl::cat(SymbolOptions), cl::sub(DumpSubcommand));
+cl::opt<uint32_t>
+    DumpChildrenDepth("children-recurse-depth", cl::Optional, cl::init(-1U),
+                      cl::desc("only recurse to a depth of N when displaying "
+                               "children of a symbol record."),
+                      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(
int main(int Argc, const char **Argv) {
   opts::Filters.SizeThreshold = opts::pretty::SizeThreshold;
   opts::Filters.JustMyCode = opts::dump::JustMyCode;
   if (opts::dump::DumpModi.getNumOccurrences() > 0) {
     if (opts::dump::DumpModi.getNumOccurrences() != 1) {
       errs() << "argument '-modi' specified more than once.\n";
       errs().flush();
       exit(1);
     }
-    opts::Filters.NumOccurrences = opts::dump::DumpModi.getNumOccurrences();
     opts::Filters.DumpModi = opts::dump::DumpModi;
   }
+  if (opts::dump::DumpSymbolOffset) {
+    if (!opts::Filters.DumpModi) {
+      errs()
+          << "need to specify argument '-modi' when using '-symbol-offset'.\n";
+      errs().flush();
+      exit(1);
+    }
+    opts::Filters.SymbolOffset = opts::dump::DumpSymbolOffset;
+    if (opts::dump::DumpParents)
+      opts::Filters.ParentRecurseDepth = opts::dump::DumpParentDepth;
+    if (opts::dump::DumpChildren)
+      opts::Filters.ChildrenRecurseDepth = opts::dump::DumpChildrenDepth;
+  }
 
   if (opts::PdbToYamlSubcommand) {
     pdb2Yaml(opts::pdb2yaml::InputFilename.front());
   } else if (opts::YamlToPdbSubcommand) {
     if (opts::yaml2pdb::YamlPdbOutputFile.empty()) {
       SmallString<16> OutputFilename(opts::yaml2pdb::InputFilename.getValue());
       sys::path::replace_extension(OutputFilename, ".pdb");
       opts::yaml2pdb::YamlPdbOutputFile = std::string(OutputFilename.str());