LLVM  10.0.0svn
Minidump.h
Go to the documentation of this file.
1 //===- Minidump.h - Minidump object file implementation ---------*- 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 #ifndef LLVM_OBJECT_MINIDUMP_H
10 #define LLVM_OBJECT_MINIDUMP_H
11 
12 #include "llvm/ADT/DenseMap.h"
13 #include "llvm/ADT/StringExtras.h"
14 #include "llvm/ADT/iterator.h"
16 #include "llvm/Object/Binary.h"
17 #include "llvm/Support/Error.h"
18 
19 namespace llvm {
20 namespace object {
21 
22 /// A class providing access to the contents of a minidump file.
23 class MinidumpFile : public Binary {
24 public:
25  /// Construct a new MinidumpFile object from the given memory buffer. Returns
26  /// an error if this file cannot be identified as a minidump file, or if its
27  /// contents are badly corrupted (i.e. we cannot read the stream directory).
29 
30  static bool classof(const Binary *B) { return B->isMinidump(); }
31 
32  /// Returns the contents of the minidump header.
33  const minidump::Header &header() const { return Header; }
34 
35  /// Returns the list of streams (stream directory entries) in this file.
36  ArrayRef<minidump::Directory> streams() const { return Streams; }
37 
38  /// Returns the raw contents of the stream given by the directory entry.
40  return getData().slice(Stream.Location.RVA, Stream.Location.DataSize);
41  }
42 
43  /// Returns the raw contents of the stream of the given type, or None if the
44  /// file does not contain a stream of this type.
46 
47  /// Returns the raw contents of an object given by the LocationDescriptor. An
48  /// error is returned if the descriptor points outside of the minidump file.
51  return getDataSlice(getData(), Desc.RVA, Desc.DataSize);
52  }
53 
54  /// Returns the minidump string at the given offset. An error is returned if
55  /// we fail to parse the string, or the string is invalid UTF16.
57 
58  /// Returns the contents of the SystemInfo stream, cast to the appropriate
59  /// type. An error is returned if the file does not contain this stream, or
60  /// the stream is smaller than the size of the SystemInfo structure. The
61  /// internal consistency of the stream is not checked in any way.
63  return getStream<minidump::SystemInfo>(minidump::StreamType::SystemInfo);
64  }
65 
66  /// Returns the module list embedded in the ModuleList stream. An error is
67  /// returned if the file does not contain this stream, or if the stream is
68  /// not large enough to contain the number of modules declared in the stream
69  /// header. The consistency of the Module entries themselves is not checked in
70  /// any way.
72  return getListStream<minidump::Module>(minidump::StreamType::ModuleList);
73  }
74 
75  /// Returns the thread list embedded in the ThreadList stream. An error is
76  /// returned if the file does not contain this stream, or if the stream is
77  /// not large enough to contain the number of threads declared in the stream
78  /// header. The consistency of the Thread entries themselves is not checked in
79  /// any way.
81  return getListStream<minidump::Thread>(minidump::StreamType::ThreadList);
82  }
83 
84  /// Returns the contents of the Exception stream. An error is returned if the
85  /// file does not contain this stream, or the stream is smaller than the size
86  /// of the ExceptionStream structure. The internal consistency of the stream
87  /// is not checked in any way.
89  return getStream<minidump::ExceptionStream>(
90  minidump::StreamType::Exception);
91  }
92 
93  /// Returns the list of descriptors embedded in the MemoryList stream. The
94  /// descriptors provide the content of interesting regions of memory at the
95  /// time the minidump was taken. An error is returned if the file does not
96  /// contain this stream, or if the stream is not large enough to contain the
97  /// number of memory descriptors declared in the stream header. The
98  /// consistency of the MemoryDescriptor entries themselves is not checked in
99  /// any way.
101  return getListStream<minidump::MemoryDescriptor>(
102  minidump::StreamType::MemoryList);
103  }
104 
106  : public iterator_facade_base<MemoryInfoIterator,
107  std::forward_iterator_tag,
108  minidump::MemoryInfo> {
109  public:
110  MemoryInfoIterator(ArrayRef<uint8_t> Storage, size_t Stride)
111  : Storage(Storage), Stride(Stride) {
112  assert(Storage.size() % Stride == 0);
113  }
114 
115  bool operator==(const MemoryInfoIterator &R) const {
116  return Storage.size() == R.Storage.size();
117  }
118 
120  assert(Storage.size() >= sizeof(minidump::MemoryInfo));
121  return *reinterpret_cast<const minidump::MemoryInfo *>(Storage.data());
122  }
123 
125  Storage = Storage.drop_front(Stride);
126  return *this;
127  }
128 
129  private:
130  ArrayRef<uint8_t> Storage;
131  size_t Stride;
132  };
133 
134  /// Returns the list of descriptors embedded in the MemoryInfoList stream. The
135  /// descriptors provide properties (e.g. permissions) of interesting regions
136  /// of memory at the time the minidump was taken. An error is returned if the
137  /// file does not contain this stream, or if the stream is not large enough to
138  /// contain the number of memory descriptors declared in the stream header.
139  /// The consistency of the MemoryInfoList entries themselves is not checked
140  /// in any way.
142 
143 private:
144  static Error createError(StringRef Str) {
145  return make_error<GenericBinaryError>(Str, object_error::parse_failed);
146  }
147 
148  static Error createEOFError() {
149  return make_error<GenericBinaryError>("Unexpected EOF",
151  }
152 
153  /// Return a slice of the given data array, with bounds checking.
155  size_t Offset, size_t Size);
156 
157  /// Return the slice of the given data array as an array of objects of the
158  /// given type. The function checks that the input array is large enough to
159  /// contain the correct number of objects of the given type.
160  template <typename T>
161  static Expected<ArrayRef<T>> getDataSliceAs(ArrayRef<uint8_t> Data,
162  size_t Offset, size_t Count);
163 
164  MinidumpFile(MemoryBufferRef Source, const minidump::Header &Header,
167  : Binary(ID_Minidump, Source), Header(Header), Streams(Streams),
168  StreamMap(std::move(StreamMap)) {}
169 
170  ArrayRef<uint8_t> getData() const {
171  return arrayRefFromStringRef(Data.getBuffer());
172  }
173 
174  /// Return the stream of the given type, cast to the appropriate type. Checks
175  /// that the stream is large enough to hold an object of this type.
176  template <typename T>
177  Expected<const T &> getStream(minidump::StreamType Stream) const;
178 
179  /// Return the contents of a stream which contains a list of fixed-size items,
180  /// prefixed by the list size.
181  template <typename T>
182  Expected<ArrayRef<T>> getListStream(minidump::StreamType Stream) const;
183 
184  const minidump::Header &Header;
187 };
188 
189 template <typename T>
190 Expected<const T &> MinidumpFile::getStream(minidump::StreamType Type) const {
191  if (Optional<ArrayRef<uint8_t>> Stream = getRawStream(Type)) {
192  if (Stream->size() >= sizeof(T))
193  return *reinterpret_cast<const T *>(Stream->data());
194  return createEOFError();
195  }
196  return createError("No such stream");
197 }
198 
199 template <typename T>
200 Expected<ArrayRef<T>> MinidumpFile::getDataSliceAs(ArrayRef<uint8_t> Data,
201  size_t Offset,
202  size_t Count) {
203  // Check for overflow.
204  if (Count > std::numeric_limits<size_t>::max() / sizeof(T))
205  return createEOFError();
207  getDataSlice(Data, Offset, sizeof(T) * Count);
208  if (!Slice)
209  return Slice.takeError();
210  return ArrayRef<T>(reinterpret_cast<const T *>(Slice->data()), Count);
211 }
212 
213 } // end namespace object
214 } // end namespace llvm
215 
216 #endif // LLVM_OBJECT_MINIDUMP_H
MemoryInfoIterator(ArrayRef< uint8_t > Storage, size_t Stride)
Definition: Minidump.h:110
Expected< const minidump::ExceptionStream & > getExceptionStream() const
Returns the contents of the Exception stream.
Definition: Minidump.h:88
static bool classof(const Binary *B)
Definition: Minidump.h:30
This class represents lattice values for constants.
Definition: AllocatorList.h:23
Specifies the location (and size) of various objects in the minidump file.
Definition: Minidump.h:59
ArrayRef< uint8_t > arrayRefFromStringRef(StringRef Input)
Construct a string ref from an array ref of unsigned chars.
Definition: StringExtras.h:60
Error takeError()
Take ownership of the stored error.
Definition: Error.h:552
ArrayRef< minidump::Directory > streams() const
Returns the list of streams (stream directory entries) in this file.
Definition: Minidump.h:36
Expected< std::string > getString(size_t Offset) const
Returns the minidump string at the given offset.
Definition: Minidump.cpp:25
StreamType
The type of a minidump stream identifies its contents.
Definition: Minidump.h:50
const minidump::MemoryInfo & operator*() const
Definition: Minidump.h:119
const minidump::Header & header() const
Returns the contents of the minidump header.
Definition: Minidump.h:33
Tagged union holding either a T or a Error.
Definition: yaml2obj.h:21
The minidump header is the first part of a minidump file.
Definition: Minidump.h:32
Expected< const minidump::SystemInfo & > getSystemInfo() const
Returns the contents of the SystemInfo stream, cast to the appropriate type.
Definition: Minidump.h:62
Expected< ArrayRef< minidump::Module > > getModuleList() const
Returns the module list embedded in the ModuleList stream.
Definition: Minidump.h:71
ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory)...
Definition: APInt.h:32
CRTP base class which implements the entire standard iterator facade in terms of a minimal subset of ...
Definition: iterator.h:67
static Expected< std::unique_ptr< MinidumpFile > > create(MemoryBufferRef Source)
Construct a new MinidumpFile object from the given memory buffer.
Definition: Minidump.cpp:111
static GCRegistry::Add< OcamlGC > B("ocaml", "ocaml 3.10-compatible GC")
The instances of the Type class are immutable: once they are created, they are never changed...
Definition: Type.h:46
size_t size() const
size - Get the array size.
Definition: ArrayRef.h:148
Expected< ArrayRef< minidump::MemoryDescriptor > > getMemoryList() const
Returns the list of descriptors embedded in the MemoryList stream.
Definition: Minidump.h:100
Expected< ArrayRef< uint8_t > > getRawData(minidump::LocationDescriptor Desc) const
Returns the raw contents of an object given by the LocationDescriptor.
Definition: Minidump.h:50
Expected< ArrayRef< minidump::Thread > > getThreadList() const
Returns the thread list embedded in the ThreadList stream.
Definition: Minidump.h:80
bool operator==(const MemoryInfoIterator &R) const
Definition: Minidump.h:115
ArrayRef< uint8_t > getRawStream(const minidump::Directory &Stream) const
Returns the raw contents of the stream given by the directory entry.
Definition: Minidump.h:39
const T * data() const
Definition: ArrayRef.h:145
Align max(MaybeAlign Lhs, Align Rhs)
Definition: Alignment.h:390
LocationDescriptor Location
Definition: Minidump.h:122
Expected< iterator_range< MemoryInfoIterator > > getMemoryInfoList() const
Returns the list of descriptors embedded in the MemoryInfoList stream.
Definition: Minidump.cpp:57
support::ulittle32_t RVA
Definition: Minidump.h:61
MemoryBufferRef Data
Definition: Binary.h:37
ArrayRef< T > slice(size_t N, size_t M) const
slice(n, m) - Chop off the first N elements of the array, and keep M elements in the array...
Definition: ArrayRef.h:178
support::ulittle32_t DataSize
Definition: Minidump.h:60
ArrayRef< T > drop_front(size_t N=1) const
Drop the first N elements of the array.
Definition: ArrayRef.h:187
Specifies the location and type of a single stream in the minidump file.
Definition: Minidump.h:120
uint32_t Size
Definition: Profile.cpp:46
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
Lightweight error class with error context and mandatory checking.
Definition: Error.h:157
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:48
A class providing access to the contents of a minidump file.
Definition: Minidump.h:23
bool isMinidump() const
Definition: Binary.h:142