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 list of descriptors embedded in the MemoryList stream. The
85  /// descriptors provide the content of interesting regions of memory at the
86  /// time the minidump was taken. An error is returned if the file does not
87  /// contain this stream, or if the stream is not large enough to contain the
88  /// number of memory descriptors declared in the stream header. The
89  /// consistency of the MemoryDescriptor entries themselves is not checked in
90  /// any way.
92  return getListStream<minidump::MemoryDescriptor>(
93  minidump::StreamType::MemoryList);
94  }
95 
97  : public iterator_facade_base<MemoryInfoIterator,
98  std::forward_iterator_tag,
99  minidump::MemoryInfo> {
100  public:
101  MemoryInfoIterator(ArrayRef<uint8_t> Storage, size_t Stride)
102  : Storage(Storage), Stride(Stride) {
103  assert(Storage.size() % Stride == 0);
104  }
105 
106  bool operator==(const MemoryInfoIterator &R) const {
107  return Storage.size() == R.Storage.size();
108  }
109 
111  assert(Storage.size() >= sizeof(minidump::MemoryInfo));
112  return *reinterpret_cast<const minidump::MemoryInfo *>(Storage.data());
113  }
114 
116  Storage = Storage.drop_front(Stride);
117  return *this;
118  }
119 
120  private:
121  ArrayRef<uint8_t> Storage;
122  size_t Stride;
123  };
124 
125  /// Returns the list of descriptors embedded in the MemoryInfoList stream. The
126  /// descriptors provide properties (e.g. permissions) of interesting regions
127  /// of memory at the time the minidump was taken. An error is returned if the
128  /// file does not contain this stream, or if the stream is not large enough to
129  /// contain the number of memory descriptors declared in the stream header.
130  /// The consistency of the MemoryInfoList entries themselves is not checked
131  /// in any way.
133 
134 private:
135  static Error createError(StringRef Str) {
136  return make_error<GenericBinaryError>(Str, object_error::parse_failed);
137  }
138 
139  static Error createEOFError() {
140  return make_error<GenericBinaryError>("Unexpected EOF",
142  }
143 
144  /// Return a slice of the given data array, with bounds checking.
146  size_t Offset, size_t Size);
147 
148  /// Return the slice of the given data array as an array of objects of the
149  /// given type. The function checks that the input array is large enough to
150  /// contain the correct number of objects of the given type.
151  template <typename T>
152  static Expected<ArrayRef<T>> getDataSliceAs(ArrayRef<uint8_t> Data,
153  size_t Offset, size_t Count);
154 
155  MinidumpFile(MemoryBufferRef Source, const minidump::Header &Header,
158  : Binary(ID_Minidump, Source), Header(Header), Streams(Streams),
159  StreamMap(std::move(StreamMap)) {}
160 
161  ArrayRef<uint8_t> getData() const {
162  return arrayRefFromStringRef(Data.getBuffer());
163  }
164 
165  /// Return the stream of the given type, cast to the appropriate type. Checks
166  /// that the stream is large enough to hold an object of this type.
167  template <typename T>
168  Expected<const T &> getStream(minidump::StreamType Stream) const;
169 
170  /// Return the contents of a stream which contains a list of fixed-size items,
171  /// prefixed by the list size.
172  template <typename T>
173  Expected<ArrayRef<T>> getListStream(minidump::StreamType Stream) const;
174 
175  const minidump::Header &Header;
178 };
179 
180 template <typename T>
181 Expected<const T &> MinidumpFile::getStream(minidump::StreamType Type) const {
182  if (Optional<ArrayRef<uint8_t>> Stream = getRawStream(Type)) {
183  if (Stream->size() >= sizeof(T))
184  return *reinterpret_cast<const T *>(Stream->data());
185  return createEOFError();
186  }
187  return createError("No such stream");
188 }
189 
190 template <typename T>
191 Expected<ArrayRef<T>> MinidumpFile::getDataSliceAs(ArrayRef<uint8_t> Data,
192  size_t Offset,
193  size_t Count) {
194  // Check for overflow.
195  if (Count > std::numeric_limits<size_t>::max() / sizeof(T))
196  return createEOFError();
198  getDataSlice(Data, Offset, sizeof(T) * Count);
199  if (!Slice)
200  return Slice.takeError();
201  return ArrayRef<T>(reinterpret_cast<const T *>(Slice->data()), Count);
202 }
203 
204 } // end namespace object
205 } // end namespace llvm
206 
207 #endif // LLVM_OBJECT_MINIDUMP_H
MemoryInfoIterator(ArrayRef< uint8_t > Storage, size_t Stride)
Definition: Minidump.h:101
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:110
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:91
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:106
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